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, 45 insertions, 34 deletions

diff --git a/source/blender/makesdna/DNA_node_types.h b/source/blender/makesdna/DNA_node_types.h
index dc5acb9d5b2..f4a1efe84b8 100644
--- a/source/blender/makesdna/DNA_node_types.h
+++ b/source/blender/makesdna/DNA_node_types.h
@@ -174,7 +174,7 @@ typedef struct bNodeSocket {
   const SocketDeclarationHandle *declaration;
 } bNodeSocket;
 
-/* sock->type */
+/** #bNodeSocket.type & #bNodeSocketType.type */
 typedef enum eNodeSocketDatatype {
   SOCK_CUSTOM = -1, /* socket has no integer type */
   SOCK_FLOAT = 0,
@@ -193,7 +193,7 @@ typedef enum eNodeSocketDatatype {
   SOCK_MATERIAL = 13,
 } eNodeSocketDatatype;
 
-/* Socket shape. */
+/** Socket shape. */
 typedef enum eNodeSocketDisplayShape {
   SOCK_DISPLAY_SHAPE_CIRCLE = 0,
   SOCK_DISPLAY_SHAPE_SQUARE = 1,
@@ -203,13 +203,13 @@ typedef enum eNodeSocketDisplayShape {
   SOCK_DISPLAY_SHAPE_DIAMOND_DOT = 5,
 } eNodeSocketDisplayShape;
 
-/* Socket side (input/output). */
+/** Socket side (input/output). */
 typedef enum eNodeSocketInOut {
   SOCK_IN = 1 << 0,
   SOCK_OUT = 1 << 1,
 } eNodeSocketInOut;
 
-/* #bNodeSocket.flag, first bit is selection. */
+/** #bNodeSocket.flag, first bit is selection. */
 typedef enum eNodeSocketFlag {
   /** Hidden is user defined, to hide unused sockets. */
   SOCK_HIDDEN = (1 << 1),
@@ -239,7 +239,7 @@ typedef enum eNodeSocketFlag {
   SOCK_HIDE_LABEL = (1 << 12),
 } eNodeSocketFlag;
 
-/* TODO: Limit data in bNode to what we want to see saved. */
+/** TODO: Limit data in #bNode to what we want to see saved. */
 typedef struct bNode {
   struct bNode *next, *prev, *new_node;
 
@@ -571,7 +571,7 @@ typedef struct bNodeTree {
   struct PreviewImage *preview;
 } bNodeTree;
 
-/* ntree->type, index */
+/** #NodeTree.type, index */
 
 #define NTREE_UNDEFINED -2 /* Represents #NodeTreeTypeUndefined type. */
 #define NTREE_CUSTOM -1    /* for dynamically registered custom types */
@@ -580,10 +580,10 @@ typedef struct bNodeTree {
 #define NTREE_TEXTURE 2
 #define NTREE_GEOMETRY 3
 
-/* ntree->init, flag */
+/** #NodeTree.init, flag */
 #define NTREE_TYPE_INIT 1
 
-/* ntree->flag */
+/** #NodeTree.flag */
 #define NTREE_DS_EXPAND (1 << 0)            /* for animation editors */
 #define NTREE_COM_OPENCL (1 << 1)           /* use opencl */
 #define NTREE_TWO_PASS (1 << 2)             /* two pass */
@@ -594,7 +594,7 @@ typedef struct bNodeTree {
 /* tree is localized copy, free when deleting node groups */
 /* #define NTREE_IS_LOCALIZED           (1 << 5) */
 
-/* ntree->update */
+/** #NodeTree.update */
 typedef enum eNodeTreeUpdate {
   NTREE_UPDATE = 0xFFFF,             /* generic update flag (includes all others) */
   NTREE_UPDATE_LINKS = (1 << 0),     /* links have been added or removed */
@@ -608,7 +608,7 @@ typedef enum eNodeTreeUpdate {
   NTREE_UPDATE_GROUP = (NTREE_UPDATE_GROUP_IN | NTREE_UPDATE_GROUP_OUT),
 } eNodeTreeUpdate;
 
-/* tree->execution_mode */
+/** #NodeTree.execution_mode */
 typedef enum eNodeTreeExecutionMode {
   NTREE_EXECUTION_MODE_TILED = 0,
   NTREE_EXECUTION_MODE_FULL_FRAME = 1,
@@ -674,7 +674,8 @@ typedef struct bNodeSocketValueMaterial {
   struct Material *value;
 } bNodeSocketValueMaterial;
 
-/* Data structs, for node->storage. */
+/* Data structs, for `node->storage`. */
+
 enum {
   CMP_NODE_MASKTYPE_ADD = 0,
   CMP_NODE_MASKTYPE_SUBTRACT = 1,
@@ -713,7 +714,7 @@ typedef struct NodeFrame {
   short label_size;
 } NodeFrame;
 
-/* This one has been replaced with ImageUser, keep it for do_versions(). */
+/** \note This one has been replaced with #ImageUser, keep it for do_versions(). */
 typedef struct NodeImageAnim {
   int frames DNA_DEPRECATED;
   int sfra DNA_DEPRECATED;
@@ -767,7 +768,7 @@ typedef struct NodeEllipseMask {
   char _pad[4];
 } NodeEllipseMask;
 
-/* Layer info for image node outputs. */
+/** Layer info for image node outputs. */
 typedef struct NodeImageLayer {
   /* index in the Image->layers->passes lists */
   int pass_index DNA_DEPRECATED;
@@ -805,7 +806,7 @@ typedef struct NodeAntiAliasingData {
   float corner_rounding;
 } NodeAntiAliasingData;
 
-/* NOTE: Only for do-version code. */
+/** \note Only for do-version code. */
 typedef struct NodeHueSat {
   float hue, sat, val;
 } NodeHueSat;
@@ -817,7 +818,9 @@ typedef struct NodeImageFile {
   int sfra, efra;
 } NodeImageFile;
 
-/* XXX first struct fields should match NodeImageFile to ensure forward compatibility */
+/**
+ * XXX: first struct fields should match #NodeImageFile to ensure forward compatibility.
+ */
 typedef struct NodeImageMultiFile {
   /** 1024 = FILE_MAX. */
   char base_path[1024];
@@ -1066,7 +1069,7 @@ typedef struct NodeShaderPrincipled {
   char _pad[3];
 } NodeShaderPrincipled;
 
-/* TEX_output */
+/** TEX_output. */
 typedef struct TexNodeOutput {
   char name[64];
 } TexNodeOutput;
@@ -1632,14 +1635,17 @@ typedef struct NodeFunctionCompare {
 #define NODE_IES_INTERNAL 0
 #define NODE_IES_EXTERNAL 1
 
-/* frame node flags */
+/* Frame node flags. */
+
 #define NODE_FRAME_SHRINK 1     /* keep the bounding box minimal */
 #define NODE_FRAME_RESIZEABLE 2 /* test flag, if frame can be resized by user */
 
-/* proxy node flags */
+/* Proxy node flags. */
+
 #define NODE_PROXY_AUTOTYPE 1 /* automatically change output type based on link */
 
-/* comp channel matte */
+/* Comp channel matte. */
+
 #define CMP_NODE_CHANNEL_MATTE_CS_RGB 1
 #define CMP_NODE_CHANNEL_MATTE_CS_HSV 2
 #define CMP_NODE_CHANNEL_MATTE_CS_YUV 3
@@ -1661,7 +1667,7 @@ typedef struct NodeFunctionCompare {
 #define SHD_VECT_TRANSFORM_SPACE_OBJECT 1
 #define SHD_VECT_TRANSFORM_SPACE_CAMERA 2
 
-/* attribute */
+/** #NodeShaderAttribute.type */
 enum {
   SHD_ATTRIBUTE_GEOMETRY = 0,
   SHD_ATTRIBUTE_OBJECT = 1,
@@ -1795,7 +1801,7 @@ enum {
 #define SHD_AO_INSIDE 1
 #define SHD_AO_LOCAL 2
 
-/* Mapping node vector types. */
+/** Mapping node vector types. */
 enum {
   NODE_MAPPING_TYPE_POINT = 0,
   NODE_MAPPING_TYPE_TEXTURE = 1,
@@ -1803,7 +1809,7 @@ enum {
   NODE_MAPPING_TYPE_NORMAL = 3,
 };
 
-/* Rotation node vector types. */
+/** Rotation node vector types. */
 enum {
   NODE_VECTOR_ROTATE_TYPE_AXIS = 0,
   NODE_VECTOR_ROTATE_TYPE_AXIS_X = 1,
@@ -1815,7 +1821,7 @@ enum {
 /* math node clamp */
 #define SHD_MATH_CLAMP 1
 
-/* Math node operations. */
+/** Math node operations. */
 typedef enum NodeMathOperation {
   NODE_MATH_ADD = 0,
   NODE_MATH_SUBTRACT = 1,
@@ -1859,7 +1865,7 @@ typedef enum NodeMathOperation {
   NODE_MATH_SMOOTH_MAX = 39,
 } NodeMathOperation;
 
-/* Vector Math node operations. */
+/** Vector Math node operations. */
 typedef enum NodeVectorMathOperation {
   NODE_VECTOR_MATH_ADD = 0,
   NODE_VECTOR_MATH_SUBTRACT = 1,
@@ -1893,14 +1899,14 @@ typedef enum NodeVectorMathOperation {
   NODE_VECTOR_MATH_MULTIPLY_ADD = 26,
 } NodeVectorMathOperation;
 
-/* Boolean math node operations. */
+/** Boolean math node operations. */
 enum {
   NODE_BOOLEAN_MATH_AND = 0,
   NODE_BOOLEAN_MATH_OR = 1,
   NODE_BOOLEAN_MATH_NOT = 2,
 };
 
-/* Float compare node operations. */
+/** Float compare node operations. */
 typedef enum NodeCompareMode {
   NODE_COMPARE_MODE_ELEMENT = 0,
   NODE_COMPARE_MODE_LENGTH = 1,
@@ -1921,7 +1927,7 @@ typedef enum NodeCompareOperation {
 
 } NodeCompareOperation;
 
-/* Float to Int node operations. */
+/** Float to Int node operations. */
 typedef enum FloatToIntRoundingMode {
   FN_NODE_FLOAT_TO_INT_ROUND = 0,
   FN_NODE_FLOAT_TO_INT_FLOOR = 1,
@@ -1929,13 +1935,13 @@ typedef enum FloatToIntRoundingMode {
   FN_NODE_FLOAT_TO_INT_TRUNCATE = 3,
 } FloatToIntRoundingMode;
 
-/* Clamp node types. */
+/** Clamp node types. */
 enum {
   NODE_CLAMP_MINMAX = 0,
   NODE_CLAMP_RANGE = 1,
 };
 
-/* Map range node types. */
+/** Map range node types. */
 enum {
   NODE_MAP_RANGE_LINEAR = 0,
   NODE_MAP_RANGE_STEPPED = 1,
@@ -1947,7 +1953,8 @@ enum {
 #define SHD_MIXRGB_USE_ALPHA 1
 #define SHD_MIXRGB_CLAMP 2
 
-/* subsurface */
+/* Subsurface. */
+
 enum {
 #ifdef DNA_DEPRECATED_ALLOW
   SHD_SUBSURFACE_COMPATIBLE = 0, /* Deprecated */
@@ -1978,25 +1985,29 @@ enum {
 /* viewer and composite output. */
 #define CMP_NODE_OUTPUT_IGNORE_ALPHA 1
 
-/* Plane track deform node */
+/* Plane track deform node. */
+
 enum {
   CMP_NODEFLAG_PLANETRACKDEFORM_MOTION_BLUR = 1,
 };
 
-/* Stabilization node */
+/* Stabilization node. */
+
 enum {
   CMP_NODEFLAG_STABILIZE_INVERSE = 1,
 };
 
 /* Set Alpha Node. */
-/* `NodeSetAlpha.mode` */
+
+/** #NodeSetAlpha.mode */
 typedef enum CMPNodeSetAlphaMode {
   CMP_NODE_SETALPHA_MODE_APPLY = 0,
   CMP_NODE_SETALPHA_MODE_REPLACE_ALPHA = 1,
 } CMPNodeSetAlphaMode;
 
 /* Denoise Node. */
-/* `NodeDenoise.prefilter` */
+
+/** #NodeDenoise.prefilter */
 typedef enum CMPNodeDenoisePrefilter {
   CMP_NODE_DENOISE_PREFILTER_FAST = 0,
   CMP_NODE_DENOISE_PREFILTER_NONE = 1,