Cleanup: use doxy sections for object_dupli.c

1 files changed, 75 insertions, 20 deletions

diff --git a/source/blender/blenkernel/intern/object_dupli.c b/source/blender/blenkernel/intern/object_dupli.c
index f485f3d2419..553cff33fbb 100644
--- a/source/blender/blenkernel/intern/object_dupli.c
+++ b/source/blender/blenkernel/intern/object_dupli.c
@@ -62,7 +62,9 @@
 #include "BLI_hash.h"
 #include "BLI_strict_flags.h"
 
-/* Dupli-Geometry */
+/* -------------------------------------------------------------------- */
+/** \name Internal Duplicate Context
+ * \{ */
 
 typedef struct DupliContext {
   Depsgraph *depsgraph;
@@ -92,7 +94,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,
@@ -119,7 +123,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)
 {
@@ -141,8 +147,10 @@ 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,
@@ -205,8 +213,10 @@ static DupliObject *make_dupli(const DupliContext *ctx,
   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,
@@ -223,7 +233,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);
 
@@ -239,7 +253,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)
@@ -282,9 +298,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;
@@ -324,7 +343,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 +470,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)
 {
@@ -573,7 +602,12 @@ static const DupliGenerator gen_dupli_verts_font = {
     make_duplis_font /* make_duplis */
 };
 
-/* OB_DUPLIVERTS - PointCloud */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Vertices Implementation (#OB_DUPLIVERTS for #PointCloud)
+ * \{ */
+
 static void make_child_duplis_pointcloud(const DupliContext *ctx,
                                          void *UNUSED(userdata),
                                          Object *child)
@@ -630,7 +664,12 @@ static const DupliGenerator gen_dupli_verts_pointcloud = {
     make_duplis_pointcloud /* make_duplis */
 };
 
-/* OB_DUPLIFACES */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Dupli-Faces Implementation (#OB_DUPLIFACES)
+ * \{ */
+
 typedef struct FaceDupliData {
   Mesh *me_eval;
   int totface;
@@ -785,7 +824,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;
@@ -1133,9 +1177,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;
@@ -1177,9 +1224,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");
@@ -1198,3 +1251,5 @@ void free_object_duplilist(ListBase *lb)
   BLI_freelistN(lb);
   MEM_freeN(lb);
 }
+
+/** \} */