Cleanup: use doxy sections for fmodifier.c

source/blender/blenkernel/intern/fmodifier.c

@@ -46,7 +46,9 @@
 
 static CLG_LogRef LOG = {"bke.fmodifier"};
 
-/* ******************************** F-Modifiers ********************************* */
+/* -------------------------------------------------------------------- */
+/** \name F-Curve Modifier Types
+ * \{ */
 
 /* Info ------------------------------- */
 
@@ -1033,16 +1035,20 @@ static FModifierTypeInfo FMI_STEPPED = {
     NULL,                       /* evaluate */
 };
 
-/* F-Curve Modifier API --------------------------- */
+/** \} */
-/* All of the F-Curve Modifier api functions use FModifierTypeInfo structs to carry out
+
- * and operations that involve F-Curve modifier specific code.
+/* -------------------------------------------------------------------- */
- */
+/** \name F-Curve Modifier Type API
+ *
+ * all of the f-curve modifier api functions use #fmodifiertypeinfo structs to carry out
+ * and operations that involve f-curve modifier specific code.
+ * \{ */
 
 /* These globals only ever get directly accessed in this file */
 static FModifierTypeInfo *fmodifiersTypeInfo[FMODIFIER_NUM_TYPES];
 static short FMI_INIT = 1; /* when non-zero, the list needs to be updated */
 
-/* This function only gets called when FMI_INIT is non-zero */
+/** This function only gets called when #FMI_INIT is non-zero. */
 static void fmods_init_typeinfo(void)
 {
   fmodifiersTypeInfo[0] = NULL;              /* 'Null' F-Curve Modifier */
@@ -1057,8 +1063,9 @@ static void fmods_init_typeinfo(void)
   fmodifiersTypeInfo[9] = &FMI_STEPPED; /* Stepped F-Curve Modifier */
 }
 
-/* This function should be used for getting the appropriate type-info when only
+/**
- * a F-Curve modifier type is known
+ * This function should be used for getting the appropriate type-info when only
+ * a F-Curve modifier type is known.
  */
 const FModifierTypeInfo *get_fmodifier_typeinfo(const int type)
 {
@@ -1079,8 +1086,9 @@ const FModifierTypeInfo *get_fmodifier_typeinfo(const int type)
   return NULL;
 }
 
-/* This function should always be used to get the appropriate type-info, as it
+/**
- * has checks which prevent segfaults in some weird cases.
+ * This function should always be used to get the appropriate type-info,
+ * as it has checks which prevent segfaults in some weird cases.
  */
 const FModifierTypeInfo *fmodifier_get_typeinfo(const FModifier *fcm)
 {
@@ -1092,9 +1100,15 @@ const FModifierTypeInfo *fmodifier_get_typeinfo(const FModifier *fcm)
   return NULL;
 }
 
-/* API --------------------------- */
+/** \} */
 
-/* Add a new F-Curve Modifier to the given F-Curve of a certain type */
+/* -------------------------------------------------------------------- */
+/** \name F-Curve Modifier Public API
+ * \{ */
+
+/**
+ * Add a new F-Curve Modifier to the given F-Curve of a certain type.
+ */
 FModifier *add_fmodifier(ListBase *modifiers, int type, FCurve *owner_fcu)
 {
   const FModifierTypeInfo *fmi = get_fmodifier_typeinfo(type);
@@ -1145,7 +1159,9 @@ FModifier *add_fmodifier(ListBase *modifiers, int type, FCurve *owner_fcu)
   return fcm;
 }
 
-/* Make a copy of the specified F-Modifier */
+/**
+ * Make a copy of the specified F-Modifier.
+ */
 FModifier *copy_fmodifier(const FModifier *src)
 {
   const FModifierTypeInfo *fmi = fmodifier_get_typeinfo(src);
@@ -1173,7 +1189,9 @@ FModifier *copy_fmodifier(const FModifier *src)
   return dst;
 }
 
-/* Duplicate all of the F-Modifiers in the Modifier stacks */
+/**
+ * Duplicate all of the F-Modifiers in the Modifier stacks.
+ */
 void copy_fmodifiers(ListBase *dst, const ListBase *src)
 {
   FModifier *fcm, *srcfcm;
@@ -1200,7 +1218,9 @@ void copy_fmodifiers(ListBase *dst, const ListBase *src)
   }
 }
 
-/* Remove and free the given F-Modifier from the given stack  */
+/**
+ * Remove and free the given F-Modifier from the given stack.
+ */
 bool remove_fmodifier(ListBase *modifiers, FModifier *fcm)
 {
   const FModifierTypeInfo *fmi = fmodifier_get_typeinfo(fcm);
@@ -1241,7 +1261,9 @@ bool remove_fmodifier(ListBase *modifiers, FModifier *fcm)
   return false;
 }
 
