Docs: use doxygen formatting for DNA

Differentiate doc-strings from title/section text.
Also use explicit doxygen references to struct members
so it's not ambiguous which member is being referenced.

Note that these changes aren't complete (some files weren't touched).

1 files changed, 25 insertions, 23 deletions

diff --git a/source/blender/makesdna/DNA_object_types.h b/source/blender/makesdna/DNA_object_types.h
index 57c8ef200ae..c9345b6a950 100644
--- a/source/blender/makesdna/DNA_object_types.h
+++ b/source/blender/makesdna/DNA_object_types.h
@@ -57,7 +57,7 @@ struct SculptSession;
 struct SoftBody;
 struct bGPdata;
 
-/* Vertex Groups - Name Info */
+/** Vertex Groups - Name Info */
 typedef struct bDeformGroup {
   struct bDeformGroup *next, *prev;
   /** MAX_VGROUP_NAME. */
@@ -66,7 +66,7 @@ typedef struct bDeformGroup {
   char flag, _pad0[7];
 } bDeformGroup;
 
-/* Face Maps. */
+/** Face Maps. */
 typedef struct bFaceMap {
   struct bFaceMap *next, *prev;
   /** MAX_VGROUP_NAME. */
@@ -107,7 +107,7 @@ typedef struct BoundBox {
   char _pad0[4];
 } BoundBox;
 
-/* boundbox flag */
+/** #BoundBox.flag */
 enum {
   BOUNDBOX_DISABLED = (1 << 0),
   BOUNDBOX_DIRTY = (1 << 1),
@@ -115,7 +115,7 @@ enum {
 
 struct CustomData_MeshMasks;
 
-/* Not saved in file! */
+/** Not saved in file! */
 typedef struct Object_Runtime {
   /**
    * The custom data layer mask that was last used
@@ -246,7 +246,7 @@ typedef struct Object {
   /** String describing subobject info, MAX_ID_NAME-2. */
   char parsubstr[64];
   struct Object *parent, *track;
-  /* if ob->proxy (or proxy_group), this object is proxy for object ob->proxy */
+  /* If `ob->proxy` (or proxy_group), this object is proxy for object `ob->proxy`. */
   /* proxy_from is set in target back to the proxy. */
   struct Object *proxy, *proxy_group, *proxy_from;
   /** Old animation system, deprecated for 2.5. */
@@ -322,8 +322,7 @@ typedef struct Object {
    * Inverse matrix of 'obmat' for any other use than rendering!
    *
    * \note this isn't assured to be valid as with 'obmat',
-   * before using this value you should do...
-   * invert_m4_m4(ob->imat, ob->obmat);
+   * before using this value you should do: `invert_m4_m4(ob->imat, ob->obmat)`
    */
   float imat[4][4];
 
@@ -436,7 +435,7 @@ typedef struct Object {
   Object_Runtime runtime;
 } Object;
 
-/* Warning, this is not used anymore because hooks are now modifiers */
+/** DEPRECATED: this is not used anymore because hooks are now modifiers. */
 typedef struct ObHook {
   struct ObHook *next, *prev;
 
@@ -466,7 +465,7 @@ typedef struct ObHook {
 /* used many places, should be specialized. */
 #define SELECT 1
 
-/* type */
+/** #Object.type */
 enum {
   OB_EMPTY = 0,
   OB_MESH = 1,
@@ -544,7 +543,7 @@ enum {
   case ID_PT: \
   case ID_VO
 
-/* partype: first 4 bits: type */
+/** #Object.partype: first 4 bits: type. */
 enum {
   PARTYPE = (1 << 4) - 1,
   PAROBJECT = 0,
@@ -555,7 +554,7 @@ enum {
 
 };
 
-/* (short) transflag */
+/** #Object.transflag (short) */
 enum {
   OB_TRANSFORM_ADJUST_ROOT_PARENT_FOR_VIEW_LOCK = 1 << 0,
   OB_TRANSFLAG_UNUSED_1 = 1 << 1, /* cleared */
@@ -577,7 +576,7 @@ enum {
   OB_DUPLI = OB_DUPLIVERTS | OB_DUPLICOLLECTION | OB_DUPLIFACES | OB_DUPLIPARTS,
 };
 
-/* (short) trackflag / upflag */
+/** #Object.trackflag / #Object.upflag (short) */
 enum {
   OB_POSX = 0,
   OB_POSY = 1,
@@ -587,7 +586,7 @@ enum {
   OB_NEGZ = 5,
 };
 
-/* dtx: flags (short) */
+/** #Object.dtx draw type extra flags (short) */
 enum {
   OB_DRAWBOUNDOX = 1 << 0,
   OB_AXIS = 1 << 1,
@@ -606,7 +605,7 @@ enum {
   OB_USE_GPENCIL_LIGHTS = 1 << 10,
 };
 
-/* empty_drawtype: no flags */
+/** #Object.empty_drawtype: no flags */
 enum {
   OB_ARROWS = 1,
   OB_PLAINAXES = 2,
@@ -618,7 +617,10 @@ enum {
   OB_EMPTY_IMAGE = 8,
 };
 
-/* gpencil add types */
+/**
+ * Grease-pencil add types.
+ * TODO: doesn't need to be DNA, local to `OBJECT_OT_gpencil_add`.
+ */
 enum {
   GP_EMPTY = 0,
   GP_STROKE = 1,
@@ -628,7 +630,7 @@ enum {
   GP_LRT_COLLECTION = 5,
 };
 
-/* boundtype */
+/** #Object.boundtype */
 enum {
   OB_BOUND_BOX = 0,
   OB_BOUND_SPHERE = 1,
@@ -642,7 +644,7 @@ enum {
 
 /* **************** BASE ********************* */
 
-/* base->flag_legacy */
+/** #Base.flag_legacy */
 enum {
   BA_WAS_SEL = (1 << 1),
   /* NOTE: BA_HAS_RECALC_DATA can be re-used later if freed in readfile.c. */
@@ -671,7 +673,7 @@ enum {
 #  define OB_FLAG_UNUSED_12 (1 << 12) /* cleared */
 #endif
 
-/* ob->visibility_flag */
+/** #Object.visibility_flag */
 enum {
   OB_HIDE_VIEWPORT = 1 << 0,
   OB_HIDE_SELECT = 1 << 1,
@@ -686,7 +688,7 @@ enum {
   OB_SHADOW_CATCHER = 1 << 10
 };
 
-/* ob->shapeflag */
+/** #Object.shapeflag */
 enum {
   OB_SHAPE_LOCK = 1 << 0,
 #ifdef DNA_DEPRECATED_ALLOW
@@ -695,7 +697,7 @@ enum {
   OB_SHAPE_EDIT_MODE = 1 << 2,
 };
 
-/* ob->nlaflag */
+/** #Object.nlaflag */
 enum {
   OB_ADS_UNUSED_1 = 1 << 0, /* cleared */
   OB_ADS_UNUSED_2 = 1 << 1, /* cleared */
@@ -711,7 +713,7 @@ enum {
   /* OB_ADS_SHOWPARTS = 1 << 14, */ /* UNUSED */
 };
 
-/* ob->protectflag */
+/** #Object.protectflag */
 enum {
   OB_LOCK_LOCX = 1 << 0,
   OB_LOCK_LOCY = 1 << 1,
@@ -729,13 +731,13 @@ enum {
   OB_LOCK_ROT4D = 1 << 10,
 };
 
-/* ob->duplicator_visibility_flag */
+/** #Object.duplicator_visibility_flag */
 enum {
   OB_DUPLI_FLAG_VIEWPORT = 1 << 0,
   OB_DUPLI_FLAG_RENDER = 1 << 1,
 };
 
-/* ob->empty_image_depth */
+/** #Object.empty_image_depth */
 #define OB_EMPTY_IMAGE_DEPTH_DEFAULT 0
 #define OB_EMPTY_IMAGE_DEPTH_FRONT 1
 #define OB_EMPTY_IMAGE_DEPTH_BACK 2