diff options
author | Campbell Barton <ideasman42@gmail.com> | 2019-04-14 11:48:42 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2019-04-14 11:48:42 +0300 |
commit | eff8cc9cccdaa7248d9d869473704e9db69c2f41 (patch) | |
tree | 95c67fbd688b1f63dfef77372a7eaeb40aa15ec5 /source/blender/editors | |
parent | b7e5433890debe629a0677473ba920f743de3342 (diff) |
Cleanup: doxy comments
Use doxy references to function and enums,
also correct some names which became out of sync.
Diffstat (limited to 'source/blender/editors')
18 files changed, 91 insertions, 71 deletions
diff --git a/source/blender/editors/animation/keyframes_general.c b/source/blender/editors/animation/keyframes_general.c index d186a0bb757..c9e672a111d 100644 --- a/source/blender/editors/animation/keyframes_general.c +++ b/source/blender/editors/animation/keyframes_general.c @@ -64,9 +64,10 @@ /* **************************************************** */ -/* Only delete the nominated keyframe from provided F-Curve. +/** + * Only delete the nominated keyframe from provided F-Curve. * Not recommended to be used many times successively. For that - * there is delete_fcurve_keys(). + * there is #delete_fcurve_keys(). */ void delete_fcurve_key(FCurve *fcu, int index, bool do_recalc) { diff --git a/source/blender/editors/animation/keyframing.c b/source/blender/editors/animation/keyframing.c index a86538f3cec..bc630040fdd 100644 --- a/source/blender/editors/animation/keyframing.c +++ b/source/blender/editors/animation/keyframing.c @@ -449,13 +449,13 @@ int insert_bezt_fcurve(FCurve *fcu, const BezTriple *bezt, eInsertKeyFlags flag) } /** - * This function is a wrapper for insert_bezt_fcurve_internal(), and should be used when + * This function is a wrapper for #insert_bezt_fcurve(), and should be used when * adding a new keyframe to a curve, when the keyframe doesn't exist anywhere else yet. * It returns the index at which the keyframe was added. * - * \param keyframe_type: The type of keyframe (eBezTriple_KeyframeType) + * \param keyframe_type: The type of keyframe (#eBezTriple_KeyframeType). * \param flag: Optional flags (eInsertKeyFlags) for controlling how keys get added - * and/or whether updates get done + * and/or whether updates get done. */ int insert_vert_fcurve(FCurve *fcu, float x, float y, eBezTriple_KeyframeType keyframe_type, eInsertKeyFlags flag) { diff --git a/source/blender/editors/armature/armature_utils.c b/source/blender/editors/armature/armature_utils.c index 6b09912064e..465209eb9c5 100644 --- a/source/blender/editors/armature/armature_utils.c +++ b/source/blender/editors/armature/armature_utils.c @@ -547,13 +547,16 @@ EditBone *make_boneList(ListBase *edbo, ListBase *bones, struct Bone *actBone) return active; } -/* This function: - * - sets local head/tail rest locations using parent bone's arm_mat. - * - calls BKE_armature_where_is_bone() which uses parent's transform (arm_mat) to define this bone's transform. - * - fixes (converts) EditBone roll into Bone roll. - * - calls again BKE_armature_where_is_bone(), since roll fiddling may have changed things for our bone... - * Note that order is crucial here, we can only handle child if all its parents in chain have already been handled - * (this is ensured by recursive process). */ +/** + * This function: + * - Sets local head/tail rest locations using parent bone's arm_mat. + * - Calls #BKE_armature_where_is_bone() which uses parent's transform (arm_mat) to define this bone's transform. + * - Fixes (converts) EditBone roll into Bone roll. + * - Calls again #BKE_armature_where_is_bone(), since roll fiddling may have changed things for our bone... + * + * \note The order is crucial here, we can only handle child + * if all its parents in chain have already been handled (this is ensured by recursive process). + */ static void armature_finalize_restpose(ListBase *bonelist, ListBase *editbonelist) { Bone *curBone; diff --git a/source/blender/editors/curve/editcurve.c b/source/blender/editors/curve/editcurve.c index 10729ecaa5e..4aaf0dc2a2f 100644 --- a/source/blender/editors/curve/editcurve.c +++ b/source/blender/editors/curve/editcurve.c @@ -2697,7 +2697,7 @@ static void smooth_single_bezt( } /** - * Same as smooth_single_bezt(), keep in sync + * Same as #smooth_single_bezt(), keep in sync. */ static void smooth_single_bp( BPoint *bp, diff --git a/source/blender/editors/gpencil/gpencil_utils.c b/source/blender/editors/gpencil/gpencil_utils.c index 44510a3f6ad..f582b52713d 100644 --- a/source/blender/editors/gpencil/gpencil_utils.c +++ b/source/blender/editors/gpencil/gpencil_utils.c @@ -216,7 +216,7 @@ bGPdata *ED_gpencil_data_get_active_direct(ID *screen_id, ScrArea *sa, Scene *sc /** * Get the active Grease Pencil datablock * \note This is the original (bmain) copy of the datablock, stored in files. - * Do not use for reading evaluated copies of GP Objects data + * Do not use for reading evaluated copies of GP Objects data */ bGPdata *ED_gpencil_data_get_active(const bContext *C) { @@ -228,9 +228,9 @@ bGPdata *ED_gpencil_data_get_active(const bContext *C) * Get the evaluated copy of the active Grease Pencil datablock (where applicable) * - For the 3D View (i.e. "GP Objects"), this gives the evaluated copy of the GP datablock * (i.e. a copy of the active GP datablock for the active object, where modifiers have been - * applied). This is needed to correctly work with "Copy-on-Write" + * applied). This is needed to correctly work with "Copy-on-Write". * - For all other editors (i.e. "GP Annotations"), this just gives the active datablock - * like for ED_gpencil_data_get_active() + * like for #ED_gpencil_data_get_active() */ bGPdata *ED_gpencil_data_get_active_evaluated(const bContext *C) { @@ -640,13 +640,13 @@ void gp_point_to_xy( /** * 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. + * 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 + * \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 + * \warning This assumes that the caller has already checked whether the stroke in question can be drawn. */ void gp_point_to_xy_fl( const GP_SpaceConversion *gsc, const bGPDstroke *gps, const bGPDspoint *pt, @@ -808,9 +808,9 @@ bool gp_point_xy_to_3d(const GP_SpaceConversion *gsc, Scene *scene, const float * Convert tGPspoint (temporary 2D/screenspace point data used by GP modal operators) * to 3D coordinates. * - * \param point2D: The screenspace 2D point data to convert - * \param depth: Depth array (via ED_view3d_autodist_depth()) - * \param[out] r_out: The resulting 2D point data + * \param point2D: The screenspace 2D point data to convert. + * \param depth: Depth array (via #ED_view3d_autodist_depth()). + * \param[out] r_out: The resulting 2D point data. */ void gp_stroke_convertcoords_tpoint( Scene *scene, ARegion *ar, diff --git a/source/blender/editors/include/ED_keyframing.h b/source/blender/editors/include/ED_keyframing.h index 51dfa3c7dff..5191978c529 100644 --- a/source/blender/editors/include/ED_keyframing.h +++ b/source/blender/editors/include/ED_keyframing.h @@ -377,11 +377,12 @@ bool fcurve_frame_has_keyframe(struct FCurve *fcu, float frame, short filter); */ bool fcurve_is_changed(struct PointerRNA ptr, struct PropertyRNA *prop, struct FCurve *fcu, float frame); -/* Main Keyframe Checking API call: +/** + * Main Keyframe Checking API call: * Checks whether a keyframe exists for the given ID-block one the given frame. * - It is recommended to call this method over the other keyframe-checkers directly, * in case some detail of the implementation changes... - * - frame: the value of this is quite often result of BKE_scene_frame_get() + * - frame: the value of this is quite often result of #BKE_scene_frame_get() */ bool id_frame_has_keyframe(struct ID *id, float frame, short filter); diff --git a/source/blender/editors/include/ED_numinput.h b/source/blender/editors/include/ED_numinput.h index 5f90996988a..d4cb2110c2c 100644 --- a/source/blender/editors/include/ED_numinput.h +++ b/source/blender/editors/include/ED_numinput.h @@ -72,15 +72,18 @@ enum { struct UnitSettings; -/*********************** NumInput ********************************/ - -/* There are important things to note here for code using numinput: - * * Values passed to applyNumInput() should be valid and are stored as default ones (val_org), if it is not EDITED. - * * bool returned by applyNumInput should be used to decide whether to apply numinput-specific post-process to data. - * * *Once applyNumInput has been called*, hasNumInput returns a valid value to decide whether to use numinput - * as drawstr source or not (i.e. to call outputNumInput). +/* -------------------------------------------------------------------- */ +/** \name NumInput + * \{ */ + +/** + * There are important things to note here for code using numinput: + * - Values passed to #applyNumInput() should be valid and are stored as default ones (val_org), if it is not EDITED. + * - bool returned by #applyNumInput should be used to decide whether to apply numinput-specific post-process to data. + * - Once #applyNumInput has been called, #hasNumInput returns a valid value to decide whether to use numinput + * as drawstr source or not (i.e. to call #outputNumInput). * - * Those two steps have to be separated (so do not use a common call to hasNumInput() to do both in the same time!). + * Those two steps have to be separated (so do not use a common call to #hasNumInput() to do both in the same time!). */ void initNumInput(NumInput *n); @@ -94,4 +97,6 @@ bool handleNumInput(struct bContext *C, NumInput *n, const struct wmEvent *event bool user_string_to_number(bContext *C, const char *str, const struct UnitSettings *unit, int type, double *r_value); +/** \} */ + #endif /* __ED_NUMINPUT_H__ */ diff --git a/source/blender/editors/interface/interface_align.c b/source/blender/editors/interface/interface_align.c index 8e7dc792da6..9e1563e6511 100644 --- a/source/blender/editors/interface/interface_align.c +++ b/source/blender/editors/interface/interface_align.c @@ -260,7 +260,7 @@ static void block_align_proximity_compute(ButAlign *butal, ButAlign *butal_other * Here, BUT 3 RIGHT side would not get 'dragged' to align with BUT 1 RIGHT side, since BUT 3 has not RIGHT neighbor. * So, this function, when called with BUT 1, will 'walk' the whole column in \a side_s1 direction (TOP or DOWN when * called for RIGHT side), and force buttons like BUT 3 to align as needed, if BUT 1 and BUT 3 were detected as needing - * top-right corner stitching in \a block_align_proximity_compute() step. + * top-right corner stitching in #block_align_proximity_compute() step. * * \note To avoid doing this twice, some stitching flags are cleared to break the 'stitching connection' * between neighbors. diff --git a/source/blender/editors/lattice/editlattice_tools.c b/source/blender/editors/lattice/editlattice_tools.c index 0d57b94a493..edb79797c2a 100644 --- a/source/blender/editors/lattice/editlattice_tools.c +++ b/source/blender/editors/lattice/editlattice_tools.c @@ -133,9 +133,9 @@ typedef enum eLattice_FlipAxes { } eLattice_FlipAxes; /** - * Flip midpoint value so that relative distances between midpoint and neighbor-pair is maintained - * ! Assumes that uvw <=> xyz (i.e. axis-aligned index-axes with coordinate-axes) - * - Helper for lattice_flip_exec() + * Flip midpoint value so that relative distances between midpoint and neighbor-pair is maintained. + * Assumes that uvw <=> xyz (i.e. axis-aligned index-axes with coordinate-axes). + * - Helper for #lattice_flip_exec() */ static void lattice_flip_point_value(Lattice *lt, int u, int v, int w, float mid, eLattice_FlipAxes axis) { @@ -151,8 +151,8 @@ static void lattice_flip_point_value(Lattice *lt, int u, int v, int w, float mid } /** - * Swap pairs of lattice points along a specified axis - * - Helper for lattice_flip_exec() + * Swap pairs of lattice points along a specified axis. + * - Helper for #lattice_flip_exec() */ static void lattice_swap_point_pairs(Lattice *lt, int u, int v, int w, float mid, eLattice_FlipAxes axis) { diff --git a/source/blender/editors/space_clip/clip_editor.c b/source/blender/editors/space_clip/clip_editor.c index 79a159bac2e..7cfc5257792 100644 --- a/source/blender/editors/space_clip/clip_editor.c +++ b/source/blender/editors/space_clip/clip_editor.c @@ -578,7 +578,7 @@ void ED_clip_point_stable_pos(SpaceClip *sc, ARegion *ar, float x, float y, floa } /** - * \brief the reverse of ED_clip_point_stable_pos(), gets the marker region coords. + * \brief the reverse of #ED_clip_point_stable_pos(), gets the marker region coords. * better name here? view_to_track / track_to_view or so? */ void ED_clip_point_stable_pos__reverse(SpaceClip *sc, ARegion *ar, const float co[2], float r_co[2]) diff --git a/source/blender/editors/space_text/text_draw.c b/source/blender/editors/space_text/text_draw.c index 87bbefdd365..1b49e637350 100644 --- a/source/blender/editors/space_text/text_draw.c +++ b/source/blender/editors/space_text/text_draw.c @@ -154,14 +154,19 @@ static void format_draw_color(const TextDrawContext *tdc, char formatchar) /************************** draw text *****************************/ -/* Notes on word-wrap +/** + * Notes on word-wrap * -- - * All word-wrap functions follow the algorithm below to maintain consistency. - * line The line to wrap (tabs converted to spaces) - * view_width The maximum number of characters displayable in the region - * This equals region_width/font_width for the region - * wrap_chars Characters that allow wrapping. This equals [' ', '\t', '-'] + * All word-wrap functions follow the algorithm below to maintain consistency: + * - line: + * The line to wrap (tabs converted to spaces) + * - view_width: + * The maximum number of characters displayable in the region + * This equals region_width/font_width for the region + * - wrap_chars: + * Characters that allow wrapping. This equals [' ', '\t', '-'] * + * \code{.py} * def wrap(line, view_width, wrap_chars): * draw_start = 0 * draw_end = view_width @@ -175,6 +180,7 @@ static void format_draw_color(const TextDrawContext *tdc, char formatchar) * draw_end = pos+1 * pos += 1 * print line[draw_start:] + * \encode */ int wrap_width(const SpaceText *st, ARegion *ar) diff --git a/source/blender/editors/space_text/text_format_lua.c b/source/blender/editors/space_text/text_format_lua.c index 7118b8b748a..4b25c5d39a7 100644 --- a/source/blender/editors/space_text/text_format_lua.c +++ b/source/blender/editors/space_text/text_format_lua.c @@ -30,9 +30,10 @@ /* *** Lua Keywords (for format_line) *** */ -/* Checks the specified source string for a Lua keyword (minus boolean & 'nil'). +/** + * Checks the specified source string for a Lua keyword (minus boolean & 'nil'). * This name must start at the beginning of the source string and must be - * followed by a non-identifier (see text_check_identifier(char)) or null char. + * followed by a non-identifier (see #text_check_identifier(char)) or null char. * * If a keyword is found, the length of the matching word is returned. * Otherwise, -1 is returned. @@ -40,7 +41,6 @@ * See: * http://www.lua.org/manual/5.1/manual.html#2.1 */ - static int txtfmt_lua_find_keyword(const char *string) { int i, len; @@ -71,9 +71,10 @@ static int txtfmt_lua_find_keyword(const char *string) return i; } -/* Checks the specified source string for a Lua special name/function. This +/** + * Checks the specified source string for a Lua special name/function. This * name must start at the beginning of the source string and must be followed - * by a non-identifier (see text_check_identifier(char)) or null character. + * by a non-identifier (see *text_check_identifier(char)) or null character. * * If a special name is found, the length of the matching name is returned. * Otherwise, -1 is returned. @@ -81,7 +82,6 @@ static int txtfmt_lua_find_keyword(const char *string) * See: * http://www.lua.org/manual/5.1/manual.html#5.1 */ - static int txtfmt_lua_find_specialvar(const char *string) { int i, len; diff --git a/source/blender/editors/space_text/text_format_pov.c b/source/blender/editors/space_text/text_format_pov.c index da10c8626b5..2435d2f21da 100644 --- a/source/blender/editors/space_text/text_format_pov.c +++ b/source/blender/editors/space_text/text_format_pov.c @@ -30,9 +30,10 @@ /* *** POV Keywords (for format_line) *** */ -/* Checks the specified source string for a POV keyword (minus boolean & 'nil'). +/** + * Checks the specified source string for a POV keyword (minus boolean & 'nil'). * This name must start at the beginning of the source string and must be - * followed by a non-identifier (see text_check_identifier(char)) or null char. + * followed by a non-identifier (see #text_check_identifier(char)) or null char. * * If a keyword is found, the length of the matching word is returned. * Otherwise, -1 is returned. @@ -40,7 +41,6 @@ * See: * http://www.povray.org/documentation/view/3.7.0/212/ */ - static int txtfmt_pov_find_keyword(const char *string) { int i, len; @@ -467,9 +467,10 @@ static int txtfmt_pov_find_reserved_builtins(const char *string) } -/* Checks the specified source string for a POV modifiers. This +/** + * Checks the specified source string for a POV modifiers. This * name must start at the beginning of the source string and must be followed - * by a non-identifier (see text_check_identifier(char)) or null character. + * by a non-identifier (see #text_check_identifier(char)) or null character. * * If a special name is found, the length of the matching name is returned. * Otherwise, -1 is returned. @@ -477,7 +478,6 @@ static int txtfmt_pov_find_reserved_builtins(const char *string) * See: * http://www.povray.org/documentation/view/3.7.0/212/ */ - static int txtfmt_pov_find_specialvar(const char *string) { int i, len; diff --git a/source/blender/editors/space_text/text_format_pov_ini.c b/source/blender/editors/space_text/text_format_pov_ini.c index e41fd94ef49..da69a35f0b0 100644 --- a/source/blender/editors/space_text/text_format_pov_ini.c +++ b/source/blender/editors/space_text/text_format_pov_ini.c @@ -30,9 +30,10 @@ /* *** POV INI Keywords (for format_line) *** */ -/* Checks the specified source string for a POV INI keyword (minus boolean & 'nil'). +/** + * Checks the specified source string for a POV INI keyword (minus boolean & 'nil'). * This name must start at the beginning of the source string and must be - * followed by a non-identifier (see text_check_identifier(char)) or null char. + * followed by a non-identifier (see #text_check_identifier(char)) or null char. * * If a keyword is found, the length of the matching word is returned. * Otherwise, -1 is returned. @@ -40,7 +41,6 @@ * See: * http://www.povray.org/documentation/view/3.7.0/212/ */ - static int txtfmt_ini_find_keyword(const char *string) { int i, len; diff --git a/source/blender/editors/space_text/text_format_py.c b/source/blender/editors/space_text/text_format_py.c index 85c3c4220c0..87b3835ce1e 100644 --- a/source/blender/editors/space_text/text_format_py.c +++ b/source/blender/editors/space_text/text_format_py.c @@ -30,9 +30,10 @@ /* *** Local Functions (for format_line) *** */ -/* Checks the specified source string for a Python built-in function name. This +/** + * Checks the specified source string for a Python built-in function name. This * name must start at the beginning of the source string and must be followed by - * a non-identifier (see text_check_identifier(char)) or null character. + * a non-identifier (see #text_check_identifier(char)) or null character. * * If a built-in function is found, the length of the matching name is returned. * Otherwise, -1 is returned. @@ -40,7 +41,6 @@ * See: * http://docs.python.org/py3k/reference/lexical_analysis.html#keywords */ - static int txtfmt_py_find_builtinfunc(const char *string) { int i, len; diff --git a/source/blender/editors/space_view3d/view3d_iterators.c b/source/blender/editors/space_view3d/view3d_iterators.c index 0054680281b..daa1cd38164 100644 --- a/source/blender/editors/space_view3d/view3d_iterators.c +++ b/source/blender/editors/space_view3d/view3d_iterators.c @@ -79,10 +79,12 @@ typedef struct foreachScreenFace_userData { } foreachScreenFace_userData; -/* Note! - foreach funcs should be called while drawing or directly after - * if not, ED_view3d_init_mats_rv3d() can be used for selection tools +/** + * \note foreach funcs should be called while drawing or directly after + * if not, #ED_view3d_init_mats_rv3d() can be used for selection tools * but would not give correct results with dupli's for eg. which don't - * use the object matrix in the usual way */ + * use the object matrix in the usual way. + */ /* ------------------------------------------------------------------------ */ diff --git a/source/blender/editors/space_view3d/view3d_project.c b/source/blender/editors/space_view3d/view3d_project.c index 760cbb3f3ef..e5f8ac147de 100644 --- a/source/blender/editors/space_view3d/view3d_project.c +++ b/source/blender/editors/space_view3d/view3d_project.c @@ -582,7 +582,7 @@ bool ED_view3d_win_to_3d_on_plane_int( /** * Calculate a 3d difference vector from 2d window offset. - * note that ED_view3d_calc_zfac() must be called first to determine + * note that #ED_view3d_calc_zfac() must be called first to determine * the depth used to calculate the delta. * \param ar: The region (used for the window width and height). * \param mval: The area relative 2d difference (such as event->mval[0] - other_x). diff --git a/source/blender/editors/uvedit/uvedit_ops.c b/source/blender/editors/uvedit/uvedit_ops.c index a4247ec370d..1bcf60077ff 100644 --- a/source/blender/editors/uvedit/uvedit_ops.c +++ b/source/blender/editors/uvedit/uvedit_ops.c @@ -2827,10 +2827,12 @@ static void UV_OT_select_linked_pick(wmOperatorType *ot) /** \name Select Split Operator * \{ */ -/* note: this is based on similar use case to MESH_OT_split(), which has a similar effect +/** + * \note This is based on similar use case to #MESH_OT_split(), which has a similar effect * but in this case they are not joined to begin with (only having the behavior of being joined) - * so its best to call this uv_select_split() instead of just split(), but assigned to the same key - * as MESH_OT_split - Campbell */ + * so its best to call this #uv_select_split() instead of just split(), but assigned to the same key + * as #MESH_OT_split - Campbell. + */ static int uv_select_split_exec(bContext *C, wmOperator *op) { Scene *scene = CTX_data_scene(C); |