Cleanup: use doxy sections in graph editor module

7 files changed, 204 insertions, 68 deletions

diff --git a/source/blender/editors/space_graph/graph_buttons.c b/source/blender/editors/space_graph/graph_buttons.c
index 275616f3bcb..7c116a00eae 100644
--- a/source/blender/editors/space_graph/graph_buttons.c
+++ b/source/blender/editors/space_graph/graph_buttons.c
@@ -19,6 +19,8 @@
 
 /** \file
  * \ingroup spgraph
+ *
+ * Graph editor space & buttons.
  */
 
 #include <float.h>
@@ -66,11 +68,11 @@
 
 #include "graph_intern.h" /* own include */
 
-/* ******************* graph editor space & buttons ************** */
-
 #define B_REDR 1
 
-/* -------------- */
+/* -------------------------------------------------------------------- */
+/** \name Internal Utilities
+ * \{ */
 
 static bool graph_panel_context(const bContext *C, bAnimListElem **ale, FCurve **fcu)
 {
@@ -120,7 +122,11 @@ static bool graph_panel_poll(const bContext *C, PanelType *UNUSED(pt))
   return graph_panel_context(C, NULL, NULL);
 }
 
-/* -------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Cursor Header
+ * \{ */
 
 static void graph_panel_cursor_header(const bContext *C, Panel *panel)
 {
@@ -174,7 +180,11 @@ static void graph_panel_cursor(const bContext *C, Panel *panel)
   uiItemO(sub, IFACE_("Cursor Value to Selection"), ICON_NONE, "GRAPH_OT_snap_cursor_value");
 }
 
-/* ******************* active F-Curve ************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Active F-Curve
+ * \{ */
 
 static void graph_panel_properties(const bContext *C, Panel *panel)
 {
@@ -243,7 +253,11 @@ static void graph_panel_properties(const bContext *C, Panel *panel)
   MEM_freeN(ale);
 }
 
-/* ******************* active Keyframe ************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Active Keyframe
+ * \{ */
 
 /* get 'active' keyframe for panel editing */
 static bool get_active_fcurve_keyframe_edit(const FCurve *fcu,
@@ -610,7 +624,11 @@ static void graph_panel_key_properties(const bContext *C, Panel *panel)
   MEM_freeN(ale);
 }
 
-/* ******************* drivers ******************************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Drivers
+ * \{ */
 
 #define B_IPO_DEPCHANGE 10
 
@@ -1320,8 +1338,13 @@ static void graph_panel_drivers_popover(const bContext *C, Panel *panel)
   uiItemO(layout, IFACE_("Show in Drivers Editor"), ICON_DRIVER, "SCREEN_OT_drivers_editor_show");
 }
 
-/* ******************* F-Modifiers ******************************** */
-/* All the drawing code is in editors/animation/fmodifier_ui.c */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name F-Curve Modifiers
+ *
+ * \note All the drawing code is in `editors/animation/fmodifier_ui.c`
+ * \{ */
 
 #define B_FMODIFIER_REDRAW 20
 /** The start of FModifier panels registered for the graph editor. */
@@ -1380,7 +1403,11 @@ static void graph_panel_modifiers(const bContext *C, Panel *panel)
   MEM_freeN(ale);
 }
 
-/* ******************* general ******************************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Registration
+ * \{ */
 
 void graph_buttons_register(ARegionType *art)
 {
@@ -1456,3 +1483,5 @@ void graph_buttons_register(ARegionType *art)
   pt->draw_header = graph_panel_cursor_header;
   BLI_addtail(&art->paneltypes, pt);
 }
+
+/** \} */
diff --git a/source/blender/editors/space_graph/graph_edit.c b/source/blender/editors/space_graph/graph_edit.c
index 1967dfabd21..2afee277847 100644
--- a/source/blender/editors/space_graph/graph_edit.c
+++ b/source/blender/editors/space_graph/graph_edit.c
@@ -19,6 +19,8 @@
 
 /** \file
  * \ingroup spgraph
+ *
+ * Insert duplicate and bake keyframes.
  */
 
 #include <float.h>
@@ -69,9 +71,6 @@
 
 #include "graph_intern.h"
 
-/* ************************************************************************** */
-/* INSERT DUPLICATE AND BAKE KEYFRAMES */
-
 /* -------------------------------------------------------------------- */
 /** \name Insert Keyframes Operator
  * \{ */
