Cleanup: spelling in comments, use doxygen syntax

intern/cycles/scene/light_tree.h

@@ -160,7 +160,7 @@ struct LightTreeNode {
   int num_prims = -1;                    /* The number of primitives a leaf node stores. A negative
                                             number indicates it is an inner node. */
   int first_prim_index;                  /* Leaf nodes contain an index to first primitive. */
-  unique_ptr<LightTreeNode> children[2]; /* Inner node has two chlidren. */
+  unique_ptr<LightTreeNode> children[2]; /* Inner node has two children. */
 
   LightTreeNode() = default;
 

source/blender/blenkernel/BKE_DerivedMesh.h

@@ -8,34 +8,34 @@
  *
  * Basic design of the DerivedMesh system:
  *
- * DerivedMesh is a common set of interfaces for mesh systems.
+ * #DerivedMesh is a common set of interfaces for mesh systems.
  *
  * There are three main mesh data structures in Blender:
  * #Mesh, #CDDerivedMesh and #BMesh.
  *
- * These, and a few others, all implement DerivedMesh interfaces,
+ * These, and a few others, all implement #DerivedMesh interfaces,
  * which contains unified drawing interfaces, a few utility interfaces,
  * and a bunch of read-only interfaces intended mostly for conversion from
  * one format to another.
  *
- * All Mesh structures in blender make use of CustomData, which is used to store
+ * All Mesh structures in blender make use of #CustomData, which is used to store
- * per-element attributes and interpolate them (e.g. uvs, vcols, vgroups, etc).
+ * per-element attributes and interpolate them (e.g. UVs, vertex-colors, vertex-groups, etc).
  *
  * Mesh is the "serialized" structure, used for storing object-mode mesh data
- * and also for saving stuff to disk.  Its interfaces are also what DerivedMesh
+ * and also for saving stuff to disk. Its interfaces are also what #DerivedMesh
  * uses to communicate with.
  *
- * CDDM is a little mesh library, that uses Mesh data structures in the backend.
+ * #CDDM is a little mesh library, that uses Mesh data structures in the backend.
  * It's mostly used for modifiers, and has the advantages of not taking much
  * resources.
  *
- * BMesh is a full-on BREP, used for edit-mode, some modifiers, etc.  It's much
+ * #BMesh is a full-on BREP, used for edit-mode, some modifiers, etc.
- * more capable (if memory-intensive) then CDDM.
+ * It's much more capable (if memory-intensive) then CDDM.
  *
- * DerivedMesh is somewhat hackish.  Many places assumes that a DerivedMesh is
+ * #DerivedMesh is somewhat hackish. Many places assumes that a #DerivedMesh is
  * a CDDM (most of the time by simply copying it and converting it to one).
  * CDDM is the original structure for modifiers, but has since been superseded
- * by BMesh, at least for the foreseeable future.
+ * by #BMesh, at least for the foreseeable future.
  */
 
 /*

source/blender/blenkernel/intern/image_gpu.cc

@@ -342,7 +342,7 @@ void BKE_image_ensure_gpu_texture(Image *image, ImageUser *image_user)
     return;
   }
 
-  /* Note that the image can cache both sterio views, so we only invalidate the cache if the view
+  /* Note that the image can cache both stereo views, so we only invalidate the cache if the view
    * index is more than 2. */
   if (image->gpu_pass != image_user->pass || image->gpu_layer != image_user->layer ||
       (image->gpu_view != image_user->multi_index && image_user->multi_index >= 2)) {

source/blender/blenkernel/intern/softbody.c

@@ -3598,9 +3598,9 @@ void sbObjectStep(struct Depsgraph *depsgraph,
     /* pass */
   }
   else if (/*ob->id.lib || */
-           /* "library linking & pointcaches" has to be solved properly at some point */
+           /* "library linking & point-caches" has to be solved properly at some point. */
            (cache->flag & PTCACHE_BAKED)) {
-    /* if baked and nothing in cache, do nothing */
+    /* If baked and nothing in cache, do nothing. */
     if (can_write_cache) {
       BKE_ptcache_invalidate(cache);
     }

source/blender/blenkernel/intern/subsurf_ccg.cc

@@ -312,7 +312,7 @@ static int ss_sync_from_uv(CCGSubSurf *ss,
     int nverts = poly.totloop;
     int j, j_next;
     CCGFace *origf = ccgSubSurf_getFace(origss, POINTER_FROM_INT(i));
-    /* uint *fv = &poly.v1; */
+    // uint *fv = &poly.v1;
 
     fverts.reinitialize(nverts);
 

source/blender/blenloader/intern/versioning_250.c

@@ -774,7 +774,7 @@ void blo_do_versions_250(FileData *fd, Library *lib, Main *bmain)
       part->clength = 1.0f;
     }
 
-    /* set old pointcaches to have disk cache flag */
+    /* Set old point-caches to have disk cache flag. */
     for (ob = bmain->objects.first; ob; ob = ob->id.next) {
 
 #if 0

source/blender/draw/engines/eevee/shaders/infos/eevee_legacy_material_info.hh

@@ -31,7 +31,10 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_empty_base_volume)
 
 /**** MATERIAL VERTEX SHADER PERMUTATIONS ****/
 
-/** -- Volumetric -- **/
+/* -------------------------------------------------------------------- */
+/** \name Volumetric
+ * \{ */
+
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_volumetric_vert)
     .additional_info("eevee_legacy_material_empty_base_volume")
     .vertex_out(legacy_volume_vert_geom_iface)
@@ -45,7 +48,12 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_volumetric_vert_no_geom)
     .additional_info("draw_resource_id_varying");
 #endif
 
-/** -- World Shader -- **/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name World Shader
+ * \{ */
+
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_world_vert)
     .additional_info("eevee_legacy_material_empty_base")
     .additional_info("eevee_legacy_common_utiltex_lib")
@@ -54,7 +62,12 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_world_vert)
     .additional_info("draw_resource_id_varying")
     .vertex_in(0, Type::VEC2, "pos");
 