-/* Remove all of a given F-Curve's modifiers */
+/**
+ * Remove all of a given F-Curve's modifiers.
+ */
 void free_fmodifiers(ListBase *modifiers)
 {
   FModifier *fcm, *fmn;
@@ -1258,7 +1280,9 @@ void free_fmodifiers(ListBase *modifiers)
   }
 }
 
-/* Find the active F-Modifier */
+/**
+ * Find the active F-Modifier.
+ */
 FModifier *find_active_fmodifier(ListBase *modifiers)
 {
   FModifier *fcm;
@@ -1279,7 +1303,9 @@ FModifier *find_active_fmodifier(ListBase *modifiers)
   return NULL;
 }
 
-/* Set the active F-Modifier */
+/**
+ * Set the active F-Modifier.
+ */
 void set_active_fmodifier(ListBase *modifiers, FModifier *fcm)
 {
   FModifier *fm;
@@ -1300,9 +1326,11 @@ void set_active_fmodifier(ListBase *modifiers, FModifier *fcm)
   }
 }
 
-/* Do we have any modifiers which match certain criteria
+/**
- * - mtype - type of modifier (if 0, doesn't matter)
+ * Do we have any modifiers which match certain criteria.
- * - acttype - type of action to perform (if -1, doesn't matter)
+ *
+ * \param mtype: Type of modifier (if 0, doesn't matter).
+ * \param acttype: Type of action to perform (if -1, doesn't matter).
  */
 bool list_has_suitable_fmodifier(ListBase *modifiers, int mtype, short acttype)
 {
@@ -1318,7 +1346,7 @@ bool list_has_suitable_fmodifier(ListBase *modifiers, int mtype, short acttype)
     return false;
   }
 
-  /* find the first mdifier fitting these criteria */
+  /* Find the first modifier fitting these criteria. */
   for (fcm = modifiers->first; fcm; fcm = fcm->next) {
     const FModifierTypeInfo *fmi = fmodifier_get_typeinfo(fcm);
     short mOk = 1, aOk = 1; /* by default 1, so that when only one test, won't fail */
@@ -1365,7 +1393,9 @@ uint evaluate_fmodifiers_storage_size_per_modifier(ListBase *modifiers)
   return max_size;
 }
 
-/* helper function - calculate influence of FModifier */
+/**
+ * Helper function - calculate influence of #FModifier.
+ */
 static float eval_fmodifier_influence(FModifier *fcm, float evaltime)
 {
   float influence;
@@ -1409,16 +1439,18 @@ static float eval_fmodifier_influence(FModifier *fcm, float evaltime)
   return influence;
 }
 
-/* evaluate time modifications imposed by some F-Curve Modifiers
+/**
- * - this step acts as an optimization to prevent the F-Curve stack being evaluated
+ * Evaluate time modifications imposed by some F-Curve Modifiers.
+ *
+ * - This step acts as an optimization to prevent the F-Curve stack being evaluated
  *   several times by modifiers requesting the time be modified, as the final result
  *   would have required using the modified time
- * - modifiers only ever receive the unmodified time, as subsequent modifiers should be
+ * - Modifiers only ever receive the unmodified time, as subsequent modifiers should be
  *   working on the 'global' result of the modified curve, not some localized segment,
- *   so nevaltime gets set to whatever the last time-modifying modifier likes...
+ *   so \a evaltime gets set to whatever the last time-modifying modifier likes.
- * - we start from the end of the stack, as only the last one matters for now
+ * - We start from the end of the stack, as only the last one matters for now.
  *
- * Note: *fcu might be NULL
+ * \param fcu: Can be NULL.
  */
 float evaluate_time_fmodifiers(FModifiersStackStorage *storage,
                                ListBase *modifiers,
@@ -1477,8 +1509,9 @@ float evaluate_time_fmodifiers(FModifiersStackStorage *storage,
   return evaltime;
 }
 
-/* Evaluates the given set of F-Curve Modifiers using the given data
+/**
- * Should only be called after evaluate_time_fmodifiers() has been called...
+ * Evaluates the given set of F-Curve Modifiers using the given data
+ * Should only be called after evaluate_time_fmodifiers() has been called.
  */
 void evaluate_value_fmodifiers(FModifiersStackStorage *storage,
                                ListBase *modifiers,
@@ -1528,7 +1561,8 @@ void evaluate_value_fmodifiers(FModifiersStackStorage *storage,
 
 /* ---------- */
 
-/* Bake modifiers for given F-Curve to curve sample data, in the frame range defined
+/**
+ * Bake modifiers for given F-Curve to curve sample data, in the frame range defined
  * by start and end (inclusive).
  */
 void fcurve_bake_modifiers(FCurve *fcu, int start, int end)
@@ -1555,3 +1589,5 @@ void fcurve_bake_modifiers(FCurve *fcu, int start, int end)
   /* restore driver */
   fcu->driver = driver;
 }
+
+/** \} */