Cleanup: move public doc-strings into headers for 'modifiers'

Ref T92709

9 files changed, 58 insertions, 46 deletions

diff --git a/source/blender/modifiers/MOD_modifiertypes.h b/source/blender/modifiers/MOD_modifiertypes.h
index f36cb7ded9c..2a0a7a02472 100644
--- a/source/blender/modifiers/MOD_modifiertypes.h
+++ b/source/blender/modifiers/MOD_modifiertypes.h
@@ -91,6 +91,10 @@ extern ModifierTypeInfo modifierType_VolumeDisplace;
 extern ModifierTypeInfo modifierType_VolumeToMesh;
 
 /* MOD_util.c */
+
+/**
+ * Only called by `BKE_modifier.h/modifier.c`
+ */
 void modifier_type_init(ModifierTypeInfo *types[]);
 
 #ifdef __cplusplus
diff --git a/source/blender/modifiers/MOD_nodes.h b/source/blender/modifiers/MOD_nodes.h
index 907dbe9c5f4..1105925162c 100644
--- a/source/blender/modifiers/MOD_nodes.h
+++ b/source/blender/modifiers/MOD_nodes.h
@@ -24,6 +24,11 @@ struct Object;
 extern "C" {
 #endif
 
+/**
+ * Rebuild the list of properties based on the sockets exposed as the modifier's node group
+ * inputs. If any properties correspond to the old properties by name and type, carry over
+ * the values.
+ */
 void MOD_nodes_update_interface(struct Object *object, struct NodesModifierData *nmd);
 
 void MOD_nodes_init(struct Main *bmain, struct NodesModifierData *nmd);
diff --git a/source/blender/modifiers/intern/MOD_nodes.cc b/source/blender/modifiers/intern/MOD_nodes.cc
index 05e9bd7d233..ea95a5f5af4 100644
--- a/source/blender/modifiers/intern/MOD_nodes.cc
+++ b/source/blender/modifiers/intern/MOD_nodes.cc
@@ -561,11 +561,6 @@ static void init_socket_cpp_value_from_property(const IDProperty &property,
   }
 }
 
