From 72c9141a7a56fa4762ac0daae501f1609532506c Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Mon, 19 Jun 2017 09:33:23 +1000 Subject: Cleanup: doxygen comments Also remove duplicate & mismatching comments from grease-pencil header. Keep comments close to implementation to avoid getting out of sync. --- source/blender/editors/armature/armature_naming.c | 4 +- source/blender/editors/gpencil/gpencil_intern.h | 89 +--------------------- source/blender/editors/gpencil/gpencil_utils.c | 62 ++++++++++++--- source/blender/editors/space_image/image_ops.c | 4 +- .../editors/transform/transform_conversions.c | 6 +- .../editors/transform/transform_snap_object.c | 4 +- 6 files changed, 63 insertions(+), 106 deletions(-) (limited to 'source/blender/editors') diff --git a/source/blender/editors/armature/armature_naming.c b/source/blender/editors/armature/armature_naming.c index c928508237d..db4b642fe91 100644 --- a/source/blender/editors/armature/armature_naming.c +++ b/source/blender/editors/armature/armature_naming.c @@ -311,8 +311,8 @@ typedef struct BoneFlipNameData { * This way if we are flipping related bones (e.g., Bone.L, Bone.R) at the same time * all the bones are safely renamed, without conflicting with each other. * - * \param arm Armature the bones belong to - * \param bones ListBase of BoneConflict elems, populated via ED_armature_bones_flip_names_add + * \param arm: Armature the bones belong to + * \param bones_names: List of BoneConflict elems. */ void ED_armature_bones_flip_names(bArmature *arm, ListBase *bones_names) { diff --git a/source/blender/editors/gpencil/gpencil_intern.h b/source/blender/editors/gpencil/gpencil_intern.h index 13af06fd4fd..a3734c56c59 100644 --- a/source/blender/editors/gpencil/gpencil_intern.h +++ b/source/blender/editors/gpencil/gpencil_intern.h @@ -71,75 +71,23 @@ typedef struct GP_SpaceConversion { float mat[4][4]; /* transform matrix on the strokes (introduced in [b770964]) */ } GP_SpaceConversion; - -/** - * Check whether a given stroke segment is inside a circular brush - * - * \param mval The current screen-space coordinates (midpoint) of the brush - * \param mvalo The previous screen-space coordinates (midpoint) of the brush (NOT CURRENTLY USED) - * \param rad The radius of the brush - * - * \param x0, y0 The screen-space x and y coordinates of the start of the stroke segment - * \param x1, y1 The screen-space x and y coordinates of the end of the stroke segment - */ bool gp_stroke_inside_circle(const int mval[2], const int UNUSED(mvalo[2]), int rad, int x0, int y0, int x1, int y1); - -/** - * Init settings for stroke point space conversions - * - * \param[out] r_gsc The space conversion settings struct, populated with necessary params - */ void gp_point_conversion_init(struct bContext *C, GP_SpaceConversion *r_gsc); -/** - * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D) - * - * \param[out] r_x The screen-space x-coordinate of the point - * \param[out] r_y The screen-space y-coordinate of the point - */ void gp_point_to_xy(GP_SpaceConversion *settings, struct bGPDstroke *gps, struct bGPDspoint *pt, int *r_x, int *r_y); -/** - * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D) - * - * Just like gp_point_to_xy(), except the resulting coordinates are floats not ints. - * Use this version to solve "stair-step" artifacts which may arise when roundtripping the calculations. - * - * \param[out] r_x The screen-space x-coordinate of the point - * \param[out] r_y The screen-space y-coordinate of the point - */ void gp_point_to_xy_fl(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt, float *r_x, float *r_y); -/** - * Convert point to parent space - * - * \param pt Original point - * \param diff_mat Matrix with the difference between original parent matrix - * \param[out] r_pt Pointer to new point after apply matrix - */ void gp_point_to_parent_space(bGPDspoint *pt, float diff_mat[4][4], bGPDspoint *r_pt); -/** - * Change points position relative to parent object - */ + void gp_apply_parent(bGPDlayer *gpl, bGPDstroke *gps); -/** - * Change point position relative to parent object - */ + void gp_apply_parent_point(bGPDlayer *gpl, bGPDspoint *pt); -/** - * Convert a screenspace point to a 3D Grease Pencil coordinate. - * - * For use with editing tools where it is easier to perform the operations in 2D, - * and then later convert the transformed points back to 3D. - * - * \param screeN_co The screenspace 2D coordinates to convert to - * \param[out] r_out The resulting 3D coordinates of the input point - */ bool gp_point_xy_to_3d(GP_SpaceConversion *gsc, struct Scene *scene, const float screen_co[2], float r_out[3]); /* Poll Callbacks ------------------------------------ */ @@ -165,43 +113,10 @@ struct GHash *gp_copybuf_validate_colormap(bGPdata *gpd); void gp_stroke_delete_tagged_points(bGPDframe *gpf, bGPDstroke *gps, bGPDstroke *next_stroke, int tag_flags); -/** - * Apply smooth to stroke point - * \param gps Stroke to smooth - * \param i Point index - * \param inf Amount of smoothing to apply - * \param affect_pressure Apply smoothing to pressure values too? - */ bool gp_smooth_stroke(bGPDstroke *gps, int i, float inf, bool affect_pressure); - -/** -* Apply smooth for strength to stroke point -* \param gps Stroke to smooth -* \param i Point index -* \param inf Amount of smoothing to apply -*/ bool gp_smooth_stroke_strength(bGPDstroke *gps, int i, float inf); - -/** -* Apply smooth for thickness to stroke point (use pressure) -* \param gps Stroke to smooth -* \param i Point index -* \param inf Amount of smoothing to apply -*/ bool gp_smooth_stroke_thickness(bGPDstroke *gps, int i, float inf); - -/** - * Subdivide a stroke once, by adding points at the midpoint between each pair of points - * \param gps Stroke data - * \param new_totpoints Total number of points (after subdividing) - */ void gp_subdivide_stroke(bGPDstroke *gps, const int new_totpoints); - -/** -* Add randomness to stroke -* \param gps Stroke data -* \param brush Brush data -*/ void gp_randomize_stroke(bGPDstroke *gps, bGPDbrush *brush); /* Layers Enums -------------------------------------- */ diff --git a/source/blender/editors/gpencil/gpencil_utils.c b/source/blender/editors/gpencil/gpencil_utils.c index 2b662d04f03..ed05b8be9ca 100644 --- a/source/blender/editors/gpencil/gpencil_utils.c +++ b/source/blender/editors/gpencil/gpencil_utils.c @@ -391,7 +391,16 @@ EnumPropertyItem *ED_gpencil_layers_with_new_enum_itemf(bContext *C, PointerRNA /* ******************************************************** */ /* Brush Tool Core */ -/* Check if part of stroke occurs within last segment drawn by eraser */ +/** + * Check whether a given stroke segment is inside a circular brush + * + * \param mval The current screen-space coordinates (midpoint) of the brush + * \param mvalo The previous screen-space coordinates (midpoint) of the brush (NOT CURRENTLY USED) + * \param rad The radius of the brush + * + * \param x0, y0 The screen-space x and y coordinates of the start of the stroke segment + * \param x1, y1 The screen-space x and y coordinates of the end of the stroke segment + */ bool gp_stroke_inside_circle(const int mval[2], const int UNUSED(mvalo[2]), int rad, int x0, int y0, int x1, int y1) { @@ -502,7 +511,11 @@ bGPDpalettecolor *ED_gpencil_stroke_getcolor(bGPdata *gpd, bGPDstroke *gps) /* ******************************************************** */ /* Space Conversion */ -/* Init handling for space-conversion function (from passed-in parameters) */ +/** + * Init settings for stroke point space conversions + * + * \param r_gsc: [out] The space conversion settings struct, populated with necessary params + */ void gp_point_conversion_init(bContext *C, GP_SpaceConversion *r_gsc) { ScrArea *sa = CTX_wm_area(C); @@ -538,7 +551,13 @@ void gp_point_conversion_init(bContext *C, GP_SpaceConversion *r_gsc) } } -/* convert point to parent space */ +/** + * Convert point to parent space + * + * \param pt Original point + * \param diff_mat Matrix with the difference between original parent matrix + * \param[out] r_pt Pointer to new point after apply matrix + */ void gp_point_to_parent_space(bGPDspoint *pt, float diff_mat[4][4], bGPDspoint *r_pt) { float fpt[3]; @@ -547,7 +566,9 @@ void gp_point_to_parent_space(bGPDspoint *pt, float diff_mat[4][4], bGPDspoint * copy_v3_v3(&r_pt->x, fpt); } -/* Change position relative to parent object */ +/** + * Change points position relative to parent object + */ void gp_apply_parent(bGPDlayer *gpl, bGPDstroke *gps) { bGPDspoint *pt; @@ -568,7 +589,9 @@ void gp_apply_parent(bGPDlayer *gpl, bGPDstroke *gps) } } -/* Change point position relative to parent object */ +/** + * Change point position relative to parent object + */ void gp_apply_parent_point(bGPDlayer *gpl, bGPDspoint *pt) { /* undo matrix */ @@ -583,8 +606,13 @@ void gp_apply_parent_point(bGPDlayer *gpl, bGPDspoint *pt) copy_v3_v3(&pt->x, fpt); } -/* Convert Grease Pencil points to screen-space values - * WARNING: This assumes that the caller has already checked whether the stroke in question can be drawn +/** + * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D) + * + * \param[out] r_x The screen-space x-coordinate of the point + * \param[out] r_y The screen-space y-coordinate of the point + * + * \warning This assumes that the caller has already checked whether the stroke in question can be drawn. */ void gp_point_to_xy(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt, int *r_x, int *r_y) @@ -628,8 +656,16 @@ void gp_point_to_xy(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt, } } -/* Convert Grease Pencil points to screen-space values (as floats) - * WARNING: This assumes that the caller has already checked whether the stroke in question can be drawn +/** + * Convert a Grease Pencil coordinate (i.e. can be 2D or 3D) to screenspace (2D) + * + * Just like gp_point_to_xy(), except the resulting coordinates are floats not ints. + * Use this version to solve "stair-step" artifacts which may arise when roundtripping the calculations. + * + * \param r_x: [out] The screen-space x-coordinate of the point + * \param r_y: [out] The screen-space y-coordinate of the point + * + * \warning This assumes that the caller has already checked whether the stroke in question can be drawn */ void gp_point_to_xy_fl(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt, float *r_x, float *r_y) @@ -688,6 +724,12 @@ void gp_point_to_xy_fl(GP_SpaceConversion *gsc, bGPDstroke *gps, bGPDspoint *pt, /** * Project screenspace coordinates to 3D-space * + * For use with editing tools where it is easier to perform the operations in 2D, + * and then later convert the transformed points back to 3D. + * + * \param screen_co: The screenspace 2D coordinates to convert to + * \param r_out: The resulting 3D coordinates of the input point + * * \note We include this as a utility function, since the standard method * involves quite a few steps, which are invariably always the same * for all GPencil operations. So, it's nicer to just centralize these. @@ -722,7 +764,7 @@ bool gp_point_xy_to_3d(GP_SpaceConversion *gsc, Scene *scene, const float screen } /** - * Apply smooth to stroke point + * Apply smooth to stroke point * \param gps Stroke to smooth * \param i Point index * \param inf Amount of smoothing to apply diff --git a/source/blender/editors/space_image/image_ops.c b/source/blender/editors/space_image/image_ops.c index c2cfca295a4..501a5a35899 100644 --- a/source/blender/editors/space_image/image_ops.c +++ b/source/blender/editors/space_image/image_ops.c @@ -1067,6 +1067,7 @@ typedef struct ImageOpenData { typedef struct ImageFrameRange { struct ImageFrameRange *next, *prev; ListBase frames; + /** The full path of the first file in the list of image files */ char filepath[FILE_MAX]; } ImageFrameRange; @@ -1092,8 +1093,7 @@ static void image_open_cancel(bContext *UNUSED(C), wmOperator *op) /** * \brief Get a list of frames from the list of image files matching the first file name sequence pattern * \param ptr [in] the RNA pointer containing the "directory" entry and "files" collection - * \param frames [out] the list of frame numbers found in the files matching the first one by name - * \param path [out] the full path of the first file in the list of image files + * \param frames_all [out] the list of frame numbers found in the files matching the first one by name */ static void image_sequence_get_frame_ranges(PointerRNA *ptr, ListBase *frames_all) { diff --git a/source/blender/editors/transform/transform_conversions.c b/source/blender/editors/transform/transform_conversions.c index dabce262125..ba474e93b70 100644 --- a/source/blender/editors/transform/transform_conversions.c +++ b/source/blender/editors/transform/transform_conversions.c @@ -2008,9 +2008,9 @@ static bool bmesh_test_dist_add( } /** - * \parm mtx: Measure disatnce in this space. - * \parm dists: Store the closest connected distance to selected vertices. - * \parm index: Optionally store the original index we're measuring the distance to (can be NULL). + * \param mtx: Measure disatnce in this space. + * \param dists: Store the closest connected distance to selected vertices. + * \param index: Optionally store the original index we're measuring the distance to (can be NULL). */ static void editmesh_set_connectivity_distance(BMesh *bm, float mtx[3][3], float *dists, int *index) { diff --git a/source/blender/editors/transform/transform_snap_object.c b/source/blender/editors/transform/transform_snap_object.c index b33528b4149..aecd24d4e40 100644 --- a/source/blender/editors/transform/transform_snap_object.c +++ b/source/blender/editors/transform/transform_snap_object.c @@ -234,7 +234,7 @@ static void raycast_all_cb(void *userdata, int index, const BVHTreeRay *ray, BVH /* -------------------------------------------------------------------- */ -/** \Common utilities +/** Common utilities * \{ */ /** @@ -620,7 +620,7 @@ static float dist_aabb_to_plane( /* -------------------------------------------------------------------- */ -/** \Walk DFS +/** Walk DFS * \{ */ typedef void (*Nearest2DGetEdgeVertsCallback)(const int index, const float *v_pair[2], void *data); -- cgit v1.2.3