-/** -- Surface Shader -- **/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Surface Shader
+ * \{ */
+
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_surface_vert_common)
     .additional_info("eevee_legacy_material_empty_base")
     .additional_info("draw_resource_id_varying")
@@ -81,7 +94,13 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_mateiral_surface_vert_pointcloud)
     .auto_resource_location(true);
 
 /**** MATERIAL GEOMETRY SHADER PERMUTATIONS ****/
-/** -- Volumetric -- **/
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Volumetric
+ * \{ */
+
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_volumetric_geom)
     .additional_info("eevee_legacy_common_lib")
     .additional_info("draw_view")
@@ -89,9 +108,14 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_volumetric_geom)
     .geometry_layout(PrimitiveIn::TRIANGLES, PrimitiveOut::TRIANGLE_STRIP, 3)
     .additional_info("draw_resource_id_varying");
 
+/** \} */
+
 /**** MATERIAL FRAGMENT SHADER PERMUTATIONS ****/
 
-/** -- Volumetric Shader -- **/
+/* -------------------------------------------------------------------- */
+/** \name Volumetric Shader
+ * \{ */
+
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_volumetric_frag)
     .additional_info("eevee_legacy_common_lib")
     .additional_info("draw_view")
@@ -102,7 +126,11 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_volumetric_frag)
     .fragment_out(2, Type::VEC4, "volumeEmissive")
     .fragment_out(3, Type::VEC4, "volumePhase");
 
-/** -- Prepass Shader -- **/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Pre-pass Shader
+ * \{ */
 
 /* Common info for all `prepass_frag` variants. */
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_prepass_frag_common)
@@ -148,7 +176,11 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_prepass_frag_alpha_hash_pointcloud)
     .additional_info("eevee_legacy_material_prepass_frag_alpha_hash_common")
     .additional_info("draw_pointcloud");
 
