[Bf-blender-cvs] [fc5ff997709] blender-v2.90-release: Cleanup: use doxy sections for object_dupli.c

[Campbell Barton]

Commit: fc5ff997709bdc5ec458647eb8db0a6eced670a2
Author: Campbell Barton
Date:   Mon Aug 10 18:29:17 2020 +1000
Branches: blender-v2.90-release
https://developer.blender.org/rBfc5ff997709bdc5ec458647eb8db0a6eced670a2

Cleanup: use doxy sections for object_dupli.c

===================================================================

M	source/blender/blenkernel/intern/object_dupli.c

===================================================================

diff --git a/source/blender/blenkernel/intern/object_dupli.c b/source/blender/blenkernel/intern/object_dupli.c
index f498e147110..452c1657ed5 100644
--- a/source/blender/blenkernel/intern/object_dupli.c
+++ b/source/blender/blenkernel/intern/object_dupli.c
@@ -61,7 +61,9 @@
 #include "BLI_hash.h"
 #include "BLI_strict_flags.h"
 
-/* Dupli-Geometry */
+/* -------------------------------------------------------------------- */
+/** \name Internal Duplicate Context
+ * \{ */
 
 typedef struct DupliContext {
   Depsgraph *depsgraph;
@@ -91,7 +93,9 @@ typedef struct DupliGenerator {
 
 static const DupliGenerator *get_dupli_generator(const DupliContext *ctx);
 
-/* create initial context for root object */
+/**
+ * Create initial context for root object.
+ */
 static void init_context(DupliContext *r_ctx,
                          Depsgraph *depsgraph,
                          Scene *scene,
@@ -118,7 +122,9 @@ static void init_context(DupliContext *r_ctx,
   r_ctx->duplilist = NULL;
 }
 
-/* create sub-context for recursive duplis */
+/**
+ * Create sub-context for recursive duplis.
+ */
 static void copy_dupli_context(
     DupliContext *r_ctx, const DupliContext *ctx, Object *ob, const float mat[4][4], int index)
 {
@@ -140,10 +146,15 @@ static void copy_dupli_context(
   r_ctx->gen = get_dupli_generator(r_ctx);
 }
 
-/* generate a dupli instance
- * mat is transform of the object relative to current context (including object obmat)
+/**
+ * Generate a dupli instance.
+ *
+ * \param mat: is transform of the object relative to current context (including #Object.obmat).
  */
-static DupliObject *make_dupli(const DupliContext *ctx, Object *ob, float mat[4][4], int index)
+static DupliObject *make_dupli(const DupliContext *ctx,
+                               Object *ob,
+                               const float mat[4][4],
+                               int index)
 {
   DupliObject *dob;
   int i;
@@ -201,8 +212,10 @@ static DupliObject *make_dupli(const DupliContext *ctx, Object *ob, float mat[4]
   return dob;
 }
 
-/* recursive dupli objects
- * space_mat is the local dupli space (excluding dupli object obmat!)
+/**
+ * Recursive dupli objects.
+ *
+ * \param space_mat: is the local dupli space (excluding dupli #Object.obmat).
  */
 static void make_recursive_duplis(const DupliContext *ctx,
                                   Object *ob,
@@ -219,7 +232,11 @@ static void make_recursive_duplis(const DupliContext *ctx,
   }
 }
 
-/* ---- Child Duplis ---- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Internal Child Duplicates (Used by Other Functions)
+ * \{ */
 
 typedef void (*MakeChildDuplisFunc)(const DupliContext *ctx, void *userdata, Object *child);
 
@@ -235,7 +252,9 @@ static bool is_child(const Object *ob, const Object *parent)
   return false;
 }
 
-/* create duplis from every child in scene or collection */
+/**
+ * Create duplis from every child in scene or collection.
+ */
 static void make_child_duplis(const DupliContext *ctx,
                               void *userdata,
                               MakeChildDuplisFunc make_child_duplis_cb)
@@ -278,9 +297,12 @@ static void make_child_duplis(const DupliContext *ctx,
   }
 }
 
-/*---- Implementations ----*/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Collection Implementation (#OB_DUPLICOLLECTION)
+ * \{ */
 
-/* OB_DUPLICOLLECTION */
 static void make_duplis_collection(const DupliContext *ctx)
 {
   Object *ob = ctx->object;
@@ -320,7 +342,12 @@ static const DupliGenerator gen_dupli_collection = {
     make_duplis_collection /* make_duplis */
 };
 
-/* OB_DUPLIVERTS */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Vertices Implementation (#OB_DUPLIVERTS for Geometry)
+ * \{ */
+
 typedef struct VertexDupliData {
   Mesh *me_eval;
   BMEditMesh *edit_mesh;
@@ -446,7 +473,12 @@ static const DupliGenerator gen_dupli_verts = {
     make_duplis_verts /* make_duplis */
 };
 
-/* OB_DUPLIVERTS - FONT */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Vertices Implementation (#OB_DUPLIVERTS for 3D Text)
+ * \{ */
+
 static Object *find_family_object(
     Main *bmain, const char *family, size_t family_len, unsigned int ch, GHash *family_gh)
 {
@@ -523,7 +555,7 @@ static void make_duplis_font(const DupliContext *ctx)
   /* Safety check even if it might fail badly when called for original object. */
   const bool is_eval_curve = DEG_is_evaluated_id(&cu->id);
 
-  /* advance matching BLI_strncpy_wchar_from_utf8 */
+  /* Advance matching BLI_str_utf8_as_utf32. */
   for (a = 0; a < text_len; a++, ct++) {
 
     /* XXX That G.main is *really* ugly, but not sure what to do here...
@@ -573,7 +605,12 @@ static const DupliGenerator gen_dupli_verts_font = {
     make_duplis_font /* make_duplis */
 };
 
-/* OB_DUPLIFACES */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Faces Implementation (#OB_DUPLIFACES)
+ * \{ */
+
 typedef struct FaceDupliData {
   Mesh *me_eval;
   int totface;
@@ -728,7 +765,12 @@ static const DupliGenerator gen_dupli_faces = {
     make_duplis_faces /* make_duplis */
 };
 
-/* OB_DUPLIPARTS */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Particles Implementation (#OB_DUPLIPARTS)
+ * \{ */
+
 static void make_duplis_particle_system(const DupliContext *ctx, ParticleSystem *psys)
 {
   Scene *scene = ctx->scene;
@@ -1077,9 +1119,12 @@ static const DupliGenerator gen_dupli_particles = {
     make_duplis_particles /* make_duplis */
 };
 
-/* ------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Generator Selector For The Given Context
+ * \{ */
 
-/* select dupli generator from given context */
 static const DupliGenerator *get_dupli_generator(const DupliContext *ctx)
 {
   int transflag = ctx->object->transflag;
@@ -1118,9 +1163,15 @@ static const DupliGenerator *get_dupli_generator(const DupliContext *ctx)
   return NULL;
 }
 
-/* ---- ListBase dupli container implementation ---- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Container Implementation
+ * \{ */
 
-/* Returns a list of DupliObject */
+/**
+ * \return a #ListBase of #DupliObject.
+ */
 ListBase *object_duplilist(Depsgraph *depsgraph, Scene *sce, Object *ob)
 {
   ListBase *duplilist = MEM_callocN(sizeof(ListBase), "duplilist");
@@ -1139,3 +1190,5 @@ void free_object_duplilist(ListBase *lb)
   BLI_freelistN(lb);
   MEM_freeN(lb);
 }
+
+/** \} */