-/**
- * Rebuild the list of properties based on the sockets exposed as the modifier's node group
- * inputs. If any properties correspond to the old properties by name and type, carry over
- * the values.
- */
 void MOD_nodes_update_interface(Object *object, NodesModifierData *nmd)
 {
   if (nmd->node_group == nullptr) {
diff --git a/source/blender/modifiers/intern/MOD_ui_common.c b/source/blender/modifiers/intern/MOD_ui_common.c
index cbeb429a94c..fc1f6d33b25 100644
--- a/source/blender/modifiers/intern/MOD_ui_common.c
+++ b/source/blender/modifiers/intern/MOD_ui_common.c
@@ -100,9 +100,6 @@ static void set_modifier_expand_flag(const bContext *UNUSED(C), Panel *panel, sh
 /** \name Modifier Panel Layouts
  * \{ */
 
-/**
- * Draw modifier error message.
- */
 void modifier_panel_end(uiLayout *layout, PointerRNA *ptr)
 {
   ModifierData *md = ptr->data;
@@ -137,9 +134,6 @@ PointerRNA *modifier_panel_get_property_pointers(Panel *panel, PointerRNA *r_ob_
   return ptr;
 }
 
-/**
- * Helper function for modifier layouts to draw vertex group settings.
- */
 void modifier_vgroup_ui(uiLayout *layout,
                         PointerRNA *ptr,
                         PointerRNA *ob_ptr,
@@ -429,9 +423,6 @@ static void modifier_panel_header(const bContext *C, Panel *panel)
 /** \name Modifier Registration Helpers
  * \{ */
 
-/**
- * Create a panel in the context's region
- */
 PanelType *modifier_panel_register(ARegionType *region_type, ModifierType type, PanelDrawFn draw)
 {
   PanelType *panel_type = MEM_callocN(sizeof(PanelType), __func__);
@@ -458,12 +449,6 @@ PanelType *modifier_panel_register(ARegionType *region_type, ModifierType type,
   return panel_type;
 }
 
-/**
- * Add a child panel to the parent.
- *
- * \note To create the panel type's idname, it appends the \a name argument to the \a parent's
- * idname.
- */
 PanelType *modifier_subpanel_register(ARegionType *region_type,
                                       const char *name,
                                       const char *label,
diff --git a/source/blender/modifiers/intern/MOD_ui_common.h b/source/blender/modifiers/intern/MOD_ui_common.h
index e7f801049b8..9662b181013 100644
--- a/source/blender/modifiers/intern/MOD_ui_common.h
+++ b/source/blender/modifiers/intern/MOD_ui_common.h
@@ -37,6 +37,9 @@ typedef void (*PanelDrawFn)(const bContext *, struct Panel *);
 
 void modifier_panel_buttons(const struct bContext *C, struct Panel *panel);
 
+/**
+ * Helper function for modifier layouts to draw vertex group settings.
+ */
 void modifier_vgroup_ui(struct uiLayout *layout,
                         struct PointerRNA *ptr,
                         struct PointerRNA *ob_ptr,
@@ -44,15 +47,27 @@ void modifier_vgroup_ui(struct uiLayout *layout,
                         const char *invert_vgroup_prop,
                         const char *text);
 
+/**
+ * Draw modifier error message.
+ */
 void modifier_panel_end(struct uiLayout *layout, PointerRNA *ptr);
 
 struct PointerRNA *modifier_panel_get_property_pointers(struct Panel *panel,
                                                         struct PointerRNA *r_ob_ptr);
 
+/**
+ * Create a panel in the context's region
+ */
 struct PanelType *modifier_panel_register(struct ARegionType *region_type,
                                           ModifierType type,
                                           PanelDrawFn draw);
 
+/**
+ * Add a child panel to the parent.
+ *
+ * \note To create the panel type's idname, it appends the \a name argument to the \a parent's
+ * idname.
+ */
 struct PanelType *modifier_subpanel_register(struct ARegionType *region_type,
                                              const char *name,
                                              const char *label,
diff --git a/source/blender/modifiers/intern/MOD_util.c b/source/blender/modifiers/intern/MOD_util.c
index 194e7ac2a68..16ef65f7838 100644
--- a/source/blender/modifiers/intern/MOD_util.c
+++ b/source/blender/modifiers/intern/MOD_util.c
@@ -72,7 +72,6 @@ void MOD_init_texture(MappingInfoModifierData *dmd, const ModifierEvalContext *c
 }
 
 /* TODO: to be renamed to get_texture_coords once we are done with moving modifiers to Mesh. */
-/** \param cos: may be NULL, in which case we use directly mesh vertices' coordinates. */
 void MOD_get_texture_coords(MappingInfoModifierData *dmd,
                             const ModifierEvalContext *UNUSED(ctx),
                             Object *ob,
@@ -182,7 +181,6 @@ void MOD_previous_vcos_store(ModifierData *md, const float (*vert_coords)[3])
   /* lattice/mesh modifier too */
 }
 
-/* returns a mesh if mesh == NULL, for deforming modifiers that need it */
 Mesh *MOD_deform_mesh_eval_get(Object *ob,
                                struct BMEditMesh *em,
                                Mesh *mesh,
@@ -288,7 +286,6 @@ void MOD_depsgraph_update_object_bone_relation(struct DepsNodeHandle *node,
   }
 }
 
-/* only called by BKE_modifier.h/modifier.c */
 void modifier_type_init(ModifierTypeInfo *types[])
 {
 #define INIT_TYPE(typeName) (types[eModifierType_##typeName] = &modifierType_##typeName)
diff --git a/source/blender/modifiers/intern/MOD_util.h b/source/blender/modifiers/intern/MOD_util.h
index a3db848874e..a6fc2749e71 100644
--- a/source/blender/modifiers/intern/MOD_util.h
+++ b/source/blender/modifiers/intern/MOD_util.h
@@ -32,6 +32,9 @@ struct ModifierEvalContext;
 struct Object;
 
 void MOD_init_texture(struct MappingInfoModifierData *dmd, const struct ModifierEvalContext *ctx);
+/**
+ * \param cos: may be NULL, in which case we use directly mesh vertices' coordinates.
+ */
 void MOD_get_texture_coords(struct MappingInfoModifierData *dmd,
                             const struct ModifierEvalContext *ctx,
                             struct Object *ob,
@@ -41,6 +44,9 @@ void MOD_get_texture_coords(struct MappingInfoModifierData *dmd,
 
 void MOD_previous_vcos_store(struct ModifierData *md, const float (*vert_coords)[3]);
 
+/**
+ * \returns a mesh if mesh == NULL, for deforming modifiers that need it.
+ */
 struct Mesh *MOD_deform_mesh_eval_get(struct Object *ob,
                                       struct BMEditMesh *em,
                                       struct Mesh *mesh,
diff --git a/source/blender/modifiers/intern/MOD_weightvg_util.c b/source/blender/modifiers/intern/MOD_weightvg_util.c
index e403051d1be..cd9e5162527 100644
--- a/source/blender/modifiers/intern/MOD_weightvg_util.c
+++ b/source/blender/modifiers/intern/MOD_weightvg_util.c
@@ -57,12 +57,6 @@
 #include "MOD_weightvg_util.h"
 #include "RE_texture.h" /* Texture masking. */
 
-/* Maps new_w weights in place, using either one of the predefined functions, or a custom curve.
- * Return values are in new_w.
- * If indices is not NULL, it must be a table of same length as org_w and new_w,
- * mapping to the real vertex index (in case the weight tables do not cover the whole vertices...).
- * cmap might be NULL, in which case curve mapping mode will return unmodified data.
- */
 void weightvg_do_map(
     int num, float *new_w, short falloff_type, const bool do_invert, CurveMapping *cmap, RNG *rng)
 {
@@ -125,13 +119,6 @@ void weightvg_do_map(
   }
 }
 
-/* Applies new_w weights to org_w ones, using either a texture, vgroup or constant value as factor.
- * Return values are in org_w.
- * If indices is not NULL, it must be a table of same length as org_w and new_w,
- * mapping to the real vertex index (in case the weight tables do not cover the whole vertices...).
- * XXX The standard "factor" value is assumed in [0.0, 1.0] range.
- * Else, weird results might appear.
- */
 void weightvg_do_mask(const ModifierEvalContext *ctx,
                       const int num,
                       const int *indices,
@@ -267,12 +254,6 @@ void weightvg_do_mask(const ModifierEvalContext *ctx,
   }
 }
 
-/* Applies weights to given vgroup (defgroup), and optionally add/remove vertices from the group.
- * If dws is not NULL, it must be an array of MDeformWeight pointers of same length as weights (and
- * defgrp_idx can then have any value).
- * If indices is not NULL, it must be an array of same length as weights, mapping to the real
- * vertex index (in case the weight array does not cover the whole vertices...).
- */
 void weightvg_update_vg(MDeformVert *dvert,
                         int defgrp_idx,
                         MDeformWeight **dws,
@@ -340,8 +321,6 @@ void weightvg_update_vg(MDeformVert *dvert,
   }
 }
 
-/* Common vertex weight mask interface elements for the modifier panels.
- */
 void weightvg_ui_common(const bContext *C, PointerRNA *ob_ptr, PointerRNA *ptr, uiLayout *layout)
 {
   PointerRNA mask_texture_ptr = RNA_pointer_get(ptr, "mask_texture");
diff --git a/source/blender/modifiers/intern/MOD_weightvg_util.h b/source/blender/modifiers/intern/MOD_weightvg_util.h
index 796603289ca..00aecd7342c 100644
--- a/source/blender/modifiers/intern/MOD_weightvg_util.h
+++ b/source/blender/modifiers/intern/MOD_weightvg_util.h
@@ -46,13 +46,21 @@ struct uiLayout;
  * Util functions.                    *
  **************************************/
 
-/* We cannot divide by zero (what a surprise...).
- * So if -MOD_WEIGHTVGROUP_DIVMODE_ZEROFLOOR < weightf < MOD_WEIGHTVGROUP_DIVMODE_ZEROFLOOR,
+/**
+ * We cannot divide by zero (what a surprise...).
+ * So if `-MOD_WEIGHTVGROUP_DIVMODE_ZEROFLOOR < weightf < MOD_WEIGHTVGROUP_DIVMODE_ZEROFLOOR`,
  * we clamp weightf to this value (or its negative version).
  * Also used to avoid null power factor.
  */
 #define MOD_WVG_ZEROFLOOR 1.0e-32f
 
+/**
+ * Maps new_w weights in place, using either one of the predefined functions, or a custom curve.
+ * Return values are in new_w.
+ * If indices is not NULL, it must be a table of same length as org_w and new_w,
+ * mapping to the real vertex index (in case the weight tables do not cover the whole vertices...).
+ * cmap might be NULL, in which case curve mapping mode will return unmodified data.
+ */
 void weightvg_do_map(int num,
                      float *new_w,
                      short falloff_type,
@@ -60,6 +68,14 @@ void weightvg_do_map(int num,
                      struct CurveMapping *cmap,
                      struct RNG *rng);
 
+/**
+ * Applies new_w weights to org_w ones, using either a texture, vgroup or constant value as factor.
+ * Return values are in org_w.
+ * If indices is not NULL, it must be a table of same length as org_w and new_w,
+ * mapping to the real vertex index (in case the weight tables do not cover the whole vertices...).
+ * XXX The standard "factor" value is assumed in [0.0, 1.0] range.
+ * Else, weird results might appear.
+ */
 void weightvg_do_mask(const ModifierEvalContext *ctx,
                       const int num,
                       const int *indices,
@@ -78,6 +94,13 @@ void weightvg_do_mask(const ModifierEvalContext *ctx,
                       const char *tex_uvlayer_name,
                       const bool invert_vgroup_mask);
 
+/**
+ * Applies weights to given vgroup (defgroup), and optionally add/remove vertices from the group.
+ * If dws is not NULL, it must be an array of #MDeformWeight pointers of same length as weights
+ * (and defgrp_idx can then have any value).
+ * If indices is not NULL, it must be an array of same length as weights, mapping to the real
+ * vertex index (in case the weight array does not cover the whole vertices...).
+ */
 void weightvg_update_vg(struct MDeformVert *dvert,
                         int defgrp_idx,
                         struct MDeformWeight **dws,
@@ -90,4 +113,7 @@ void weightvg_update_vg(struct MDeformVert *dvert,
                         const float rem_thresh,
                         const bool do_normalize);
 
+/**
+ * Common vertex weight mask interface elements for the modifier panels.
+ */
 void weightvg_ui_common(const bContext *C, PointerRNA *ob_ptr, PointerRNA *ptr, uiLayout *layout);