-/** -- Surface Shader -- **/
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Surface Shader
+ * \{ */
 
 GPU_SHADER_CREATE_INFO(eevee_legacy_material_surface_frag_common)
     .additional_info("eevee_legacy_common_lib")
@@ -173,6 +205,8 @@ GPU_SHADER_CREATE_INFO(eevee_legacy_material_surface_frag_alpha_blend)
     .fragment_out(0, Type::VEC4, "outRadiance", DualBlend::SRC_0)
     .fragment_out(0, Type::VEC4, "outTransmittance", DualBlend::SRC_1);
 
+/** \} */
+
 /* hair_refine_shader_transform_feedback_create */
 
 GPU_SHADER_INTERFACE_INFO(legacy_hair_refine_shader_transform_feedback_iface, "")

source/blender/draw/engines/eevee_next/eevee_defines.hh

@@ -110,7 +110,7 @@
 #define GBUF_COLOR_SLOT RBUFS_DIFF_COLOR_SLOT
 
 /* Uniform Buffers. */
-/* Only during prepass. */
+/* Only during pre-pass. */
 #define VELOCITY_CAMERA_PREV_BUF 3
 #define VELOCITY_CAMERA_CURR_BUF 4
 #define VELOCITY_CAMERA_NEXT_BUF 5

source/blender/draw/engines/eevee_next/shaders/infos/eevee_velocity_info.hh

@@ -6,7 +6,7 @@
 /* -------------------------------------------------------------------- */
 /** \name Surface Velocity
  *
- * Combined with the depth prepass shader.
+ * Combined with the depth pre-pass shader.
  * Outputs the view motion vectors for animated objects.
  * \{ */
 

source/blender/draw/engines/overlay/overlay_shader.cc

@@ -1165,7 +1165,7 @@ OVERLAY_InstanceFormats *OVERLAY_shader_instance_formats_get(void)
                               {
                                   {"boneStart", DRW_ATTR_FLOAT, 3},
                                   {"boneEnd", DRW_ATTR_FLOAT, 3},
-                                  {"wireColor", DRW_ATTR_FLOAT, 4}, /* TODO: uchar color. */
+                                  {"wireColor", DRW_ATTR_FLOAT, 4}, /* TODO: `uchar` color. */
                                   {"boneColor", DRW_ATTR_FLOAT, 4},
                                   {"headColor", DRW_ATTR_FLOAT, 4},
                                   {"tailColor", DRW_ATTR_FLOAT, 4},

source/blender/editors/include/ED_gpencil.h

@@ -213,7 +213,7 @@ void ED_gpencil_strokes_copybuf_free(void);
 /* drawgpencil.c */
 
 /**
- * Draw grease-pencil sketches to specified 2d-view that uses ibuf corrections.
+ * Draw grease-pencil sketches to specified 2d-view that uses `ibuf` corrections.
  */
 void ED_annotation_draw_2dimage(const struct bContext *C);
 /**

source/blender/editors/space_action/action_draw.cc

@@ -689,7 +689,7 @@ void timeline_draw_cache(SpaceAction *saction, Object *ob, Scene *scene)
 
   GPU_blend(GPU_BLEND_ALPHA);
 
-  /* Iterate over pointcaches on the active object, and draw each one's range. */
+  /* Iterate over point-caches on the active object, and draw each one's range. */
   float y_offset = 0.0f;
   const float cache_draw_height = 4.0f * UI_SCALE_FAC * U.pixelsize;
   LISTBASE_FOREACH (PTCacheID *, pid, &pidlist) {

source/blender/editors/space_action/action_edit.cc

@@ -115,8 +115,8 @@ static int act_markers_make_local_exec(bContext *C, wmOperator * /*op*/)
     }
   }
 
-  /* Now enable the "show posemarkers only" setting,
+  /* Now enable the "show pose-markers only" setting,
-   * so that we can see that something did happen */
+   * so that we can see that something did happen. */
   sact->flag |= SACTION_POSEMARKERS_SHOW;
 
   /* notifiers - both sets, as this change affects both */
@@ -376,7 +376,7 @@ static int actkeys_viewall(bContext *C, const bool only_sel)
   }
 
   if (fabsf(max - min) < 1.0f) {
-    /* Exception - center the single keyfrme */
+    /* Exception - center the single keyframe. */
     float xwidth = BLI_rctf_size_x(&v2d->cur);
 
     v2d->cur.xmin = min - xwidth / 2.0f;

source/blender/geometry/GEO_uv_pack.hh

@@ -18,15 +18,21 @@
 struct UnwrapOptions;
 
 enum eUVPackIsland_MarginMethod {
-  ED_UVPACK_MARGIN_SCALED = 0, /* Use scale of existing UVs to multiply margin. */
+  /** Use scale of existing UVs to multiply margin. */
-  ED_UVPACK_MARGIN_ADD,        /* Just add the margin, ignoring any UV scale. */
+  ED_UVPACK_MARGIN_SCALED = 0,
-  ED_UVPACK_MARGIN_FRACTION,   /* Specify a precise fraction of final UV output. */
+  /** Just add the margin, ignoring any UV scale. */
+  ED_UVPACK_MARGIN_ADD,
+  /** Specify a precise fraction of final UV output. */
+  ED_UVPACK_MARGIN_FRACTION,
 };
 
 enum eUVPackIsland_ShapeMethod {
-  ED_UVPACK_SHAPE_AABB = 0, /* Use Axis-Aligned Bounding-Boxes. */
+  /** Use Axis-Aligned Bounding-Boxes. */
-  ED_UVPACK_SHAPE_CONVEX,   /* Use convex hull. */
+  ED_UVPACK_SHAPE_AABB = 0,
-  ED_UVPACK_SHAPE_CONCAVE,  /* Use concave hull. */
+  /** Use convex hull. */
+  ED_UVPACK_SHAPE_CONVEX,
+  /** Use concave hull. */
+  ED_UVPACK_SHAPE_CONCAVE,
 };
 
 namespace blender::geometry {
@@ -67,8 +73,10 @@ class UVPackIsland_Params {
 class PackIsland {
  public:
   rctf bounds_rect;
-  float2 pre_translate; /* Output. */
+  /** Output. */
-  int caller_index;     /* Unchanged by #pack_islands, used by caller. */
+  float2 pre_translate;
+  /** Unchanged by #pack_islands, used by caller. */
+  int caller_index;
 
   void add_triangle(const float2 uv0, const float2 uv1, const float2 uv2);
   void add_polygon(const blender::Span<float2> uvs, MemArena *arena, Heap *heap);

source/blender/geometry/intern/uv_pack.cc

@@ -24,22 +24,22 @@
 
 namespace blender::geometry {
 
-/** Compute `r = mat * (a + b)` with high precision.
- *
- * Often, linear transforms are written as :
- *  `A.x + b`
- *
- * When transforming UVs, the familiar expression can
- * damage UVs due to round-off error, expecially when
- * using UDIM and if there are large numbers of islands.
- *
- * Instead, we provide a helper which evaluates :
- *  `A. (x + b)`
- *
- * To further reduce damage, all internal calculations are
- * performed using double precision. */
 void mul_v2_m2_add_v2v2(float r[2], const float mat[2][2], const float a[2], const float b[2])
 {
+  /* Compute `r = mat * (a + b)` with high precision.
+   *
+   * Often, linear transforms are written as:
+   *  `A.x + b`
+   *
+   * When transforming UVs, the familiar expression can damage UVs due to round-off error,
+   * especially when using UDIM and if there are large numbers of islands.
+   *
+   * Instead, we provide a helper which evaluates:
+   *  `A. (x + b)`
+   *
+   * To further reduce damage, all internal calculations are
+   * performed using double precision. */
+
   const double x = double(a[0]) + double(b[0]);
   const double y = double(a[1]) + double(b[1]);
 
@@ -47,7 +47,8 @@ void mul_v2_m2_add_v2v2(float r[2], const float mat[2][2], const float a[2], con
   r[1] = float(mat[0][1] * x + mat[1][1] * y);
 }
 
-/* Compute signed distance squared to a line passing through `uva` and `uvb`.
+/**
+ * Compute signed distance squared to a line passing through `uva` and `uvb`.
  */
 static float dist_signed_squared_to_edge(float2 probe, float2 uva, float2 uvb)
 {
@@ -459,12 +460,12 @@ static float guess_initial_scale(const Span<PackIsland *> islands,
 }
 
 /**
- * Pack irregular islands using the "xatlas" strategy, with no rotation.
+ * Pack irregular islands using the `xatlas` strategy, with no rotation.
  *
  * Loosely based on the 'xatlas' code by Jonathan Young
  * from https://github.com/jpcy/xatlas
  *
- * A brute force packer (BFPacker) with accelerators:
+ * A brute force packer (BF-Packer) with accelerators:
  * - Uses a Bitmap Occupancy class.
  * - Uses a "Witness Pixel" and a "Triangle Hint".
  * - Write with `margin * 2`, read with `margin == 0`.
@@ -489,9 +490,9 @@ static void pack_island_xatlas(const Span<UVAABBIsland *> island_indices,
   int i = 0;
 
   /* The following `while` loop is setting up a three-way race:
-   * for (scan_line=0; scan_line<bitmap_radix; scan_line++)
+   * `for (scan_line = 0; scan_line < bitmap_radix; scan_line++)`
-   * for (i : island_indices.index_range())
+   * `for (i : island_indices.index_range())`
-   * while (bitmap_scale_reciprocal > 0) { bitmap_scale_reciprocal *= 0.5f; }
+   * `while (bitmap_scale_reciprocal > 0) { bitmap_scale_reciprocal *= 0.5f; }`
    */
 
   while (i < island_indices.size()) {
@@ -507,10 +508,9 @@ static void pack_island_xatlas(const Span<UVAABBIsland *> island_indices,
       else {
         /* Increasing by 2 here has the effect of changing the sampling pattern.
          * The parameter '2' is not "free" in the sense that changing it requires
-         * a change to `bitmap_radix` and then retuning `alpaca_cutoff`.
+         * a change to `bitmap_radix` and then returning `alpaca_cutoff`.
          * Possible values here *could* be 1, 2 or 3, however the only *reasonable*
-         * choice is 2.
+         * choice is 2. */
-         */
         scan_line += 2;
       }
       if (scan_line < occupancy.bitmap_radix) {
@@ -592,10 +592,8 @@ static float pack_islands_scale_margin(const Span<PackIsland *> islands,
 
   /* Partition `islands`, largest will go to a slow packer, the rest alpaca_turbo.
    * See discussion above for details. */
-  int64_t alpaca_cutoff = int64_t(
+  int64_t alpaca_cutoff = 1024;    /* Regular situation, pack 1024 islands with slow packer. */
-      1024); /* Regular situation, pack 1024 islands with slow packer. */
+  int64_t alpaca_cutoff_fast = 80; /* Reduced problem size, only 80 islands with slow packer. */
-  int64_t alpaca_cutoff_fast = int64_t(
-      80); /* Reduced problem size, only 80 islands with slow packer. */
   if (params.margin_method == ED_UVPACK_MARGIN_FRACTION) {
     if (margin > 0.0f) {
       alpaca_cutoff = alpaca_cutoff_fast;

source/blender/gpu/intern/gpu_shader_create_info.hh

@@ -21,8 +21,8 @@
 
 namespace blender::gpu::shader {
 
-#ifndef GPU_SHADER_CREATE_INFO
 /* Helps intellisense / auto-completion. */
+#ifndef GPU_SHADER_CREATE_INFO
 #  define GPU_SHADER_INTERFACE_INFO(_interface, _inst_name) \
     StageInterfaceInfo _interface(#_interface, _inst_name); \
     _interface

source/blender/makesdna/DNA_customdata_types.h

@@ -41,7 +41,7 @@ typedef struct CustomDataLayer {
   int active_clone;
   /** Number of the layer to render. */
   int active_mask;
-  /** Shape keyblock unique id reference. */
+  /** Shape key-block unique id reference. */
   int uid;
   /** Layer name, MAX_CUSTOMDATA_LAYER_NAME. */
   char name[68];
@@ -84,7 +84,7 @@ typedef struct CustomData {
   int totsize;
   /** (BMesh Only): Memory pool for allocation of blocks. */
   struct BLI_mempool *pool;
-  /** External file storing customdata layers. */
+  /** External file storing custom-data layers. */
   CustomDataExternal *external;
 } CustomData;
 

source/blender/python/bmesh/bmesh_py_types_meshdata.c

@@ -710,7 +710,7 @@ static struct PyMethodDef bpy_bmdeformvert_methods[] = {
     {"values", (PyCFunction)bpy_bmdeformvert_values, METH_NOARGS, bpy_bmdeformvert_values_doc},
     {"items", (PyCFunction)bpy_bmdeformvert_items, METH_NOARGS, bpy_bmdeformvert_items_doc},
     {"get", (PyCFunction)bpy_bmdeformvert_get, METH_VARARGS, bpy_bmdeformvert_get_doc},
-    /* BMESH_TODO pop, popitem, update */
+    /* BMESH_TODO `pop`, `popitem`, `update`. */
     {"clear", (PyCFunction)bpy_bmdeformvert_clear, METH_NOARGS, bpy_bmdeformvert_clear_doc},
     {NULL, NULL, 0, NULL},
 };