diff --git a/source/blender/editors/space_graph/graph_ops.c b/source/blender/editors/space_graph/graph_ops.c
index 32396a70cce..ecafc75fc06 100644
--- a/source/blender/editors/space_graph/graph_ops.c
+++ b/source/blender/editors/space_graph/graph_ops.c
@@ -52,11 +52,13 @@
 /* ************************** view-based operators **********************************/
 /* XXX should these really be here? */
 
-/* Set Cursor --------------------------------------------------------------------- */
-/* The 'cursor' in the Graph Editor consists of two parts:
+/* -------------------------------------------------------------------- */
+/** \name Set Cursor
+ *
+ * The 'cursor' in the Graph Editor consists of two parts:
  * 1) Current Frame Indicator (as per ANIM_OT_change_frame)
  * 2) Value Indicator (stored per Graph Editor instance)
- */
+ * \{ */
 
 static bool graphview_cursor_poll(bContext *C)
 {
@@ -225,7 +227,11 @@ static void GRAPH_OT_cursor_set(wmOperatorType *ot)
   RNA_def_float(ot->srna, "value", 0, -FLT_MAX, FLT_MAX, "Value", "", -100.0f, 100.0f);
 }
 
-/* Hide/Reveal ------------------------------------------------------------ */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Hide/Reveal
+ * \{ */
 
 static int graphview_curves_hide_exec(bContext *C, wmOperator *op)
 {
@@ -413,7 +419,11 @@ static void GRAPH_OT_reveal(wmOperatorType *ot)
   RNA_def_boolean(ot->srna, "select", true, "Select", "");
 }
 
-/* ************************** registration - operator types **********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Registration: operator types
+ * \{ */
 
 void graphedit_operatortypes(void)
 {
@@ -496,7 +506,11 @@ void ED_operatormacros_graph(void)
   RNA_boolean_set(otmacro->ptr, "use_proportional_edit", false);
 }
 
-/* ************************** registration - keymaps **********************************/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Registration: Key-Maps
+ * \{ */
 
 void graphedit_keymap(wmKeyConfig *keyconf)
 {
@@ -514,3 +528,5 @@ void graphedit_keymap(wmKeyConfig *keyconf)
   /* keyframes */
   WM_keymap_ensure(keyconf, "Graph Editor", SPACE_GRAPH, 0);
 }
+
+/** \} */
diff --git a/source/blender/editors/space_graph/graph_select.c b/source/blender/editors/space_graph/graph_select.c
index ffe74e20bdf..03bfd1092c6 100644
--- a/source/blender/editors/space_graph/graph_select.c
+++ b/source/blender/editors/space_graph/graph_select.c
@@ -56,8 +56,9 @@
 
 #include "graph_intern.h"
 
-/* ************************************************************************** */
-/* KEYFRAMES STUFF */
+/* -------------------------------------------------------------------- */
+/** \name Internal Keyframe Utilities
+ * \{ */
 
 /* temp info for caching handle vertices close */
 typedef struct tNearestVertInfo {
@@ -334,14 +335,19 @@ static tNearestVertInfo *find_nearest_fcurve_vert(bAnimContext *ac, const int mv
   return nvi;
 }
 
-/* ******************** Deselect All Operator ***************************** */
-/* This operator works in one of three ways:
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Deselect All Operator
+ *
+ * This operator works in one of three ways:
  * 1) (de)select all (AKEY) - test if select all or deselect all
  * 2) invert all (CTRL-IKEY) - invert selection of all keyframes
  * 3) (de)select all - no testing is done; only for use internal tools as normal function...
- */
+ * \{ */
 
-/* Deselects keyframes in the Graph Editor
+/**
+ * Deselects keyframes in the Graph Editor
  * - This is called by the deselect all operator, as well as other ones!
  *
  * - test: check if select or deselect all
@@ -490,8 +496,12 @@ void GRAPH_OT_select_all(wmOperatorType *ot)
   WM_operator_properties_select_all(ot);
 }
 
-/* ******************** Box Select Operator **************************** */
-/* This operator currently works in one of three ways:
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Box Select Operator
+ *
+ * This operator currently works in one of three ways:
  * -> BKEY     - 1) all keyframes within region are selected (validation with BEZT_OK_REGION)
  * -> ALT-BKEY - depending on which axis of the region was larger...
  *    -> 2) x-axis, so select all frames within frame range (validation with BEZT_OK_FRAMERANGE)
@@ -499,7 +509,7 @@ void GRAPH_OT_select_all(wmOperatorType *ot)
  *          (validation with BEZT_OK_VALUERANGE).
  *
  * The selection backend is also reused for the Lasso and Circle select operators.
- */
+ * \{ */
 
 static rctf initialize_box_select_coords(const bAnimContext *ac, const rctf *rectf_view)
 {
@@ -572,7 +582,8 @@ static void initialize_box_select_key_editing_data(const SpaceGraph *sipo,
   *r_mapping_flag |= ANIM_get_normalization_flags(ac);
 }
 
-/* Box Select only selects keyframes, as overshooting handles often get caught too,
+/**
+ * Box Select only selects keyframes, as overshooting handles often get caught too,
  * which means that they may be inadvertently moved as well. However, incl_handles overrides
  * this, and allow handles to be considered independently too.
  * Also, for convenience, handles should get same status as keyframe (if it was within bounds).
@@ -667,7 +678,8 @@ static bool box_select_graphkeys(bAnimContext *ac,
   return any_key_selection_changed;
 }
 
-/* This function is used to set all the keyframes of a given curve as selectable
+/**
+ * This function is used to set all the keyframes of a given curve as selectable
  * by the "select_cb" function inside of "box_select_graphcurves".
  */
 static short ok_bezier_always_ok(KeyframeEditData *UNUSED(ked), BezTriple *UNUSED(bezt))
@@ -732,11 +744,12 @@ static bool rectf_curve_intersection(
 #undef INSIDE
 #undef BELOW
 
-/* Perform a box selection of the curves themselves. This means this function tries
+/**
+ * Perform a box selection of the curves themselves. This means this function tries
  * to select a curve by sampling it at various points instead of trying to select the
  * keyframes directly.
  * The selection actions done to a curve are actually done on all the keyframes of the curve.
- * NOTE: This function is only called if no keyframe is in the selection area.
+ * \note This function is only called if no keyframe is in the selection area.
  */
 static void box_select_graphcurves(bAnimContext *ac,
                                    const rctf *rectf_view,
@@ -1107,13 +1120,17 @@ void GRAPH_OT_select_circle(wmOperatorType *ot)
   RNA_def_property_flag(prop, PROP_SKIP_SAVE);
 }
 
-/* ******************** Column Select Operator **************************** */
-/* This operator works in one of four ways:
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Column Select Operator
+ *
+ * This operator works in one of four ways:
  * - 1) select all keyframes in the same frame as a selected one  (KKEY)
  * - 2) select all keyframes in the same frame as the current frame marker (CTRL-KKEY)
  * - 3) select all keyframes in the same frame as a selected markers (SHIFT-KKEY)
  * - 4) select all keyframes that occur between selected markers (ALT-KKEY)
- */
+ * \{ */
 
 /* defines for column-select mode */
 static const EnumPropertyItem prop_column_select_types[] = {
@@ -1297,7 +1314,11 @@ void GRAPH_OT_select_column(wmOperatorType *ot)
   ot->prop = RNA_def_enum(ot->srna, "mode", prop_column_select_types, 0, "Mode", "");
 }
 
-/* ******************** Select Linked Operator *********************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Select Linked Operator
+ * \{ */
 
 static int graphkeys_select_linked_exec(bContext *C, wmOperator *UNUSED(op))
 {
@@ -1353,7 +1374,11 @@ void GRAPH_OT_select_linked(wmOperatorType *ot)
   ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 }
 
-/* ******************** Select More/Less Operators *********************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Select More/Less Operators
+ * \{ */
 
 /* Common code to perform selection */
 static void select_moreless_graph_keys(bAnimContext *ac, short mode)
@@ -1467,8 +1492,13 @@ void GRAPH_OT_select_less(wmOperatorType *ot)
   ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 }
 
-/* ******************** Select Left/Right Operator ************************* */
-/* Select keyframes left/right of the current frame indicator */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Select Left/Right Operator
+ *
+ * Select keyframes left/right of the current frame indicator.
+ * \{ */
 
 /* defines for left-right select tool */
 static const EnumPropertyItem prop_graphkeys_leftright_select_types[] = {
@@ -1628,15 +1658,19 @@ void GRAPH_OT_select_leftright(wmOperatorType *ot)
   RNA_def_property_flag(prop, PROP_SKIP_SAVE);
 }
 
-/* ******************** Mouse-Click Select Operator *********************** */
-/* This operator works in one of three ways:
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Mouse-Click Select Operator
+ *
+ * This operator works in one of three ways:
  * - 1) keyframe under mouse - no special modifiers
  * - 2) all keyframes on the same side of current frame indicator as mouse - ALT modifier
  * - 3) column select all keyframes in frame under mouse - CTRL modifier
  *
  * In addition to these basic options, the SHIFT modifier can be used to toggle the
  * selection mode between replacing the selection (without) and inverting the selection (with).
- */
+ * \{ */
 
 /* option 1) select keyframe directly under mouse */
 static int mouse_graph_keys(bAnimContext *ac,
@@ -1888,9 +1922,12 @@ static int graphkeys_mselect_column(bAnimContext *ac,
   return run_modal ? OPERATOR_RUNNING_MODAL : OPERATOR_FINISHED;
 }
 
-/* ------------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Click Select Operator
+ * \{ */
 
-/* handle clicking */
 static int graphkeys_clickselect_exec(bContext *C, wmOperator *op)
 {
   bAnimContext ac;
@@ -1988,4 +2025,4 @@ void GRAPH_OT_clickselect(wmOperatorType *ot)
   RNA_def_property_flag(prop, PROP_SKIP_SAVE);
 }
 
-/* ************************************************************************** */
+/** \} */
diff --git a/source/blender/editors/space_graph/graph_slider_ops.c b/source/blender/editors/space_graph/graph_slider_ops.c
index 14a8f73a3a4..4e62ab2df2d 100644
--- a/source/blender/editors/space_graph/graph_slider_ops.c
+++ b/source/blender/editors/space_graph/graph_slider_ops.c
@@ -17,6 +17,16 @@
  * All rights reserved.
  */
 
+/** \file
+ * \ingroup spgraph
+ *
+ * Graph Slider Operators
+ *
+ * This file contains a collection of operators to modify keyframes in the graph editor.
+ * All operators are modal and use a slider that allows the user to define a percentage
+ * to modify the operator.
+ */
+
 #include <float.h>
 #include <string.h>
 
@@ -48,16 +58,15 @@
 
 #include "graph_intern.h"
 
+/* -------------------------------------------------------------------- */
+/** \name Internal Struct & Defines
+ * \{ */
+
 /* Used to obtain a list of animation channels for the operators to work on. */
 #define OPERATOR_DATA_FILTER \
   (ANIMFILTER_DATA_VISIBLE | ANIMFILTER_CURVE_VISIBLE | ANIMFILTER_FOREDIT | ANIMFILTER_SEL | \
    ANIMFILTER_NODUPLIS)
 
-/* ******************** GRAPH SLIDER OPERATORS ************************* */
-/* This file contains a collection of operators to modify keyframes in the graph editor. All
- * operators are modal and use a slider that allows the user to define a percentage to modify the
- * operator. */
-
 /* This data type is only used for modal operation. */
 typedef struct tGraphSliderOp {
   bAnimContext ac;
@@ -81,7 +90,11 @@ typedef struct tBeztCopyData {
   BezTriple *bezt;
 } tBeztCopyData;
 
-/* ******************** Utility Functions ************************* */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Utility Functions
+ * \{ */
 
 /* Construct a list with the original bezt arrays so we can restore them during modal operation.
  * The data is stored on the struct that is passed.*/
@@ -161,7 +174,11 @@ static void reset_bezts(tGraphSliderOp *gso)
   ANIM_animdata_freelist(&anim_data);
 }
 
-/* ******************** Decimate Keyframes Operator ************************* */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Decimate Keyframes Operator
+ * \{ */
 
 typedef enum tDecimModes {
   DECIM_RATIO = 1,
@@ -517,3 +534,5 @@ void GRAPH_OT_decimate(wmOperatorType *ot)
                 0.0f,
                 10.0f);
 }
+
+/** \} */
diff --git a/source/blender/editors/space_graph/graph_utils.c b/source/blender/editors/space_graph/graph_utils.c
index c37d9f42c12..89e7fefd9ac 100644
--- a/source/blender/editors/space_graph/graph_utils.c
+++ b/source/blender/editors/space_graph/graph_utils.c
@@ -46,8 +46,9 @@
 
 #include "graph_intern.h" /* own include */
 
-/* ************************************************************** */
-/* Set Up Drivers Editor */
+/* -------------------------------------------------------------------- */
+/** \name Set Up Drivers Editor
+ * \{ */
 
 /* Set up UI configuration for Drivers Editor */
 /* NOTE: Currently called from window-manager
@@ -89,8 +90,11 @@ void ED_drivers_editor_init(bContext *C, ScrArea *area)
   }
 }
 
-/* ************************************************************** */
-/* Active F-Curve */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Active F-Curve
+ * \{ */
 
 /**
  * Find 'active' F-Curve.
@@ -124,8 +128,11 @@ bAnimListElem *get_active_fcurve_channel(bAnimContext *ac)
   return NULL;
 }
 
-/* ************************************************************** */
-/* Operator Polling Callbacks */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Operator Polling Callbacks
+ * \{ */
 
 /* Check if there are any visible keyframes (for selection tools) */
 bool graphop_visible_keyframes_poll(bContext *C)
@@ -321,4 +328,4 @@ bool graphop_selected_fcurve_poll(bContext *C)
   return true;
 }
 
-/* ************************************************************** */
+/** \} */
diff --git a/source/blender/editors/space_graph/graph_view.c b/source/blender/editors/space_graph/graph_view.c
index 56649c50cfd..a12c6053877 100644
--- a/source/blender/editors/space_graph/graph_view.c
+++ b/source/blender/editors/space_graph/graph_view.c
@@ -17,6 +17,10 @@
  * All rights reserved.
  */
 
+/** \file
+ * \ingroup spgraph
+ */
+
 #include <math.h>
 
 #include "MEM_guardedalloc.h"
@@ -48,7 +52,9 @@
 
 #include "graph_intern.h"
 
-/* *************************** Calculate Range ************************** */
+/* -------------------------------------------------------------------- */
+/** \name Calculate Range
+ * \{ */
 
 /* Get the min/max keyframes. */
 /* NOTE: it should return total boundbox, filter for selection only can be argument... */
@@ -194,7 +200,11 @@ void get_graph_keyframe_extents(bAnimContext *ac,
   }
 }
 
-/* ****************** Automatic Preview-Range Operator ****************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Automatic Preview-Range Operator
+ * \{ */
 
 static int graphkeys_previewrange_exec(bContext *C, wmOperator *UNUSED(op))
 {
@@ -241,7 +251,11 @@ void GRAPH_OT_previewrange_set(wmOperatorType *ot)
   ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 }
 
-/* ****************** View-All Operator ****************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name View-All Operator
+ * \{ */
 
 static int graphkeys_viewall(bContext *C,
                              const bool do_sel_only,
@@ -347,7 +361,11 @@ void GRAPH_OT_view_selected(wmOperatorType *ot)
                              "Include handles of keyframes when calculating extents");
 }
 
-/* ********************** View Frame Operator ****************************** */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name View Frame Operator
+ * \{ */
 
 static int graphkeys_view_frame_exec(bContext *C, wmOperator *op)
 {
@@ -371,10 +389,14 @@ void GRAPH_OT_view_frame(wmOperatorType *ot)
   ot->flag = 0;
 }
 
-/* ******************** Create Ghost-Curves Operator *********************** */
-/* This operator samples the data of the selected F-Curves to F-Points, storing them
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Create Ghost-Curves Operator
+ *
+ * This operator samples the data of the selected F-Curves to F-Points, storing them
  * as 'ghost curves' in the active Graph Editor.
- */
+ * \{ */
 
 /* Bake each F-Curve into a set of samples, and store as a ghost curve. */
 static void create_ghost_curves(bAnimContext *ac, int start, int end)
@@ -493,8 +515,13 @@ void GRAPH_OT_ghost_curves_create(wmOperatorType *ot)
   /* TODO: add props for start/end frames */
 }
 
-/* ******************** Clear Ghost-Curves Operator *********************** */
-/* This operator clears the 'ghost curves' for the active Graph Editor */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Clear Ghost-Curves Operator
+ *
+ * This operator clears the 'ghost curves' for the active Graph Editor.
+ * \{ */
 
 static int graphkeys_clear_ghostcurves_exec(bContext *C, wmOperator *UNUSED(op))
 {
@@ -534,3 +561,5 @@ void GRAPH_OT_ghost_curves_clear(wmOperatorType *ot)
   /* Flags */
   ot->flag = OPTYPE_REGISTER | OPTYPE_UNDO;
 }
+
+/** \} */