Cleanup: use doxy sections and comments in DNA_scene_types.h

source/blender/makesdna/DNA_scene_types.h

@@ -47,11 +47,9 @@ struct World;
 struct bGPdata;
 struct bNodeTree;
 
-/* ************************************************************* */
-/* Scene Data */
-
-/* ************************************************************* */
-/* Output Format Data */
+/* -------------------------------------------------------------------- */
+/** \name FFMPEG
+ * \{ */
 
 typedef struct AviCodecData {
   /** Save format. */
@@ -100,17 +98,18 @@ typedef enum eFFMpegPreset {
 
   /* Used by WEBM/VP9 and h.264 to control encoding speed vs. file size.
    * WEBM/VP9 use these values directly, whereas h.264 map those to
-   * respectively the MEDIUM, SLOWER, and SUPERFAST presets.
-   */
-  /** the default and recommended for most applications */
+   * respectively the MEDIUM, SLOWER, and SUPERFAST presets. */
+
+  /** The default and recommended for most applications. */
   FFM_PRESET_GOOD = 10,
-  /** recommended if you have lots of time and want the best compression efficiency */
+  /** Recommended if you have lots of time and want the best compression efficiency. */
   FFM_PRESET_BEST = 11,
-  /** recommended for live / fast encoding */
+  /** Recommended for live / fast encoding. */
   FFM_PRESET_REALTIME = 12,
 } eFFMpegPreset;
 
-/* Mapping from easily-understandable descriptions to CRF values.
+/**
+ * Mapping from easily-understandable descriptions to CRF values.
  * Assumes we output 8-bit video. Needs to be remapped if 10-bit
  * is output.
  * We use a slightly wider than "subjectively sane range" according
@@ -160,12 +159,15 @@ typedef struct FFMpegCodecData {
   void *_pad1;
 } FFMpegCodecData;
 
-/* ************************************************************* */
-/* Audio */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Audio
+ * \{ */
 
 typedef struct AudioData {
-  int mixrate; /* 2.5: now in FFMpegCodecData: audio_mixrate */
-  float main;  /* 2.5: now in FFMpegCodecData: audio_volume */
+  int mixrate; /* 2.5: now in FFMpegCodecData: audio_mixrate. */
+  float main;  /* 2.5: now in FFMpegCodecData: audio_volume. */
   float speed_of_sound;
   float doppler_factor;
   int distance_model;
@@ -175,8 +177,9 @@ typedef struct AudioData {
   char _pad2[4];
 } AudioData;
 
-/* *************************************************************** */
-/* Render Layers */
+/* -------------------------------------------------------------------- */
+/** \name Render Layers
+ * \{ */
 
 /** Render Layer. */
 typedef struct SceneRenderLayer {
@@ -196,7 +199,7 @@ typedef struct SceneRenderLayer {
   /** Converted to ViewLayer layflag and flag. */
   int layflag DNA_DEPRECATED;
 
-  /* pass_xor has to be after passflag */
+  /* Pass_xor has to be after passflag. */
   /** Pass_xor has to be after passflag. */
   int passflag DNA_DEPRECATED;
   /** Converted to ViewLayer passflag and flag. */
@@ -227,6 +230,7 @@ typedef struct SceneRenderLayer {
 #define SCE_LAY_MOTION_BLUR (1 << 9)
 
 /* Flags between (1 << 9) and (1 << 15) are set to 1 already, for future options. */
+
 #define SCE_LAY_FLAG_DEFAULT ((1 << 15) - 1)
 
 #define SCE_LAY_UNUSED_4 (1 << 15)
@@ -310,7 +314,13 @@ typedef enum eScenePassType {
 #define RE_PASSNAME_CRYPTOMATTE_ASSET "CryptoAsset"
 #define RE_PASSNAME_CRYPTOMATTE_MATERIAL "CryptoMaterial"
 
-/** View - MultiView. */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Multi-View
+ * \{ */
+
+/** View (Multi-view). */
 typedef struct SceneRenderView {
   struct SceneRenderView *next, *prev;
 
@@ -333,7 +343,7 @@ enum {
   SCE_VIEWS_FORMAT_MULTIVIEW = 1,
 };
 
-/** #ImageFormatData.views_format (also used for #Sequence.views_format) */
+/** #ImageFormatData.views_format (also used for #Sequence.views_format). */
 enum {
   R_IMF_VIEWS_INDIVIDUAL = 0,
   R_IMF_VIEWS_STEREO_3D = 1,
@@ -381,10 +391,15 @@ typedef enum eStereo3dInterlaceType {
   S3D_INTERLACE_CHECKERBOARD = 2,
 } eStereo3dInterlaceType;
 
-/* *************************************************************** */
+/** \} */
 
-/* Generic image format settings,
- * this is used for NodeImageFile and IMAGE_OT_save_as operator too.
+/* -------------------------------------------------------------------- */
+/** \name Image Format Data
+ * \{ */
+
+/**
+ * Generic image format settings,
+ * this is used for #NodeImageFile and IMAGE_OT_save_as operator too.
  *
  * NOTE: its a bit strange that even though this is an image format struct
  * the imtype can still be used to select video formats.
@@ -413,28 +428,29 @@ typedef struct ImageFormatData {
 
   /* --- format specific --- */
 
-  /* OpenEXR */
+  /** OpenEXR. */
   char exr_codec;
 
-  /* Cineon */
+  /** Cineon. */
   char cineon_flag;
   short cineon_white, cineon_black;
   float cineon_gamma;
 
-  /* Jpeg2000 */
+  /** Jpeg2000. */
   char jp2_flag;
   char jp2_codec;
 
-  /* TIFF */
+  /** TIFF. */
   char tiff_codec;
 
   char _pad[4];
 
-  /* Multiview */
+  /** Multi-view. */
   char views_format;
   Stereo3dFormat stereo3d_format;
 
-  /* color management */
+  /* Color management members. */
+
   char color_management;
   char _pad1[7];
   ColorManagedViewSettings view_settings;
@@ -480,22 +496,27 @@ typedef struct ImageFormatData {
 #define R_IMF_FLAG_ZBUF (1 << 0)
 #define R_IMF_FLAG_PREVIEW_JPG (1 << 1)
 
-/* Return values from #BKE_imtype_valid_depths, note this is depths per channel. */
-/** #ImageFormatData.depth */
+/*  */
+
+/**
+ * #ImageFormatData.depth
+ *
+ * Return values from #BKE_imtype_valid_depths, note this is depths per channel.
+ */
 typedef enum eImageFormatDepth {
-  /* 1bits  (unused) */
+  /** 1bits  (unused). */
   R_IMF_CHAN_DEPTH_1 = (1 << 0),
-  /* 8bits  (default) */
+  /** 8bits  (default). */
   R_IMF_CHAN_DEPTH_8 = (1 << 1),
-  /* 10bits (uncommon, Cineon/DPX support) */
+  /** 10bits (uncommon, Cineon/DPX support). */
   R_IMF_CHAN_DEPTH_10 = (1 << 2),
-  /* 12bits (uncommon, jp2/DPX support) */
+  /** 12bits (uncommon, jp2/DPX support). */
   R_IMF_CHAN_DEPTH_12 = (1 << 3),
-  /* 16bits (tiff, half float exr) */
+  /** 16bits (TIFF, half float EXR). */
   R_IMF_CHAN_DEPTH_16 = (1 << 4),
-  /* 24bits (unused) */
+  /** 24bits (unused). */
   R_IMF_CHAN_DEPTH_24 = (1 << 5),
-  /* 32bits (full float exr) */
+  /** 32bits (full float EXR). */
   R_IMF_CHAN_DEPTH_32 = (1 << 6),
 } eImageFormatDepth;
 
@@ -518,16 +539,16 @@ typedef enum eImageFormatDepth {
 #define R_IMF_EXR_CODEC_MAX 10
 
 /** #ImageFormatData.jp2_flag */
-#define R_IMF_JP2_FLAG_YCC (1 << 0) /* when disabled use RGB */ /* was R_JPEG2K_YCC */
-#define R_IMF_JP2_FLAG_CINE_PRESET (1 << 1)                     /* was R_JPEG2K_CINE_PRESET */
-#define R_IMF_JP2_FLAG_CINE_48 (1 << 2)                         /* was R_JPEG2K_CINE_48FPS */
+#define R_IMF_JP2_FLAG_YCC (1 << 0) /* When disabled use RGB. */ /* Was `R_JPEG2K_YCC`. */
+#define R_IMF_JP2_FLAG_CINE_PRESET (1 << 1)                      /* Was `R_JPEG2K_CINE_PRESET`. */
+#define R_IMF_JP2_FLAG_CINE_48 (1 << 2)                          /* Was `R_JPEG2K_CINE_48FPS`. */
 
 /** #ImageFormatData.jp2_codec */
 #define R_IMF_JP2_CODEC_JP2 0
 #define R_IMF_JP2_CODEC_J2K 1
 
 /** #ImageFormatData.cineon_flag */
-#define R_IMF_CINEON_FLAG_LOG (1 << 0) /* was R_CINEON_LOG */
+#define R_IMF_CINEON_FLAG_LOG (1 << 0) /* Was `R_CINEON_LOG`. */
 
 /** #ImageFormatData.tiff_codec */
 enum {
@@ -537,6 +558,12 @@ enum {
   R_IMF_TIFF_CODEC_NONE = 3,
 };
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Render Bake
+ * \{ */
+
 /** #ImageFormatData.color_management */
 #define R_IMF_COLOR_MANAGEMENT_FOLLOW_SCENE 0
 #define R_IMF_COLOR_MANAGEMENT_OVERRIDE 1
@@ -566,13 +593,13 @@ typedef struct BakeData {
   struct Object *cage_object;
 } BakeData;
 
-/** #BakeData.margin_type (char) */
+/** #BakeData.margin_type (char). */
 typedef enum eBakeMarginType {
   R_BAKE_ADJACENT_FACES = 0,
   R_BAKE_EXTEND = 1,
 } eBakeMarginType;
 
-/** #BakeData.normal_swizzle (char) */
+/** #BakeData.normal_swizzle (char). */
 typedef enum eBakeNormalSwizzle {
   R_BAKE_POSX = 0,
   R_BAKE_POSY = 1,
@@ -582,19 +609,19 @@ typedef enum eBakeNormalSwizzle {
   R_BAKE_NEGZ = 5,
 } eBakeNormalSwizzle;
 
-/** #BakeData.target (char) */
+/** #BakeData.target (char). */
 typedef enum eBakeTarget {
   R_BAKE_TARGET_IMAGE_TEXTURES = 0,
   R_BAKE_TARGET_VERTEX_COLORS = 1,
 } eBakeTarget;
 
-/** #BakeData.save_mode (char) */
+/** #BakeData.save_mode (char). */
 typedef enum eBakeSaveMode {
   R_BAKE_SAVE_INTERNAL = 0,
   R_BAKE_SAVE_EXTERNAL = 1,
 } eBakeSaveMode;
 
-/** #BakeData.view_from (char) */
+/** #BakeData.view_from (char). */
 typedef enum eBakeViewFrom {
   R_BAKE_VIEW_FROM_ABOVE_SURFACE = 0,
   R_BAKE_VIEW_FROM_ACTIVE_CAMERA = 1,
@@ -616,8 +643,11 @@ typedef enum eBakePassFilter {
 
 #define R_BAKE_PASS_FILTER_ALL (~0)
 
-/* *************************************************************** */
-/* Render Data */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Render Data
+ * \{ */
 
 typedef struct RenderData {
   struct ImageFormatData im_format;
@@ -640,7 +670,7 @@ typedef struct RenderData {
   /** Frames to jump during render/playback. */
   int frame_step;
 
-  /** Standalone player stereo settings */ /* XXX deprecated since .2.5 */
+  /** Standalone player stereo settings. */ /* XXX deprecated since .2.5 */
   short stereomode DNA_DEPRECATED;
 
   /** For the dimensions presets menu. */
@@ -651,7 +681,7 @@ typedef struct RenderData {
 
   char _pad6[2];
 
-  /* from buttons: */
+  /* From buttons: */
   /**
    * The desired number of pixels in the x direction
    */
@@ -698,7 +728,7 @@ typedef struct RenderData {
   /** Render border to render sub-resions. */
   rctf border;
 
-  /* information on different layers to be rendered */
+  /* Information on different layers to be rendered. */
   /** Converted to Scene->view_layers. */
   ListBase layers DNA_DEPRECATED;
   /** Converted to Scene->active_layer. */
@@ -717,38 +747,38 @@ typedef struct RenderData {
    */
   float gauss;
 
-  /* color management settings - color profiles, gamma correction, etc */
+  /** Color management settings - color profiles, gamma correction, etc. */
   int color_mgt_flag;
 
-  /* Dither noise intensity */
+  /** Dither noise intensity. */
   float dither_intensity;
 
-  /* Bake Render options */
+  /* Bake Render options. */
   short bake_mode, bake_flag;
   short bake_margin, bake_samples;
   short bake_margin_type;
   char _pad9[6];
   float bake_biasdist, bake_user_scale;
 
-  /* path to render output */
+  /* Path to render output. */
   /** 1024 = FILE_MAX. */
   /* NOTE: Excluded from `BKE_bpath_foreach_path_` / `scene_foreach_path` code. */
   char pic[1024];
 
-  /* stamps flags. */
+  /** Stamps flags. */
   int stamp;
   /** Select one of blenders bitmap fonts. */
   short stamp_font_id;
   char _pad3[2];
 
-  /* stamp info user data. */
+  /** Stamp info user data. */
   char stamp_udata[768];
 
-  /* foreground/background color. */
+  /* Foreground/background color. */
   float fg_stamp[4];
   float bg_stamp[4];
 
-  /* sequencer options */
+  /** Sequencer options. */
   char seq_prev_type;
   /** UNUSED. */
   char seq_rend_type;
@@ -756,7 +786,7 @@ typedef struct RenderData {
   char seq_flag;
   char _pad5[3];
 
-  /* render simplify */
+  /* Render simplify. */
   short simplify_subsurf;
   short simplify_subsurf_render;
   short simplify_gpencil;
@@ -764,19 +794,19 @@ typedef struct RenderData {
   float simplify_particles_render;
   float simplify_volumes;
 
-  /* Freestyle line thickness options */
+  /** Freestyle line thickness options. */
   int line_thickness_mode;
   /** In pixels. */
   float unit_line_thickness;
 
-  /* render engine */
+  /** Render engine. */
   char engine[32];
   char _pad2[2];
 
-  /* Performance Options */
+  /** Performance Options. */
   short perf_flag;
 
-  /* Cycles baking */
+  /** Cycles baking. */
   struct BakeData bake;
 
   int _pad8;
@@ -784,16 +814,16 @@ typedef struct RenderData {
 
   short _pad4;
 
-  /* MultiView */
+  /* MultiView. */
   /** SceneRenderView. */
   ListBase views;
   short actview;
   short views_format;
 
-  /* Hair Display */
+  /* Hair Display. */
   short hair_type, hair_subdiv;
 
-  /* Motion blur shutter */
+  /** Motion blur shutter. */
   struct CurveMapping mblur_shutter_curve;
 } RenderData;
 
@@ -808,8 +838,11 @@ typedef enum eHairType {
   SCE_HAIR_SHAPE_STRIP = 1,
 } eHairType;
 
-/* *************************************************************** */
-/* Render Conversion/Simplification Settings */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Render Conversion/Simplification Settings
+ * \{ */
 
 /** Control render convert and shading engine. */
 typedef struct RenderProfile {
@@ -826,7 +859,7 @@ typedef struct RenderProfile {
 
 } RenderProfile;
 
-/* UV Paint */
+/* UV Paint. */
 /** #ToolSettings.uv_sculpt_settings */
 #define UV_SCULPT_LOCK_BORDERS 1
 #define UV_SCULPT_ALL_ISLANDS 2
@@ -836,7 +869,7 @@ typedef struct RenderProfile {
 #define UV_SCULPT_TOOL_RELAX_HC 2
 #define UV_SCULPT_TOOL_RELAX_COTAN 3
 
-/* Stereo Flags */
+/* Stereo Flags. */
 #define STEREO_RIGHT_NAME "right"
 #define STEREO_LEFT_NAME "left"
 #define STEREO_RIGHT_SUFFIX "_R"
@@ -850,8 +883,11 @@ typedef enum eStereoViews {
   STEREO_MONO_ID = 3,
 } eStereoViews;
 
-/* *************************************************************** */
-/* Markers */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Time Line Markers
+ * \{ */
 
 typedef struct TimeMarker {
   struct TimeMarker *next, *prev;
@@ -862,13 +898,16 @@ typedef struct TimeMarker {
   struct IDProperty *prop;
 } TimeMarker;
 
-/* *************************************************************** */
-/* Paint Mode/Tool Data */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Paint Mode/Tool Data
+ * \{ */
 
 #define PAINT_MAX_INPUT_SAMPLES 64
 
 typedef struct Paint_Runtime {
-  /* Avoid having to compare with scene pointer everywhere. */
+  /** Avoid having to compare with scene pointer everywhere. */
   unsigned int tool_offset;
   unsigned short ob_mode;
   char _pad[2];
@@ -883,8 +922,10 @@ typedef struct PaintToolSlot {
 typedef struct Paint {
   struct Brush *brush;
 
-  /* Each tool has its own active brush,
-   * The currently active tool is defined by the current 'brush'. */
+  /**
+   * Each tool has its own active brush,
+   * The currently active tool is defined by the current 'brush'.
+   */
   struct PaintToolSlot *tool_slots;
   int tool_slots_len;
   char _pad1[4];
@@ -893,18 +934,17 @@ typedef struct Paint {
   /** Cavity curve. */
   struct CurveMapping *cavity_curve;
 
-  /* WM Paint cursor */
+  /** WM Paint cursor. */
   void *paint_cursor;
   unsigned char paint_cursor_col[4];
 
-  /* enum ePaintFlags */
+  /** Enum #ePaintFlags. */
   int flags;
 
-  /* Paint stroke can use up to PAINT_MAX_INPUT_SAMPLES inputs to
-   * smooth the stroke */
+  /** Paint stroke can use up to PAINT_MAX_INPUT_SAMPLES inputs to smooth the stroke. */
   int num_input_samples;
 
-  /* flags used for symmetry */
+  /** Flags used for symmetry. */
   int symmetry_flags;
 
   float tile_offset[3];
@@ -913,8 +953,11 @@ typedef struct Paint {
   struct Paint_Runtime runtime;
 } Paint;
 
-/* ------------------------------------------- */
-/* Image Paint */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Image Paint
+ * \{ */
 
 /** Texture/Image Editor. */
 typedef struct ImagePaintSettings {
@@ -922,7 +965,7 @@ typedef struct ImagePaintSettings {
 
   short flag, missing_data;
 
-  /* for projection painting only */
+  /** For projection painting only. */
   short seam_bleed, normal_angle;
   /** Capture size for re-projection. */
   short screen_grab_size[2];
@@ -944,11 +987,14 @@ typedef struct ImagePaintSettings {
   char _pad[4];
 } ImagePaintSettings;
 
-/* ------------------------------------------- */
-/* Paint mode settings */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Paint Mode Settings
+ * \{ */
 
 typedef struct PaintModeSettings {
-  /** Source to select canvas from to paint on (ePaintCanvasSource) */
+  /** Source to select canvas from to paint on (#ePaintCanvasSource). */
   char canvas_source;
   char _pad[7];
 
@@ -958,8 +1004,11 @@ typedef struct PaintModeSettings {
 
 } PaintModeSettings;
 
-/* ------------------------------------------- */
-/* Particle Edit */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Particle Edit
+ * \{ */
 
 /** Settings for a Particle Editing Brush. */
 typedef struct ParticleBrushData {
@@ -995,36 +1044,39 @@ typedef struct ParticleEditSettings {
   struct Object *shape_object;
 } ParticleEditSettings;
 
-/* ------------------------------------------- */
-/* Sculpt */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Sculpt
+ * \{ */
 
 /** Sculpt. */
 typedef struct Sculpt {
   Paint paint;
 
-  /* For rotating around a pivot point */
+  /** For rotating around a pivot point. */
   // float pivot[3]; XXX not used?
   int flags;
 
-  /* Transform tool. */
+  /** Transform tool. */
   int transform_mode;
 
   int automasking_flags;
 
-  /* Control tablet input */
+  // /* Control tablet input. */
   // char tablet_size, tablet_strength; XXX not used?
   int radial_symm[3];
 
-  /* Maximum edge length for dynamic topology sculpting (in pixels) */
+  /** Maximum edge length for dynamic topology sculpting (in pixels). */
   float detail_size;
 
-  /* Direction used for SCULPT_OT_symmetrize operator */
+  /** Direction used for `SCULPT_OT_symmetrize` operator. */
   int symmetrize_direction;
 
-  /* gravity factor for sculpting */
+  /** Gravity factor for sculpting. */
   float gravity_factor;
 
-  /* scale for constant detail size */
+  /* Scale for constant detail size. */
   /** Constant detail resolution (Blender unit / constant_detail). */
   float constant_detail;
   float detail_percent;
@@ -1037,7 +1089,8 @@ typedef struct Sculpt {
   float automasking_view_normal_limit, automasking_view_normal_falloff;
 
   struct CurveMapping *automasking_cavity_curve;
-  struct CurveMapping *automasking_cavity_curve_op; /* For use by operators */
+  /** For use by operators. */
+  struct CurveMapping *automasking_cavity_curve_op;
   struct Object *gravity_object;
 } Sculpt;
 
@@ -1053,7 +1106,7 @@ typedef struct UvSculpt {
 typedef struct GpPaint {
   Paint paint;
   int flag;
-  /* Mode of paint (Materials or Vertex Color). */
+  /** Mode of paint (Materials or Vertex Color). */
   int mode;
 } GpPaint;
 
@@ -1084,8 +1137,11 @@ typedef struct GpWeightPaint {
   char _pad[4];
 } GpWeightPaint;
 
-/* ------------------------------------------- */
-/* Vertex Paint */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Vertex Paint
+ * \{ */
 
 /** Vertex Paint. */
 typedef struct VPaint {
@@ -1098,12 +1154,15 @@ typedef struct VPaint {
 
 /** #VPaint.flag */
 enum {
-  /* weight paint only */
+  /** Weight paint only. */
   VP_FLAG_VGROUP_RESTRICT = (1 << 7),
 };
 
-/* ------------------------------------------- */
-/* GPencil Stroke Sculpting */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Grease-Pencil Stroke Sculpting
+ * \{ */
 
 /** #GP_Sculpt_Settings.lock_axis */
 typedef enum eGP_Lockaxis_Types {
@@ -1136,14 +1195,14 @@ typedef struct GP_Sculpt_Settings {
   int flag;
   /** #eGP_Lockaxis_Types lock drawing to one axis. */
   int lock_axis;
-  /** Threshold for intersections */
+  /** Threshold for intersections. */
   float isect_threshold;
   char _pad[4];
   /** Multi-frame edit falloff effect by frame. */
   struct CurveMapping *cur_falloff;
   /** Curve used for primitive tools. */
   struct CurveMapping *cur_primitive;
-  /** Guides used for paint tools */
+  /** Guides used for paint tools. */
   struct GP_Sculpt_Guide guide;
 } GP_Sculpt_Settings;
 
@@ -1155,15 +1214,15 @@ typedef enum eGP_Sculpt_SettingsFlag {
   GP_SCULPT_SETT_FLAG_PRIMITIVE_CURVE = (1 << 1),
   /** Scale thickness. */
   GP_SCULPT_SETT_FLAG_SCALE_THICKNESS = (1 << 3),
-  /* Stroke Auto-Masking for sculpt. */
+  /** Stroke Auto-Masking for sculpt. */
   GP_SCULPT_SETT_FLAG_AUTOMASK_STROKE = (1 << 4),
-  /* Stroke Layer Auto-Masking for sculpt. */
+  /** Stroke Layer Auto-Masking for sculpt. */
   GP_SCULPT_SETT_FLAG_AUTOMASK_LAYER_STROKE = (1 << 5),
-  /* Stroke Material Auto-Masking for sculpt. */
+  /** Stroke Material Auto-Masking for sculpt. */
   GP_SCULPT_SETT_FLAG_AUTOMASK_MATERIAL_STROKE = (1 << 6),
-  /* Active Layer Auto-Masking for sculpt. */
+  /** Active Layer Auto-Masking for sculpt. */
   GP_SCULPT_SETT_FLAG_AUTOMASK_LAYER_ACTIVE = (1 << 7),
-  /* Active Material Auto-Masking for sculpt. */
+  /** Active Material Auto-Masking for sculpt. */
   GP_SCULPT_SETT_FLAG_AUTOMASK_MATERIAL_ACTIVE = (1 << 8),
 } eGP_Sculpt_SettingsFlag;
 
@@ -1173,7 +1232,7 @@ typedef enum eGP_Sculpt_SelectMaskFlag {
   GP_SCULPT_MASK_SELECTMODE_POINT = (1 << 0),
   /** Only affect selected strokes. */
   GP_SCULPT_MASK_SELECTMODE_STROKE = (1 << 1),
-  /** only affect selected segments. */
+  /** Only affect selected segments. */
   GP_SCULPT_MASK_SELECTMODE_SEGMENT = (1 << 2),
 } eGP_Sculpt_SelectMaskFlag;
 
@@ -1195,23 +1254,23 @@ typedef struct GP_Interpolate_Settings {
 
 /** #GP_Interpolate_Settings.flag */
 typedef enum eGP_Interpolate_SettingsFlag {
-  /* apply interpolation to all layers */
+  /** Apply interpolation to all layers. */
   GP_TOOLFLAG_INTERPOLATE_ALL_LAYERS = (1 << 0),
-  /* apply interpolation to only selected */
+  /** Apply interpolation to only selected. */
   GP_TOOLFLAG_INTERPOLATE_ONLY_SELECTED = (1 << 1),
-  /* Exclude breakdown keyframe type as extreme */
+  /** Exclude breakdown keyframe type as extreme. */
   GP_TOOLFLAG_INTERPOLATE_EXCLUDE_BREAKDOWNS = (1 << 2),
 } eGP_Interpolate_SettingsFlag;
 
 /** #GP_Interpolate_Settings.type */
 typedef enum eGP_Interpolate_Type {
-  /* Traditional Linear Interpolation */
+  /** Traditional Linear Interpolation. */
   GP_IPO_LINEAR = 0,
 
-  /* CurveMap Defined Interpolation */
+  /** CurveMap Defined Interpolation. */
   GP_IPO_CURVEMAP = 1,
 
-  /* Easing Equations */
+  /* Easing Equations. */
   GP_IPO_BACK = 3,
   GP_IPO_BOUNCE = 4,
   GP_IPO_CIRC = 5,
@@ -1224,37 +1283,41 @@ typedef enum eGP_Interpolate_Type {
   GP_IPO_SINE = 12,
 } eGP_Interpolate_Type;
 
-/* *************************************************************** */
-/* Unified Paint Settings
- */
+/** \} */
 
-/* These settings can override the equivalent fields in the active
+/* -------------------------------------------------------------------- */
+/** \name Unified Paint Settings
+ * \{ */
+
+/**
+ * These settings can override the equivalent fields in the active
  * Brush for any paint mode; the flag field controls whether these
- * values are used */
+ * values are used
+ */
 typedef struct UnifiedPaintSettings {
-  /* unified radius of brush in pixels */
+  /** Unified radius of brush in pixels. */
   int size;
 
-  /* unified radius of brush in Blender units */
+  /** Unified radius of brush in Blender units. */
   float unprojected_radius;
 
-  /* unified strength of brush */
+  /** Unified strength of brush. */
   float alpha;
 
-  /* unified brush weight, [0, 1] */
+  /** Unified brush weight, [0, 1]. */
   float weight;
 
-  /* unified brush color */
+  /** Unified brush color. */
   float rgb[3];
-  /* unified brush secondary color */
+  /** Unified brush secondary color. */
   float secondary_rgb[3];
 
-  /* user preferences for sculpt and paint */
+  /** User preferences for sculpt and paint. */
   int flag;
 
-  /* rake rotation */
+  /* Rake rotation. */
 
-  /* record movement of mouse so that rake can start at an intuitive angle */
+  /** Record movement of mouse so that rake can start at an intuitive angle. */
   float last_rake[2];
   float last_rake_angle;
 
@@ -1277,35 +1340,39 @@ typedef struct UnifiedPaintSettings {
    */
   float overlap_factor;
   char draw_inverted;
-  /* check is there an ongoing stroke right now */
+  /** Check is there an ongoing stroke right now. */
   char stroke_active;
 
   char draw_anchored;
   char do_linear_conversion;
 
-  /* store last location of stroke or whether the mesh was hit.
-   * Valid only while stroke is active */
+  /**
+   * Store last location of stroke or whether the mesh was hit.
+   * Valid only while stroke is active.
+   */
   float last_location[3];
   int last_hit;
 
   float anchored_initial_mouse[2];
 
-  /* radius of brush, premultiplied with pressure.
-   * In case of anchored brushes contains the anchored radius */
+  /**
+   * Radius of brush, pre-multiplied with pressure.
+   * In case of anchored brushes contains the anchored radius.
+   */
   float pixel_radius;
   float initial_pixel_radius;
   float start_pixel_radius;
 
-  /* drawing pressure */
+  /** Drawing pressure. */
   float size_pressure_value;
 
-  /* position of mouse, used to sample the texture */
+  /** Position of mouse, used to sample the texture. */
   float tex_mouse[2];
 
-  /* position of mouse, used to sample the mask texture */
+  /** Position of mouse, used to sample the mask texture. */
   float mask_tex_mouse[2];
 
-  /* ColorSpace cache to avoid locking up during sampling */
+  /** ColorSpace cache to avoid locking up during sampling. */
   struct ColorSpace *colorspace;
 } UnifiedPaintSettings;
 
@@ -1316,7 +1383,7 @@ typedef enum {
   UNIFIED_PAINT_WEIGHT = (1 << 5),
   UNIFIED_PAINT_COLOR = (1 << 6),
 
-  /* only used if unified size is enabled, mirrors the brush flag BRUSH_LOCK_SIZE */
+  /** Only used if unified size is enabled, mirrors the brush flag #BRUSH_LOCK_SIZE. */
   UNIFIED_PAINT_BRUSH_LOCK_SIZE = (1 << 2),
   UNIFIED_PAINT_FLAG_UNUSED_0 = (1 << 3),
 
@@ -1364,36 +1431,45 @@ enum {
   CURVE_PAINT_SURFACE_PLANE_VIEW = 2,
 };
 
-/* *************************************************************** */
-/* Stats */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Mesh Visualization
+ * \{ */
 
 /** Stats for Meshes. */
 typedef struct MeshStatVis {
   char type;
   char _pad1[2];
 
-  /* overhang */
+  /* Overhang. */
   char overhang_axis;
   float overhang_min, overhang_max;
 
-  /* thickness */
+  /* Thickness. */
   float thickness_min, thickness_max;
   char thickness_samples;
   char _pad2[3];
 
-  /* distort */
+  /* Distort. */
   float distort_min, distort_max;
 
-  /* sharp */
+  /* Sharp. */
   float sharp_min, sharp_max;
 } MeshStatVis;
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Sequencer Tool Settings
+ * \{ */
+
 typedef struct SequencerToolSettings {
-  /* eSeqImageFitMethod */
+  /** #eSeqImageFitMethod. */
   int fit_method;
   short snap_mode;
   short snap_flag;
-  /* eSeqOverlapMode */
+  /** #eSeqOverlapMode. */
   int overlap_mode;
   /**
    * When there are many snap points,
@@ -1416,8 +1492,11 @@ typedef enum eSeqImageFitMethod {
   SEQ_USE_ORIGINAL_SIZE,
 } eSeqImageFitMethod;
 
-/* *************************************************************** */
-/* Tool Settings */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Tool Settings
+ * \{ */
 
 /** #CurvePaintSettings.surface_plane */
 enum {
@@ -1444,8 +1523,7 @@ typedef struct ToolSettings {
   /** Curves sculpt. */
   CurvesSculpt *curves_sculpt;
 
-  /* Vertex group weight - used only for editmode, not weight
-   * paint */
+  /** Vertex group weight - used only for editmode, not weight paint. */
   float vgroup_weight;
 
   /** Remove doubles limit. */
@@ -1453,10 +1531,10 @@ typedef struct ToolSettings {
   char automerge;
   char object_flag;
 
-  /* Selection Mode for Mesh */
+  /** Selection Mode for Mesh. */
   char selectmode;
 
-  /* UV Calculation */
+  /* UV Calculation. */
   char unwrapper;
   char uvcalc_flag;
   char uv_flag;
@@ -1465,11 +1543,11 @@ typedef struct ToolSettings {
 
   float uvcalc_margin;
 
-  /* Auto-IK */
+  /* Auto-IK. */
   /** Runtime only. */
   short autoik_chainlen;
 
-  /* Grease Pencil */
+  /* Grease Pencil. */
   /** Flags/options for how the tool works. */
   char gpencil_flags;
 
@@ -1479,7 +1557,7 @@ typedef struct ToolSettings {
   char gpencil_v2d_align;
   char _pad0[2];
 
-  /* Annotations */
+  /* Annotations. */
   /** Stroke placement settings - 3D View. */
   char annotate_v3d_align;
 
@@ -1490,43 +1568,44 @@ typedef struct ToolSettings {
   /** Stroke selection mode for Sculpt. */
   char gpencil_selectmode_sculpt;
 
-  /* Grease Pencil Sculpt */
+  /** Grease Pencil Sculpt. */
   struct GP_Sculpt_Settings gp_sculpt;
 
-  /* Grease Pencil Interpolation Tool(s) */
+  /** Grease Pencil Interpolation Tool(s). */
   struct GP_Interpolate_Settings gp_interpolate;
 
-  /* Image Paint (8 bytes aligned please!) */
+  /** Image Paint (8 bytes aligned please!). */
   struct ImagePaintSettings imapaint;
 
   /** Settings for paint mode. */
   struct PaintModeSettings paint_mode;
 
-  /* Particle Editing */
+  /** Particle Editing. */
   struct ParticleEditSettings particle;
 
-  /* Transform Proportional Area of Effect */
+  /** Transform Proportional Area of Effect. */
   float proportional_size;
 
-  /* Select Group Threshold */
+  /** Select Group Threshold. */
   float select_thresh;
 
-  /* Auto-Keying Mode */
+  /* Auto-Keying Mode. */
   /** Defines in DNA_userdef_types.h. */
   short autokey_flag;
   char autokey_mode;
   /** Keyframe type (see DNA_curve_types.h). */
   char keyframe_type;
 
-  /* Multires */
+  /* Multires. */
   char multires_subdiv_type;
 
-  /* Edge tagging, store operator settings (no UI access). */
+  /** Edge tagging, store operator settings (no UI access). */
   char edge_mode;
 
   char edge_mode_live_unwrap;
 
-  /* Transform */
+  /* Transform. */
+
   char transform_pivot_point;
   char transform_flag;
   /** Snap elements (per space-type), #eSnapMode. */
@@ -1540,13 +1619,15 @@ typedef struct ToolSettings {
   short snap_flag_seq;
   short snap_uv_flag;
   /** Default snap source, #eSnapSourceSelect. */
-  /* TODO(@gfxcoder): Rename `snap_target` to `snap_source` to avoid previous ambiguity of
+  /**
+   * TODO(@gfxcoder): Rename `snap_target` to `snap_source` to avoid previous ambiguity of
    * "target" (now, "source" is geometry to be moved and "target" is geometry to which moved
-   * geometry is snapped). */
+   * geometry is snapped).
+   */
   char snap_target;
   /** Snap mask for transform modes, #eSnapTransformMode. */
   char snap_transform_mode_flag;
-  /** Steps to break transformation into with face nearest snapping */
+  /** Steps to break transformation into with face nearest snapping. */
   short snap_face_nearest_steps;
 
   char proportional_edit, prop_mode;
@@ -1575,47 +1656,54 @@ typedef struct ToolSettings {
   /** Stroke selection mode for Vertex Paint. */
   char gpencil_selectmode_vertex;
 
-  /* UV painting */
+  /* UV painting. */
   char uv_sculpt_settings;
   char uv_relax_method;
 
   char workspace_tool_type;
 
-  /* XXX: these sculpt_paint_* fields are deprecated, use the
-   * unified_paint_settings field instead! */
+  /**
+   * XXX: these `sculpt_paint_*` fields are deprecated, use the
+   * unified_paint_settings field instead!
+   */
   short sculpt_paint_settings DNA_DEPRECATED;
   int sculpt_paint_unified_size DNA_DEPRECATED;
   float sculpt_paint_unified_unprojected_radius DNA_DEPRECATED;
   float sculpt_paint_unified_alpha DNA_DEPRECATED;
 
-  /* Unified Paint Settings */
+  /** Unified Paint Settings. */
   struct UnifiedPaintSettings unified_paint_settings;
 
   struct CurvePaintSettings curve_paint_settings;
 
   struct MeshStatVis statvis;
 
-  /* Normal Editing */
+  /** Normal Editing. */
   float normal_vector[3];
   char _pad6[4];
 
-  /* Custom Curve Profile for bevel tool:
+  /**
+   * Custom Curve Profile for bevel tool:
    * Temporary until there is a proper preset system that stores the profiles or maybe stores
-   * entire bevel configurations. */
+   * entire bevel configurations.
+   */
   struct CurveProfile *custom_bevel_profile_preset;
 
   struct SequencerToolSettings *sequencer_tool_settings;
 
 } ToolSettings;
 
-/* *************************************************************** */
-/* Assorted Scene Data */
+/** \} */
 
-/* ------------------------------------------- */
-/* Unit Settings */
+/* Assorted Scene Data. */
 
+/* -------------------------------------------------------------------- */
+/** \name Unit Settings
+ * \{ */
+
+/** Display/Editing unit options for each scene. */
 typedef struct UnitSettings {
-  /* Display/Editing unit options for each scene */
+
   /** Maybe have other unit conversions? */
   float scale_length;
   /** Imperial, metric etc. */
@@ -1632,8 +1720,11 @@ typedef struct UnitSettings {
   char _pad[4];
 } UnitSettings;
 
-/* ------------------------------------------- */
-/* Global/Common Physics Settings */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Global/Common Physics Settings
+ * \{ */
 
 typedef struct PhysicsSettings {
   float gravity[3];
@@ -1645,15 +1736,15 @@ typedef struct PhysicsSettings {
  * Safe Area options used in Camera View & Sequencer.
  */
 typedef struct DisplaySafeAreas {
-  /* each value represents the (x,y) margins as a multiplier.
-   * 'center' in this context is just the name for a different kind of safe-area */
+  /* Each value represents the (x,y) margins as a multiplier.
+   * 'center' in this context is just the name for a different kind of safe-area. */
 
   /** Title Safe. */
   float title[2];
   /** Image/Graphics Safe. */
   float action[2];
 
-  /* use for alternate aspect ratio */
+  /* Use for alternate aspect ratio. */
   float title_center[2];
   float action_center[2];
 } DisplaySafeAreas;
@@ -1671,7 +1762,7 @@ typedef struct SceneDisplay {
   float matcap_ssao_attenuation;
   int matcap_ssao_samples;
 
-  /** Method of AA for viewport rendering and image rendering */
+  /** Method of AA for viewport rendering and image rendering. */
   char viewport_aa;
   char render_aa;
   char _pad[6];
@@ -1752,8 +1843,11 @@ typedef struct SceneGpencil {
   char _pad[4];
 } SceneGpencil;
 
-/* *************************************************************** */
-/* Scene ID-Block */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Transform Orientation
+ * \{ */
 
 typedef struct TransformOrientationSlot {
   int type;
@@ -1762,7 +1856,7 @@ typedef struct TransformOrientationSlot {
   char _pad0[7];
 } TransformOrientationSlot;
 
-/** Indices when used in #Scene.orientation_slots */
+/** Indices when used in #Scene.orientation_slots. */
 enum {
   SCE_ORIENT_DEFAULT = 0,
   SCE_ORIENT_TRANSLATE = 1,
@@ -1770,11 +1864,17 @@ enum {
   SCE_ORIENT_SCALE = 3,
 };
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Scene ID-Block
+ * \{ */
+
 typedef struct Scene {
   ID id;
   /** Animation data (must be immediately after id for utilities to use it). */
   struct AnimData *adt;
-  /* runtime (must be immediately after id for utilities to use it). */
+  /** Runtime (must be immediately after id for utilities to use it). */
   DrawDataList drawdata;
 
   struct Object *camera;
@@ -1790,9 +1890,9 @@ typedef struct Scene {
   /** 3d cursor location. */
   View3DCursor cursor;
 
-  /** Bitflags for layer visibility (deprecated). */
+  /** Bit-flags for layer visibility (deprecated). */
   unsigned int lay DNA_DEPRECATED;
-  /** Active layer (deprecated) */
+  /** Active layer (deprecated). */
   int layact DNA_DEPRECATED;
   char _pad2[4];
 
@@ -1812,8 +1912,8 @@ typedef struct Scene {
   void *_pad4;
   struct DisplaySafeAreas safe_areas;
 
-  /* migrate or replace? depends on some internal things... */
-  /* no, is on the right place (ton) */
+  /* Migrate or replace? depends on some internal things... */
+  /* No, is on the right place (ton). */
   struct RenderData r;
   struct AudioData audio;
 
@@ -1831,55 +1931,57 @@ typedef struct Scene {
   /** (runtime) info/cache used for presenting playback framerate info to the user. */
   void *fps_info;
 
-  /* None of the dependency graph vars is mean to be saved. */
+  /** None of the dependency graph vars is mean to be saved. */
   struct GHash *depsgraph_hash;
   char _pad7[4];
 
-  /* User-Defined KeyingSets */
+  /* User-Defined KeyingSets. */
   /**
    * Index of the active KeyingSet.
    * first KeyingSet has index 1, 'none' active is 0, 'add new' is -1
    */
   int active_keyingset;
-  /** KeyingSets for this scene */
+  /** KeyingSets for this scene. */
   ListBase keyingsets;
 
-  /* Units */
+  /* Units. */
   struct UnitSettings unit;
 
-  /** Grease Pencil - Annotations */
+  /** Grease Pencil - Annotations. */
   struct bGPdata *gpd;
 
-  /* Movie Tracking */
+  /* Movie Tracking. */
   /** Active movie clip. */
   struct MovieClip *clip;
 
-  /* Physics simulation settings */
+  /** Physics simulation settings. */
   struct PhysicsSettings physics_settings;
 
   void *_pad8;
-  /* XXX. runtime flag for drawing, actually belongs in the window,
-   * only used by BKE_object_handle_update() */
+  /**
+   * XXX: runtime flag for drawing, actually belongs in the window,
+   * only used by #BKE_object_handle_update()
+   */
   struct CustomData_MeshMasks customdata_mask;
-  /* XXX. same as above but for temp operator use (gl renders) */
+  /** XXX: same as above but for temp operator use (viewport renders). */
   struct CustomData_MeshMasks customdata_mask_modal;
 
-  /* Color Management */
+  /* Color Management. */
   ColorManagedViewSettings view_settings;
   ColorManagedDisplaySettings display_settings;
   ColorManagedColorspaceSettings sequencer_colorspace_settings;
 
-  /* RigidBody simulation world+settings */
+  /** RigidBody simulation world+settings. */
   struct RigidBodyWorld *rigidbody_world;
 
   struct PreviewImage *preview;
 
   ListBase view_layers;
-  /* Not an actual datablock, but memory owned by scene. */
+  /** Not an actual data-block, but memory owned by scene. */
   struct Collection *master_collection;
   struct SceneCollection *collection DNA_DEPRECATED;
 
-  /** Settings to be override by workspaces. */
+  /** Settings to be override by work-spaces. */
   IDProperty *layer_properties;
   void *_pad9;
 
@@ -1888,16 +1990,20 @@ typedef struct Scene {
   struct SceneGpencil grease_pencil_settings;
 } Scene;
 
-/* **************** RENDERDATA ********************* */
+/** \} */
 
-/** #RenderData.flag */
-/* use preview range */
+/* -------------------------------------------------------------------- */
+/** \name Render Data Enum/Flags
+ * \{ */
+
+/** #RenderData.flag. */
+/* Use preview range. */
 #define SCER_PRV_RANGE (1 << 0)
 #define SCER_LOCK_FRAME_SELECTION (1 << 1)
-/* show/use subframes (for checking motion blur) */
+/* Show/use subframes (for checking motion blur). */
 #define SCER_SHOW_SUBFRAME (1 << 3)
 
-/** #RenderData.mode */
+/** #RenderData.mode. */
 #define R_MODE_UNUSED_0 (1 << 0) /* dirty */
 #define R_MODE_UNUSED_1 (1 << 1) /* cleared */
 #define R_MODE_UNUSED_2 (1 << 2) /* cleared */
@@ -1923,11 +2029,11 @@ typedef struct Scene {
 
 #define R_MODE_UNUSED_20 (1 << 20) /* cleared */
 #define R_MODE_UNUSED_21 (1 << 21) /* cleared */
-#define R_NO_OVERWRITE (1 << 22)   /* skip existing files */
-#define R_TOUCH (1 << 23)          /* touch files before rendering */
+#define R_NO_OVERWRITE (1 << 22)   /* Skip existing files. */
+#define R_TOUCH (1 << 23)          /* Touch files before rendering. */
 #define R_SIMPLIFY (1 << 24)
 #define R_EDGE_FRS (1 << 25)        /* R_EDGE reserved for Freestyle */
-#define R_PERSISTENT_DATA (1 << 26) /* keep data around for re-render */
+#define R_PERSISTENT_DATA (1 << 26) /* Keep data around for re-render. */
 #define R_MODE_UNUSED_27 (1 << 27)  /* cleared */
 
 /** #RenderData.seq_flag */
@@ -1953,7 +2059,7 @@ enum {
 /** #RenderData.scemode */
 #define R_DOSEQ (1 << 0)
 #define R_BG_RENDER (1 << 1)
-/* passepartout is camera option now, keep this for backward compatibility */
+/* Passepartout is camera option now, keep this for backward compatibility. */
 #define R_PASSEPARTOUT (1 << 2)
 #define R_BUTS_PREVIEW (1 << 3)
 #define R_EXTENSION (1 << 4)
@@ -1982,7 +2088,8 @@ enum {
 #define R_STAMP_CAMERA (1 << 3)
 #define R_STAMP_SCENE (1 << 4)
 #define R_STAMP_NOTE (1 << 5)
-#define R_STAMP_DRAW (1 << 6) /* draw in the image */
+/** Draw in the image space. */
+#define R_STAMP_DRAW (1 << 6)
 #define R_STAMP_MARKER (1 << 7)
 #define R_STAMP_FILENAME (1 << 8)
 #define R_STAMP_SEQSTRIP (1 << 9)
@@ -2007,12 +2114,12 @@ enum {
 
 /** #RenderData.color_mgt_flag */
 enum {
-  /** deprecated, should only be used in versioning code only */
+  /** Deprecated, should only be used in versioning code only. */
   R_COLOR_MANAGEMENT = (1 << 0),
   R_COLOR_MANAGEMENT_UNUSED_1 = (1 << 1),
 };
 
-/* bake_mode: same as RE_BAKE_xxx defines */
+/* bake_mode: same as RE_BAKE_xxx defines. */
 /** #RenderData.bake_flag */
 #define R_BAKE_CLEAR (1 << 0)
 /* #define R_BAKE_OSA       (1 << 1) */ /* deprecated */
@@ -2036,29 +2143,39 @@ enum {
 #define R_LINE_THICKNESS_ABSOLUTE 1
 #define R_LINE_THICKNESS_RELATIVE 2
 
-/* sequencer seq_prev_type seq_rend_type */
+/* Sequencer seq_prev_type seq_rend_type. */
 
 /** #RenderData.engine (scene.cc) */
 extern const char *RE_engine_id_BLENDER_EEVEE;
 extern const char *RE_engine_id_BLENDER_WORKBENCH;
 extern const char *RE_engine_id_CYCLES;
 
-/* **************** SCENE ********************* */
+/** \} */
 
-/* note that much higher maxframes give imprecise sub-frames, see: T46859 */
+/* -------------------------------------------------------------------- */
+/** \name Scene Defines
+ * \{ */
+
+/* Note that much higher max-frames give imprecise sub-frames, see: T46859. */
 /* Current precision is 16 for the sub-frames closer to MAXFRAME. */
 
-/* for general use */
+/* For general use. */
 #define MAXFRAME 1048574
 #define MAXFRAMEF 1048574.0f
 
 #define MINFRAME 0
 #define MINFRAMEF 0.0f
 
-/* (minimum frame number for current-frame) */
+/** (Minimum frame number for current-frame). */
 #define MINAFRAME -1048574
 #define MINAFRAMEF -1048574.0f
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Scene Related Macros
+ * \{ */
+
 #define BASE_VISIBLE(v3d, base) BKE_base_is_visible(v3d, base)
 #define BASE_SELECTABLE(v3d, base) \
   (BASE_VISIBLE(v3d, base) && \
@@ -2089,7 +2206,13 @@ extern const char *RE_engine_id_CYCLES;
 #define TIME2FRA(a) ((((double)scene->r.frs_sec) * (double)(a)) / (double)scene->r.frs_sec_base)
 #define FPS (((double)scene->r.frs_sec) / (double)scene->r.frs_sec_base)
 
-/* Base.flag is in DNA_object_types.h */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Scene Enum/Flags
+ * \{ */
+
+/* Base.flag is in `DNA_object_types.h`. */
 
 /** #ToolSettings.transform_flag */
 enum {
@@ -2114,12 +2237,14 @@ typedef enum eSnapFlag {
   SCE_SNAP = (1 << 0),
   SCE_SNAP_ROTATE = (1 << 1),
   SCE_SNAP_PEEL_OBJECT = (1 << 2),
-  SCE_SNAP_PROJECT = (1 << 3),       /* Project individual elements instead of whole object. */
-  SCE_SNAP_NOT_TO_ACTIVE = (1 << 4), /* Was `SCE_SNAP_NO_SELF`, but self should be active. */
+  /** Project individual elements instead of whole object. */
+  SCE_SNAP_PROJECT = (1 << 3),
+  /** Was `SCE_SNAP_NO_SELF`, but self should be active. */
+  SCE_SNAP_NOT_TO_ACTIVE = (1 << 4),
   SCE_SNAP_ABS_GRID = (1 << 5),
   SCE_SNAP_BACKFACE_CULLING = (1 << 6),
   SCE_SNAP_KEEP_ON_SAME_OBJECT = (1 << 7),
-  /* see #eSnapTargetSelect */
+  /** see #eSnapTargetSelect */
   SCE_SNAP_TO_INCLUDE_EDITED = (1 << 8),
   SCE_SNAP_TO_INCLUDE_NONEDITED = (1 << 9),
   SCE_SNAP_TO_ONLY_SELECTABLE = (1 << 10),
@@ -2140,8 +2265,11 @@ typedef enum eSnapSourceSelect {
 
 ENUM_OPERATORS(eSnapSourceSelect, SCE_SNAP_SOURCE_ACTIVE)
 
-/** #TransSnap.target_select and #ToolSettings.snap_flag (#SCE_SNAP_NOT_TO_ACTIVE,
- * #SCE_SNAP_TO_INCLUDE_EDITED, #SCE_SNAP_TO_INCLUDE_NONEDITED, #SCE_SNAP_TO_ONLY_SELECTABLE) */
+/**
+ * #TransSnap.target_select and #ToolSettings.snap_flag
+ * (#SCE_SNAP_NOT_TO_ACTIVE, #SCE_SNAP_TO_INCLUDE_EDITED, #SCE_SNAP_TO_INCLUDE_NONEDITED,
+ * #SCE_SNAP_TO_ONLY_SELECTABLE).
+ */
 typedef enum eSnapTargetSelect {
   SCE_SNAP_TARGET_ALL = 0,
   SCE_SNAP_TARGET_NOT_SELECTED = (1 << 0),
@@ -2263,7 +2391,7 @@ typedef enum eVGroupSelect {
 #define SCE_KEYS_NO_SELONLY (1 << 4)
 #define SCE_READFILE_LIBLINK_NEED_SETSCENE_CHECK (1 << 5)
 
-/* return flag BKE_scene_base_iter_next functions */
+/* Return flag BKE_scene_base_iter_next functions. */
 /* #define F_ERROR          -1 */ /* UNUSED */
 #define F_START 0
 #define F_SCENE 1
@@ -2278,7 +2406,8 @@ typedef enum eVGroupSelect {
 /** #FFMpegCodecData.flags */
 enum {
 #ifdef DNA_DEPRECATED_ALLOW
-  FFMPEG_MULTIPLEX_AUDIO = (1 << 0), /* deprecated, you can choose none as audiocodec now */
+  /* DEPRECATED: you can choose none as audio-codec now. */
+  FFMPEG_MULTIPLEX_AUDIO = (1 << 0),
 #endif
   FFMPEG_AUTOSPLIT_OUTPUT = (1 << 1),
   FFMPEG_LOSSLESS_OUTPUT = (1 << 2),
@@ -2330,34 +2459,33 @@ typedef enum eSculptFlags {
   SCULPT_ONLY_DEFORM = (1 << 8),
   // SCULPT_SHOW_DIFFUSE = (1 << 9), /* deprecated */
 
-  /* If set, the mesh will be drawn with smooth-shading in
-   * dynamic-topology mode */
+  /** If set, the mesh will be drawn with smooth-shading in dynamic-topology mode. */
   SCULPT_DYNTOPO_SMOOTH_SHADING = (1 << 10),
 
-  /* If set, dynamic-topology brushes will subdivide short edges */
+  /** If set, dynamic-topology brushes will subdivide short edges. */
   SCULPT_DYNTOPO_SUBDIVIDE = (1 << 12),
-  /* If set, dynamic-topology brushes will collapse short edges */
+  /** If set, dynamic-topology brushes will collapse short edges. */
   SCULPT_DYNTOPO_COLLAPSE = (1 << 11),
 
-  /* If set, dynamic-topology detail size will be constant in object space */
+  /** If set, dynamic-topology detail size will be constant in object space. */
   SCULPT_DYNTOPO_DETAIL_CONSTANT = (1 << 13),
   SCULPT_DYNTOPO_DETAIL_BRUSH = (1 << 14),
   SCULPT_DYNTOPO_DETAIL_MANUAL = (1 << 16),
 
-  /* Don't display mask in viewport, but still use it for strokes. */
+  /** Don't display mask in viewport, but still use it for strokes. */
   SCULPT_HIDE_MASK = (1 << 15),
 
-  /* Don't display face sets in viewport. */
+  /** Don't display face sets in viewport. */
   SCULPT_HIDE_FACE_SETS = (1 << 17),
 } eSculptFlags;
 
-/* Sculpt.transform_mode */
+/** #Sculpt.transform_mode */
 typedef enum eSculptTransformMode {
   SCULPT_TRANSFORM_MODE_ALL_VERTICES = 0,
   SCULPT_TRANSFORM_MODE_RADIUS_ELASTIC = 1,
 } eSculptTrasnformMode;
 
-/** PaintModeSettings.mode */
+/** #PaintModeSettings.mode */
 typedef enum ePaintCanvasSource {
   /** Paint on the active node of the active material slot. */
   PAINT_CANVAS_SOURCE_MATERIAL = 0,
@@ -2384,7 +2512,7 @@ enum {
 // #define IMAGEPAINT_DRAW_TOOL         (1 << 1) /* deprecated */
 // #define IMAGEPAINT_DRAW_TOOL_DRAWING (1 << 2) /* deprecated */
 
-/* projection painting only */
+/* Projection painting only. */
 /** #ImagePaintSettings.flag */
 #define IMAGEPAINT_PROJECT_XRAY (1 << 4)
 #define IMAGEPAINT_PROJECT_BACKFACE (1 << 5)
@@ -2401,13 +2529,13 @@ enum {
 
 /** #ToolSettings.uvcalc_flag */
 #define UVCALC_FILLHOLES (1 << 0)
-/** would call this UVCALC_ASPECT_CORRECT, except it should be default with old file */
+/** Would call this UVCALC_ASPECT_CORRECT, except it should be default with old file. */
 #define UVCALC_NO_ASPECT_CORRECT (1 << 1)
 /** Adjust UV's while transforming with Vert or Edge Slide. */
 #define UVCALC_TRANSFORM_CORRECT_SLIDE (1 << 2)
 /** Use mesh data after subsurf to compute UV's. */
 #define UVCALC_USESUBSURF (1 << 3)
-/** adjust UV's while transforming to avoid distortion */
+/** Adjust UV's while transforming to avoid distortion */
 #define UVCALC_TRANSFORM_CORRECT (1 << 4)
 /** Keep equal values merged while correcting custom-data. */
 #define UVCALC_TRANSFORM_CORRECT_KEEP_CONNECTED (1 << 5)
@@ -2431,49 +2559,49 @@ enum {
 
 /** #ToolSettings.gpencil_flags */
 typedef enum eGPencil_Flags {
-  /* When creating new frames, the last frame gets used as the basis for the new one */
+  /** When creating new frames, the last frame gets used as the basis for the new one. */
   GP_TOOL_FLAG_RETAIN_LAST = (1 << 1),
-  /* Add the strokes below all strokes in the layer */
+  /** Add the strokes below all strokes in the layer. */
   GP_TOOL_FLAG_PAINT_ONBACK = (1 << 2),
-  /* Show compact list of colors */
+  /** Show compact list of colors. */
   GP_TOOL_FLAG_THUMBNAIL_LIST = (1 << 3),
-  /* Generate wheight data for new strokes */
+  /** Generate wheight data for new strokes. */
   GP_TOOL_FLAG_CREATE_WEIGHTS = (1 << 4),
-  /* Automerge with last stroke */
+  /** Auto-merge with last stroke. */
   GP_TOOL_FLAG_AUTOMERGE_STROKE = (1 << 5),
 } eGPencil_Flags;
 
 /** #Scene.r.simplify_gpencil */
 typedef enum eGPencil_SimplifyFlags {
-  /* Simplify */
+  /** Simplify. */
   SIMPLIFY_GPENCIL_ENABLE = (1 << 0),
-  /* Simplify on play */
+  /** Simplify on play. */
   SIMPLIFY_GPENCIL_ON_PLAY = (1 << 1),
-  /* Simplify fill on viewport */
+  /** Simplify fill on viewport. */
   SIMPLIFY_GPENCIL_FILL = (1 << 2),
-  /* Simplify modifier on viewport */
+  /** Simplify modifier on viewport. */
   SIMPLIFY_GPENCIL_MODIFIER = (1 << 3),
-  /* Simplify Shader FX */
+  /** Simplify Shader FX. */
   SIMPLIFY_GPENCIL_FX = (1 << 5),
-  /* Simplify layer tint */
+  /** Simplify layer tint. */
   SIMPLIFY_GPENCIL_TINT = (1 << 7),
-  /* Simplify Antialiasing */
+  /** Simplify Anti-aliasing. */
   SIMPLIFY_GPENCIL_AA = (1 << 8),
 } eGPencil_SimplifyFlags;
 
-/** `ToolSettings.gpencil_*_align` - Stroke Placement mode flags */
+/** `ToolSettings.gpencil_*_align` - Stroke Placement mode flags. */
 typedef enum eGPencil_Placement_Flags {
-  /* New strokes are added in viewport/data space (i.e. not screen space) */
+  /** New strokes are added in viewport/data space (i.e. not screen space). */
   GP_PROJECT_VIEWSPACE = (1 << 0),
 
-  /* Viewport space, but relative to render canvas (Sequencer Preview Only) */
-  /* GP_PROJECT_CANVAS = (1 << 1), */ /* UNUSED */
+  // /** Viewport space, but relative to render canvas (Sequencer Preview Only) */
+  // GP_PROJECT_CANVAS = (1 << 1), /* UNUSED */
 
-  /* Project into the screen's Z values */
+  /** Project into the screen's Z values. */
   GP_PROJECT_DEPTH_VIEW = (1 << 2),
   GP_PROJECT_DEPTH_STROKE = (1 << 3),
 
-  /* "Use Endpoints" */
+  /** "Use Endpoints". */
   GP_PROJECT_DEPTH_STROKE_ENDPOINTS = (1 << 4),
   GP_PROJECT_CURSOR = (1 << 5),
   GP_PROJECT_DEPTH_STROKE_FIRST = (1 << 6),
@@ -2597,6 +2725,8 @@ enum {
   SCE_DISPLAY_AA_SAMPLES_32 = 32,
 };
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif