Cleanup: use doxygen comments & sections for animation files

3 files changed, 129 insertions, 85 deletions

diff --git a/source/blender/editors/animation/anim_intern.h b/source/blender/editors/animation/anim_intern.h
index e7277c51cd3..8d8d624c69b 100644
--- a/source/blender/editors/animation/anim_intern.h
+++ b/source/blender/editors/animation/anim_intern.h
@@ -14,49 +14,80 @@ extern ListBase builtin_keyingsets;
 
 /* Operator Define Prototypes ------------------- */
 
-/* Main Keyframe Management operators:
- * These handle keyframes management from various spaces. They only make use of
- * Keying Sets.
- */
+/* -------------------------------------------------------------------- */
+/** \name Main Keyframe Management operators
+ *
+ * These handle keyframes management from various spaces.
+ * They only make use of Keying Sets.
+ * \{ */
+
 void ANIM_OT_keyframe_insert(struct wmOperatorType *ot);
 void ANIM_OT_keyframe_delete(struct wmOperatorType *ot);
 void ANIM_OT_keyframe_insert_by_name(struct wmOperatorType *ot);
 void ANIM_OT_keyframe_delete_by_name(struct wmOperatorType *ot);
 
-/* Main Keyframe Management operators:
- * These handle keyframes management from various spaces. They will handle the menus
- * required for each space.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Main Keyframe Management operators
+ *
+ * These handle keyframes management from various spaces.
+ * They will handle the menus required for each space.
+ * \{ */
+
 void ANIM_OT_keyframe_insert_menu(struct wmOperatorType *ot);
 
 void ANIM_OT_keyframe_delete_v3d(struct wmOperatorType *ot);
 void ANIM_OT_keyframe_clear_v3d(struct wmOperatorType *ot);
 
