Cleanup: doxygen comments

Also correct some outdated symbol references,
add missing 'name' commands.

9 files changed, 61 insertions, 32 deletions

diff --git a/source/blender/makesdna/DNA_curveprofile_types.h b/source/blender/makesdna/DNA_curveprofile_types.h
index dba05da910e..13e638437c4 100644
--- a/source/blender/makesdna/DNA_curveprofile_types.h
+++ b/source/blender/makesdna/DNA_curveprofile_types.h
@@ -33,7 +33,8 @@
 /** Dynamic size of widget's high resolution table. Input should be profile->totpoint. */
 #define PROF_N_TABLE(n_pts) min_ii(PROF_TABLE_MAX, (((n_pts - 1)) * PROF_RESOL) + 1)
 
-/** Each control point that makes up the profile.
+/**
+ * Each control point that makes up the profile.
  * \note The flags use the same enum as Bezier curves, but they aren't guaranteed
  * to have identical functionality, and all types aren't implemented.
  */
diff --git a/source/blender/makesdna/DNA_customdata_types.h b/source/blender/makesdna/DNA_customdata_types.h
index 9799489982d..0a6423d569f 100644
--- a/source/blender/makesdna/DNA_customdata_types.h
+++ b/source/blender/makesdna/DNA_customdata_types.h
@@ -32,7 +32,7 @@ extern "C" {
 
 #include "DNA_defs.h"
 
-/** descriptor and storage for a custom data layer */
+/** Descriptor and storage for a custom data layer. */
 typedef struct CustomDataLayer {
   /** Type of data in layer. */
   int type;
@@ -63,9 +63,11 @@ typedef struct CustomDataExternal {
   char filename[1024];
 } CustomDataExternal;
 
-/** structure which stores custom element data associated with mesh elements
+/**
+ * Structure which stores custom element data associated with mesh elements
  * (vertices, edges or faces). The custom data is organized into a series of
- * layers, each with a data type (e.g. MTFace, MDeformVert, etc.). */
+ * layers, each with a data type (e.g. MTFace, MDeformVert, etc.).
+ */
 typedef struct CustomData {
   /** CustomDataLayers, ordered by type. */
   CustomDataLayer *layers;
diff --git a/source/blender/makesdna/DNA_meshdata_types.h b/source/blender/makesdna/DNA_meshdata_types.h
index f6a7a8a5f5b..ebaaf72b3ae 100644
--- a/source/blender/makesdna/DNA_meshdata_types.h
+++ b/source/blender/makesdna/DNA_meshdata_types.h
@@ -59,9 +59,10 @@ typedef struct MVert {
   char flag, bweight;
 } MVert;
 
-/** Tessellation vertex color data.
+/**
+ * Tessellation vertex color data.
  * at the moment alpha is abused for vertex painting and not used for transparency,
- * note that red and blue are swapped
+ * note that red and blue are swapped.
  */
 typedef struct MCol {
   unsigned char a, r, g, b;
diff --git a/source/blender/makesdna/DNA_object_enums.h b/source/blender/makesdna/DNA_object_enums.h
index 75fca117b06..3214de5b3c6 100644
--- a/source/blender/makesdna/DNA_object_enums.h
+++ b/source/blender/makesdna/DNA_object_enums.h
@@ -49,8 +49,10 @@ typedef enum eObjectMode {
 /** Any mode that uses Object.sculpt. */
 #define OB_MODE_ALL_SCULPT (OB_MODE_SCULPT | OB_MODE_VERTEX_PAINT | OB_MODE_WEIGHT_PAINT)
 
-/** Any mode that has data or for Grease Pencil modes, we need to free when switching modes,
- * see: #ED_object_mode_generic_exit */
+/**
+ * Any mode that has data or for Grease Pencil modes, we need to free when switching modes,
+ * see: #ED_object_mode_generic_exit
+ */
 #define OB_MODE_ALL_MODE_DATA \
   (OB_MODE_EDIT | OB_MODE_VERTEX_PAINT | OB_MODE_WEIGHT_PAINT | OB_MODE_SCULPT | OB_MODE_POSE | \
    OB_MODE_PAINT_GPENCIL | OB_MODE_EDIT_GPENCIL | OB_MODE_SCULPT_GPENCIL | \
diff --git a/source/blender/makesdna/DNA_object_force_types.h b/source/blender/makesdna/DNA_object_force_types.h
index 34a1b6d3e0b..8afb74e0786 100644
--- a/source/blender/makesdna/DNA_object_force_types.h
+++ b/source/blender/makesdna/DNA_object_force_types.h
@@ -492,8 +492,10 @@ typedef struct SoftBody {
 #define PTCACHE_READ_INFO (1 << 10)
 /** don't use the filename of the blendfile the data is linked from (write a local cache) */
 #define PTCACHE_IGNORE_LIBPATH (1 << 11)
-/** high resolution cache is saved for smoke for backwards compatibility,
- * so set this flag to know it's a "fake" cache */
+/**
+ * High resolution cache is saved for smoke for backwards compatibility,
+ * so set this flag to know it's a "fake" cache.
+ */
 #define PTCACHE_FAKE_SMOKE (1 << 12)
 #define PTCACHE_IGNORE_CLEAR (1 << 13)
 
diff --git a/source/blender/makesdna/DNA_scene_types.h b/source/blender/makesdna/DNA_scene_types.h
index e60b16453b2..0de43c1632f 100644
--- a/source/blender/makesdna/DNA_scene_types.h
+++ b/source/blender/makesdna/DNA_scene_types.h
@@ -400,7 +400,7 @@ typedef enum eStereo3dInterlaceType {
 typedef struct ImageFormatData {
   /**
    * R_IMF_IMTYPE_PNG, R_...
-   * \note, video types should only ever be set from this structure when used from RenderData.
+   * \note Video types should only ever be set from this structure when used from #RenderData.
    */
   char imtype;
   /**
diff --git a/source/blender/makesdna/DNA_space_types.h b/source/blender/makesdna/DNA_space_types.h
index 8e4c4cc6ed4..9e8bda2d12f 100644
--- a/source/blender/makesdna/DNA_space_types.h
+++ b/source/blender/makesdna/DNA_space_types.h
@@ -973,7 +973,8 @@ typedef struct FileDirEntry {
   int act_variant;
 } FileDirEntry;
 
-/** Array of direntries.
+/**
+ * Array of direntries.
  *
  * This struct is used in various, different contexts.
  *
diff --git a/source/blender/makesdna/DNA_userdef_types.h b/source/blender/makesdna/DNA_userdef_types.h
index 2332fe39de3..3e10e817946 100644
--- a/source/blender/makesdna/DNA_userdef_types.h
+++ b/source/blender/makesdna/DNA_userdef_types.h
@@ -38,8 +38,10 @@ struct ColorBand;
 
 #define MAX_STYLE_NAME 64
 
-/** default offered by Blender.
- * #uiFont.uifont_id */
+/**
+ * Default offered by Blender.
+ * #uiFont.uifont_id
+ */
 typedef enum eUIFont_ID {
   UIFONT_DEFAULT = 0,
   /*  UIFONT_BITMAP   = 1 */ /* UNUSED */
@@ -1024,9 +1026,11 @@ typedef enum eUserpref_UI_Flag {
   USER_HIDE_SYSTEM_BOOKMARKS = (1u << 31),
 } eUserpref_UI_Flag;
 
-/** #UserDef.uiflag2
+/**
+ * #UserDef.uiflag2
  *
- * \note don't add new flags here, use 'uiflag' which has flags free. */
+ * \note don't add new flags here, use 'uiflag' which has flags free.
+ */
 typedef enum eUserpref_UI_Flag2 {
   USER_UIFLAG2_UNUSED_0 = (1 << 0), /* cleared */
   USER_REGION_OVERLAP = (1 << 1),
@@ -1052,8 +1056,10 @@ typedef enum eUserpref_APP_Flag {
   USER_APP_LOCK_UI_LAYOUT = (1 << 0),
 } eUserpref_APP_Flag;
 
-/** Auto-Keying mode.
- * #UserDef.autokey_mode */
+/**
+ * Auto-Keying mode.
+ * #UserDef.autokey_mode
+ */
 typedef enum eAutokey_Mode {
   /* AUTOKEY_ON is a bitflag */
   AUTOKEY_ON = 1,
@@ -1064,15 +1070,18 @@ typedef enum eAutokey_Mode {
   AUTOKEY_MODE_EDITKEYS = 5,
 } eAutokey_Mode;
 
-/** Zoom to frame mode.
- * #UserDef.view_frame_type */
+/**
+ * Zoom to frame mode.
+ * #UserDef.view_frame_type
+ */
 typedef enum eZoomFrame_Mode {
   ZOOM_FRAME_MODE_KEEP_RANGE = 0,
   ZOOM_FRAME_MODE_SECONDS = 1,
   ZOOM_FRAME_MODE_KEYFRAMES = 2,
 } eZoomFrame_Mode;
 
-/** Auto-Keying flag
+/**
+ * Auto-Keying flag
  * #UserDef.autokey_flag (not strictly used when autokeying only -
  * is also used when keyframing these days).
  * \note #eAutokey_Flag is used with a macro, search for lines like IS_AUTOKEY_FLAG(INSERTAVAIL).
@@ -1121,16 +1130,20 @@ typedef enum eDupli_ID_Flags {
   USER_DUP_GPENCIL = (1 << 13),
 } eDupli_ID_Flags;
 
-/** Max anti alias draw method
- * #UserDef.gpu_viewport_antialias */
+/**
+ * Max anti alias draw method
+ * #UserDef.gpu_viewport_antialias
+ */
 typedef enum eOpenGL_AntiAliasMethod {
   USER_AA_NONE = 0,
   USER_AA_FXAA = 1,
   USER_AA_TAA8 = 2,
 } eOpenGL_AntiAliasMethod;
 
-/** Text draw options
- * #UserDef.text_render */
+/**
+ * Text draw options
+ * #UserDef.text_render
+ */
 typedef enum eText_Draw_Options {
   USER_TEXT_DISABLE_AA = (1 << 0),
 
@@ -1139,8 +1152,10 @@ typedef enum eText_Draw_Options {
   USER_TEXT_HINTING_FULL = (1 << 3),
 } eText_Draw_Options;
 
-/** Grease Pencil Settings.
- * #UserDef.gp_settings */
+/**
+ * Grease Pencil Settings.
+ * #UserDef.gp_settings
+ */
 typedef enum eGP_UserdefSettings {
   GP_PAINT_UNUSED_0 = (1 << 0),
 } eGP_UserdefSettings;
@@ -1149,8 +1164,10 @@ enum {
   USER_GIZMO_DRAW = (1 << 0),
 };
 
-/** Color Picker Types.
- * #UserDef.color_picker_type */
+/**
+ * Color Picker Types.
+ * #UserDef.color_picker_type
+ */
 typedef enum eColorPicker_Types {
   USER_CP_CIRCLE_HSV = 0,
   USER_CP_SQUARE_SV = 1,
@@ -1159,8 +1176,10 @@ typedef enum eColorPicker_Types {
   USER_CP_CIRCLE_HSL = 4,
 } eColorPicker_Types;
 
-/** Timecode display styles
- * #UserDef.timecode_style */
+/**
+ * Timecode display styles
+ * #UserDef.timecode_style
+ */
 typedef enum eTimecodeStyles {
   /**
    * As little info as is necessary to show relevant info with '+' to denote the frames
diff --git a/source/blender/makesdna/intern/makesdna.c b/source/blender/makesdna/intern/makesdna.c
index d6f52e48ebe..f4bc79b786a 100644
--- a/source/blender/makesdna/intern/makesdna.c
+++ b/source/blender/makesdna/intern/makesdna.c
@@ -159,7 +159,8 @@ static short *types_size_native;
 static short *types_size_32;
 /** Contains sizes as they are calculated on 64 bit systems. */
 static short *types_size_64;
-/** At `sp = structs[a]` is the first address of a struct definition:
+/**
+ * At `sp = structs[a]` is the first address of a struct definition:
  * - `sp[0]` is type number.
  * - `sp[1]` is the length of the element array (next).
  * - `sp[2]` sp[3] is [(type_index, name_index), ..] (number of pairs is defined by `sp[1]`),