Cleanup: doxy comments

Use doxy references to function and enums,
also correct some names which became out of sync.

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);