-/* Keyframe management operators for UI buttons (RMB menu). */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Keyframe management operators for UI buttons (RMB menu)
+ * \{ */
+
 void ANIM_OT_keyframe_insert_button(struct wmOperatorType *ot);
 void ANIM_OT_keyframe_delete_button(struct wmOperatorType *ot);
 void ANIM_OT_keyframe_clear_button(struct wmOperatorType *ot);
 
-/* .......... */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name KeyingSet management operators for UI buttons (RMB menu)
+ * \{ */
 
-/* KeyingSet management operators for UI buttons (RMB menu) */
 void ANIM_OT_keyingset_button_add(struct wmOperatorType *ot);
 void ANIM_OT_keyingset_button_remove(struct wmOperatorType *ot);
 
-/* KeyingSet management operators for RNA collections/UI buttons */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name KeyingSet management operators for RNA collections/UI buttons
+ * \{ */
+
 void ANIM_OT_keying_set_add(struct wmOperatorType *ot);
 void ANIM_OT_keying_set_remove(struct wmOperatorType *ot);
 void ANIM_OT_keying_set_path_add(struct wmOperatorType *ot);
 void ANIM_OT_keying_set_path_remove(struct wmOperatorType *ot);
 
-/* KeyingSet general operators */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name KeyingSet general operators
+ * \{ */
+
 void ANIM_OT_keying_set_active_set(struct wmOperatorType *ot);
 
-/* .......... */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Driver management operators for UI buttons (RMB menu)
+ * \{ */
 
-/* Driver management operators for UI buttons (RMB menu) */
 void ANIM_OT_driver_button_add(struct wmOperatorType *ot);
 void ANIM_OT_driver_button_remove(struct wmOperatorType *ot);
 void ANIM_OT_driver_button_edit(struct wmOperatorType *ot);
 void ANIM_OT_copy_driver_button(struct wmOperatorType *ot);
 void ANIM_OT_paste_driver_button(struct wmOperatorType *ot);
+
+/** \} */
diff --git a/source/blender/editors/animation/keyframing.c b/source/blender/editors/animation/keyframing.c
index feb78ce293e..90c127b620b 100644
--- a/source/blender/editors/animation/keyframing.c
+++ b/source/blender/editors/animation/keyframing.c
@@ -244,7 +244,7 @@ FCurve *ED_action_fcurve_ensure(struct Main *bmain,
   return fcu;
 }
 
-/* Helper for update_autoflags_fcurve() */
+/** Helper for #update_autoflags_fcurve(). */
 static void update_autoflags_fcurve_direct(FCurve *fcu, PropertyRNA *prop)
 {
   /* set additional flags for the F-Curve (i.e. only integer values) */
@@ -304,7 +304,8 @@ void update_autoflags_fcurve(FCurve *fcu, bContext *C, ReportList *reports, Poin
 /* ************************************************** */
 /* KEYFRAME INSERTION */
 
-/* Move the point where a key is about to be inserted to be inside the main cycle range.
+/**
+ * Move the point where a key is about to be inserted to be inside the main cycle range.
  * Returns the type of the cycle if it is enabled and valid.
  */
 static eFCU_Cycle_Type remap_cyclic_keyframe_location(FCurve *fcu, float *px, float *py)
@@ -345,7 +346,7 @@ static eFCU_Cycle_Type remap_cyclic_keyframe_location(FCurve *fcu, float *px, fl
   return type;
 }
 
-/* Used to make curves newly added to a cyclic Action cycle with the correct period. */
+/** Used to make curves newly added to a cyclic Action cycle with the correct period. */
 static void make_new_fcurve_cyclic(const bAction *act, FCurve *fcu)
 {
   /* The curve must contain one (newly-added) keyframe. */
@@ -652,11 +653,13 @@ enum {
   KEYNEEDED_DELNEXT,
 } /*eKeyNeededStatus*/;
 
-/* This helper function determines whether a new keyframe is needed */
-/* Cases where keyframes should not be added:
- * 1. Keyframe to be added between two keyframes with similar values
- * 2. Keyframe to be added on frame where two keyframes are already situated
- * 3. Keyframe lies at point that intersects the linear line between two keyframes
+/**
+ * This helper function determines whether a new keyframe is needed.
+ *
+ * Cases where keyframes should not be added:
+ * 1. Keyframe to be added between two keyframes with similar values.
+ * 2. Keyframe to be added on frame where two keyframes are already situated.
+ * 3. Keyframe lies at point that intersects the linear line between two keyframes.
  */
 static short new_key_needed(FCurve *fcu, float cFrame, float nValue)
 {
@@ -769,7 +772,7 @@ static short new_key_needed(FCurve *fcu, float cFrame, float nValue)
 
 /* ------------------ RNA Data-Access Functions ------------------ */
 
-/* Try to read value using RNA-properties obtained already */
+/** Try to read value using RNA-properties obtained already. */
 static float *setting_get_rna_values(
     PointerRNA *ptr, PropertyRNA *prop, float *buffer, int buffer_size, int *r_count)
 {
@@ -844,7 +847,8 @@ enum {
   VISUALKEY_SCA,
 };
 
-/* This helper function determines if visual-keyframing should be used when
+/**
+ * This helper function determines if visual-keyframing should be used when
  * inserting keyframes for the given channel. As visual-keyframing only works
  * on Object and Pose-Channel blocks, this should only get called for those
  * blocktypes, when using "standard" keying but 'Visual Keying' option in Auto-Keying
@@ -1012,7 +1016,8 @@ static bool visualkey_can_use(PointerRNA *ptr, PropertyRNA *prop)
   return false;
 }
 
-/* This helper function extracts the value to use for visual-keyframing
+/**
+ * This helper function extracts the value to use for visual-keyframing
  * In the event that it is not possible to perform visual keying, try to fall-back
  * to using the default method. Assumes that all data it has been passed is valid.
  */
@@ -1305,7 +1310,7 @@ bool insert_keyframe_direct(ReportList *reports,
   return insert_keyframe_value(reports, &ptr, prop, fcu, anim_eval_context, curval, keytype, flag);
 }
 
-/* Find or create the FCurve based on the given path, and insert the specified value into it. */
+/** Find or create the #FCurve based on the given path, and insert the specified value into it. */
 static bool insert_keyframe_fcurve_value(Main *bmain,
                                          ReportList *reports,
                                          PointerRNA *ptr,
@@ -1829,9 +1834,10 @@ enum {
   COMMONKEY_MODE_DELETE,
 } /*eCommonModifyKey_Modes*/;
 
-/* Polling callback for use with ANIM_*_keyframe() operators
+/**
+ * Polling callback for use with `ANIM_*_keyframe()` operators
  * This is based on the standard ED_operator_areaactive callback,
- * except that it does special checks for a few spacetypes too...
+ * except that it does special checks for a few space-types too.
  */
 static bool modify_key_op_poll(bContext *C)
 {
diff --git a/source/blender/editors/include/ED_anim_api.h b/source/blender/editors/include/ED_anim_api.h
index 4b6f5e4cac6..3402d45fa96 100644
--- a/source/blender/editors/include/ED_anim_api.h
+++ b/source/blender/editors/include/ED_anim_api.h
@@ -51,8 +51,9 @@ struct PropertyRNA;
 /** \name Context
  * \{ */
 
-/* This struct defines a structure used for animation-specific
- * 'context' information
+/**
+ * This struct defines a structure used for animation-specific
+ * 'context' information.
  */
 typedef struct bAnimContext {
   /** data to be filtered for use in animation editor */
@@ -118,8 +119,9 @@ typedef enum eAnimCont_Types {
 /** \name Channels
  * \{ */
 
-/* This struct defines a structure used for quick and uniform access for
- * channels of animation data
+/**
+ * This struct defines a structure used for quick and uniform access for
+ * channels of animation data.
  */
 typedef struct bAnimListElem {
   struct bAnimListElem *next, *prev;
@@ -257,7 +259,8 @@ typedef enum eAnim_KeyType {
   ALE_GROUP, /* Action Group summary */
 } eAnim_KeyType;
 
-/* Flags for specifying the types of updates (i.e. recalculation/refreshing) that
+/**
+ * Flags for specifying the types of updates (i.e. recalculation/refreshing) that
  * needs to be performed to the data contained in a channel following editing.
  * For use with ANIM_animdata_update()
  */
@@ -379,13 +382,13 @@ typedef enum eAnimFilter_Flags {
 #define EXPANDED_DRVD(adt) ((adt->flag & ADT_DRIVERS_COLLAPSED) == 0)
 
 /* Actions (also used for Dopesheet) */
-/* Action Channel Group */
+/** Action Channel Group. */
 #define EDITABLE_AGRP(agrp) (((agrp)->flag & AGRP_PROTECTED) == 0)
 #define EXPANDED_AGRP(ac, agrp) \
   (((!(ac) || ((ac)->spacetype != SPACE_GRAPH)) && ((agrp)->flag & AGRP_EXPANDED)) || \
    (((ac) && ((ac)->spacetype == SPACE_GRAPH)) && ((agrp)->flag & AGRP_EXPANDED_G)))
 #define SEL_AGRP(agrp) (((agrp)->flag & AGRP_SELECTED) || ((agrp)->flag & AGRP_ACTIVE))
-/* F-Curve Channels */
+/** F-Curve Channels. */
 #define EDITABLE_FCU(fcu) ((fcu->flag & FCURVE_PROTECTED) == 0)
 #define SEL_FCU(fcu) (fcu->flag & FCURVE_SELECTED)
 
@@ -394,16 +397,16 @@ typedef enum eAnimFilter_Flags {
 #define SEL_SHAPEKEY(kb) (kb->flag & KEYBLOCK_SEL)
 
 /* Grease Pencil only */
-/* Grease Pencil datablock settings */
+/** Grease Pencil data-block settings. */
 #define EXPANDED_GPD(gpd) (gpd->flag & GP_DATA_EXPAND)
-/* Grease Pencil Layer settings */
+/** Grease Pencil Layer settings. */
 #define EDITABLE_GPL(gpl) ((gpl->flag & GP_LAYER_LOCKED) == 0)
 #define SEL_GPL(gpl) (gpl->flag & GP_LAYER_SELECT)
 
 /* Mask Only */
-/* Grease Pencil datablock settings */
+/** Grease Pencil data-block settings. */
 #define EXPANDED_MASK(mask) (mask->flag & MASK_ANIMF_EXPAND)
-/* Grease Pencil Layer settings */
+/** Grease Pencil Layer settings. */
 #define EDITABLE_MASK(masklay) ((masklay->flag & MASK_LAYERFLAG_LOCKED) == 0)
 #define SEL_MASKLAY(masklay) (masklay->flag & SELECT)
 
@@ -426,20 +429,20 @@ typedef enum eAnimFilter_Flags {
 /** \name Channel Defines
  * \{ */
 
-/* channel heights */
+/** Channel heights. */
 #define ACHANNEL_FIRST_TOP(ac) \
   (UI_view2d_scale_get_y(&(ac)->region->v2d) * -UI_TIME_SCRUB_MARGIN_Y - ACHANNEL_SKIP)
 #define ACHANNEL_HEIGHT(ac) (0.8f * (ac)->yscale_fac * U.widget_unit)
 #define ACHANNEL_SKIP (0.1f * U.widget_unit)
 #define ACHANNEL_STEP(ac) (ACHANNEL_HEIGHT(ac) + ACHANNEL_SKIP)
-/* Additional offset to give some room at the end. */
+/** Additional offset to give some room at the end. */
 #define ACHANNEL_TOT_HEIGHT(ac, item_amount) \
   (-ACHANNEL_FIRST_TOP(ac) + ACHANNEL_STEP(ac) * (item_amount + 1))
 
-/* channel widths */
+/** Channel widths. */
 #define ACHANNEL_NAMEWIDTH (10 * U.widget_unit)
 
-/* channel toggle-buttons */
+/** Channel toggle-buttons. */
 #define ACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit)
 
 /** \} */
@@ -448,7 +451,7 @@ typedef enum eAnimFilter_Flags {
 /** \name NLA Channel Defines
  * \{ */
 
-/* NLA channel heights */
+/** NLA channel heights */
 #define NLACHANNEL_FIRST_TOP(ac) \
   (UI_view2d_scale_get_y(&(ac)->region->v2d) * -UI_TIME_SCRUB_MARGIN_Y - NLACHANNEL_SKIP)
 #define NLACHANNEL_HEIGHT(snla) \
@@ -456,14 +459,14 @@ typedef enum eAnimFilter_Flags {
                                                      (1.2f * U.widget_unit))
 #define NLACHANNEL_SKIP (0.1f * U.widget_unit)
 #define NLACHANNEL_STEP(snla) (NLACHANNEL_HEIGHT(snla) + NLACHANNEL_SKIP)
-/* Additional offset to give some room at the end. */
+/** Additional offset to give some room at the end. */
 #define NLACHANNEL_TOT_HEIGHT(ac, item_amount) \
   (-NLACHANNEL_FIRST_TOP(ac) + NLACHANNEL_STEP(((SpaceNla *)(ac)->sl)) * (item_amount + 1))
 
-/* channel widths */
+/** Channel widths */
 #define NLACHANNEL_NAMEWIDTH (10 * U.widget_unit)
 
-/* channel toggle-buttons */
+/** Channel toggle-buttons */
 #define NLACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit)
 
 /** \} */
@@ -521,7 +524,7 @@ void ANIM_animdata_freelist(ListBase *anim_data);
 /** \name Drawing TypeInfo
  * \{ */
 
-/* role or level of animchannel in the hierarchy */
+/** Role or level of anim-channel in the hierarchy. */
 typedef enum eAnimChannel_Role {
   /** datablock expander - a "composite" channel type */
   ACHANNEL_ROLE_EXPANDER = -1,
@@ -561,7 +564,7 @@ typedef enum eAnimChannel_Settings {
   ACHANNEL_SETTING_ALWAYS_VISIBLE = 8,
 } eAnimChannel_Settings;
 
-/* Drawing, mouse handling, and flag setting behavior... */
+/** Drawing, mouse handling, and flag setting behavior. */
 typedef struct bAnimChannelType {
   /* -- Type data -- */
   /* name of the channel type, for debugging */
@@ -570,30 +573,31 @@ typedef struct bAnimChannelType {
   eAnimChannel_Role channel_role;
 
   /* -- Drawing -- */
-  /* get RGB color that is used to draw the majority of the backdrop */
+  /** Get RGB color that is used to draw the majority of the backdrop. */
   void (*get_backdrop_color)(bAnimContext *ac, bAnimListElem *ale, float r_color[3]);
-  /* draw backdrop strip for channel */
+  /** Draw backdrop strip for channel. */
   void (*draw_backdrop)(bAnimContext *ac, bAnimListElem *ale, float yminc, float ymaxc);
-  /* get depth of indention (relative to the depth channel is nested at) */
+  /** Get depth of indention (relative to the depth channel is nested at). */
   short (*get_indent_level)(bAnimContext *ac, bAnimListElem *ale);
-  /* get offset in pixels for the start of the channel (in addition to the indent depth) */
+  /** Get offset in pixels for the start of the channel (in addition to the indent depth). */
   short (*get_offset)(bAnimContext *ac, bAnimListElem *ale);
 
-  /* get name (for channel lists) */
+  /** Get name (for channel lists). */
   void (*name)(bAnimListElem *ale, char *name);
-  /* get RNA property+pointer for editing the name */
+  /** Get RNA property+pointer for editing the name. */
   bool (*name_prop)(bAnimListElem *ale, struct PointerRNA *ptr, struct PropertyRNA **prop);
-  /* get icon (for channel lists) */
+  /** Get icon (for channel lists). */
   int (*icon)(bAnimListElem *ale);
 
   /* -- Settings -- */
-  /* check if the given setting is valid in the current context */
+  /** Check if the given setting is valid in the current context. */
   bool (*has_setting)(bAnimContext *ac, bAnimListElem *ale, eAnimChannel_Settings setting);
-  /* get the flag used for this setting */
+  /** Get the flag used for this setting. */
   int (*setting_flag)(bAnimContext *ac, eAnimChannel_Settings setting, bool *neg);
-  /* get the pointer to int/short where data is stored,
-   * with type being  sizeof(ptr_data) which should be fine for runtime use...
-   * - assume that setting has been checked to be valid for current context
+  /**
+   * Get the pointer to int/short where data is stored,
+   * with type being `sizeof(ptr_data)` which should be fine for runtime use.
+   * - assume that setting has been checked to be valid for current context.
    */
   void *(*setting_ptr)(bAnimListElem *ale, eAnimChannel_Settings setting, short *type);
 } bAnimChannelType;
@@ -720,11 +724,11 @@ bool ANIM_remove_empty_action_from_animdata(struct AnimData *adt);
 
 /* flags for Current Frame Drawing */
 typedef enum eAnimEditDraw_CurrentFrame {
-  /* plain time indicator with no special indicators */
+  /** Plain time indicator with no special indicators. */
   /* DRAWCFRA_PLAIN = 0, */ /* UNUSED */
-  /* time indication in seconds or frames */
+  /** Time indication in seconds or frames. */
   DRAWCFRA_UNIT_SECONDS = (1 << 0),
-  /* draw indicator extra wide (for timeline) */
+  /** Draw indicator extra wide (for timeline). */
   DRAWCFRA_WIDE = (1 << 1),
 } eAnimEditDraw_CurrentFrame;
 
@@ -784,9 +788,9 @@ struct NlaTrack *ANIM_nla_context_track(const struct bContext *C);
 struct NlaStrip *ANIM_nla_context_strip(const struct bContext *C);
 struct FCurve *ANIM_graph_context_fcurve(const struct bContext *C);
 
-/* Needed for abstraction between the graph editor and the NLA editor. */
+/** Needed for abstraction between the graph editor and the NLA editor. */
 typedef bool (*PanelTypePollFn)(const struct bContext *C, struct PanelType *pt);
-/* Avoid including "UI_interface.h" here. */
+/** Avoid including `UI_interface.h` here. */
 typedef void (*uiListPanelIDFromDataFunc)(void *data_link, char *r_idname);
 
 /**
@@ -912,20 +916,21 @@ void ED_nla_postop_refresh(bAnimContext *ac);
 
 /* anim_draw.c */
 
-/* flags for conversion mapping */
+/** Flags for conversion mapping. */
 typedef enum eAnimUnitConv_Flags {
-  /* restore to original internal values */
+  /** Restore to original internal values. */
   ANIM_UNITCONV_RESTORE = (1 << 0),
-  /* ignore handles (i.e. only touch main keyframes) */
+  /** Ignore handles (i.e. only touch main keyframes). */
   ANIM_UNITCONV_ONLYKEYS = (1 << 1),
-  /* only touch selected BezTriples */
+  /** Only touch selected BezTriples. */
   ANIM_UNITCONV_ONLYSEL = (1 << 2),
-  /* only touch selected vertices */
+  /** Only touch selected vertices. */
   ANIM_UNITCONV_SELVERTS = (1 << 3),
   /* ANIM_UNITCONV_SKIPKNOTS = (1 << 4), */ /* UNUSED */
-  /* Scale FCurve i a way it fits to -1..1 space */
+  /** Scale FCurve i a way it fits to -1..1 space. */
   ANIM_UNITCONV_NORMALIZE = (1 << 5),
-  /* Only when normalization is used: use scale factor from previous run,
+  /**
+   * Only when normalization is used: use scale factor from previous run,
    * prevents curves from jumping all over the place when tweaking them.
    */
   ANIM_UNITCONV_NORMALIZE_FREEZE = (1 << 6),
@@ -953,10 +958,11 @@ float ANIM_unit_mapping_get_factor(
  */
 #define BEZKEYTYPE(bezt) ((bezt)->hide)
 
-/* set/clear/toggle macro
- * - channel - channel with a 'flag' member that we're setting
- * - smode - 0=clear, 1=set, 2=invert
- * - sflag - bitflag to set
+/**
+ * Set/Clear/Toggle macro.
+ * \param channel: Channel with a 'flag' member that we're setting.
+ * \param smode: 0=clear, 1=set, 2=invert.
+ * \param sflag: bit-flag to set.
  */
 #define ACHANNEL_SET_FLAG(channel, smode, sflag) \
   { \
@@ -972,10 +978,11 @@ float ANIM_unit_mapping_get_factor(
   } \
   ((void)0)
 
-/* set/clear/toggle macro, where the flag is negative
- * - channel - channel with a 'flag' member that we're setting
- * - smode - 0=clear, 1=set, 2=invert
- * - sflag - bitflag to set
+/**
+ * Set/Clear/Toggle macro, where the flag is negative.
+ * \param channel: channel with a 'flag' member that we're setting.
+ * \param smode: 0=clear, 1=set, 2=invert.
+ * \param sflag: Bit-flag to set.
  */
 #define ACHANNEL_SET_FLAG_NEG(channel, smode, sflag) \
   { \
@@ -1067,13 +1074,13 @@ void ED_drivers_editor_init(struct bContext *C, struct ScrArea *area);
 /* ************************************************ */
 
 typedef enum eAnimvizCalcRange {
-  /* Update motion paths at the current frame only. */
+  /** Update motion paths at the current frame only. */
   ANIMVIZ_CALC_RANGE_CURRENT_FRAME,
 
-  /* Try to limit updates to a close neighborhood of the current frame. */
+  /** Try to limit updates to a close neighborhood of the current frame. */
   ANIMVIZ_CALC_RANGE_CHANGED,
 
-  /* Update an entire range of the motion paths. */
+  /** Update an entire range of the motion paths. */
   ANIMVIZ_CALC_RANGE_FULL,
 } eAnimvizCalcRange;