Cleanup: move function comments into headers or implementation notes

For C/C++ doc-strings should be located in headers, move function comments into the headers, in some cases merging with existing doc-strings, in other cases, moving implementation notes into the function body.
2024-11-02 17:27:09 +11:00
parent c5222a3953
commit 4df285ccd5
75 changed files with 237 additions and 179 deletions
--- a/source/blender/animrig/intern/action.cc
+++ b/source/blender/animrig/intern/action.cc
@@ -400,12 +400,13 @@ static void slot_name_ensure_unique(Action &action, Slot &slot)
  BLI_uniquename_cb(check_name_is_used, &check_data, "", '.', slot.name, sizeof(slot.name));
 }

-/* TODO: maybe this function should only set the 'name without prefix' aka the 'display name'. That
- * way only `this->id_type` is responsible for the prefix. I (Sybren) think that's easier to
- * determine when the code is a bit more mature, and we can see what the majority of the calls to
- * this function actually do/need. */
 void Action::slot_name_set(Main &bmain, Slot &slot, const StringRefNull new_name)
 {
+  /* TODO: maybe this function should only set the 'name without prefix' aka the 'display name'.
+   * That way only `this->id_type` is responsible for the prefix. I (Sybren) think that's easier to
+   * determine when the code is a bit more mature, and we can see what the majority of the calls to
+   * this function actually do/need. */
+
  this->slot_name_define(slot, new_name);
  this->slot_name_propagate(bmain, slot);
 }
@@ -1441,9 +1442,10 @@ ActionSlotAssignmentResult assign_action_and_slot(Action *action,
  return assign_action_slot(slot_to_assign, animated_id);
 }

-/* TODO: rename to get_action(). */
 Action *get_action(ID &animated_id)
 {
+  /* TODO: rename to get_action(). */
+
  AnimData *adt = BKE_animdata_from_id(&animated_id);
  if (!adt) {
    return nullptr;
--- a/source/blender/animrig/intern/action_runtime.cc
+++ b/source/blender/animrig/intern/action_runtime.cc
@@ -25,9 +25,6 @@

 namespace blender::animrig::internal {

-/**
- * Rebuild the slot user cache for a specific bmain.
- */
 void rebuild_slot_user_cache(Main &bmain)
 {
  /* Loop over all Actions and clear their slots' user cache. */
--- a/source/blender/animrig/intern/action_runtime.hh
+++ b/source/blender/animrig/intern/action_runtime.hh
@@ -37,7 +37,7 @@ class SlotRuntime {
 namespace internal {

 /**
- * Rebuild the SlotRuntime::users cache of all Slots in all Actions.
+ * Rebuild the #SlotRuntime::users cache of all Slots in all Action for a specific `bmain`.
 *
 * The reason that all slot users are re-cached at once is two-fold:
 *
--- a/source/blender/asset_system/intern/asset_library_service.cc
+++ b/source/blender/asset_system/intern/asset_library_service.cc
@@ -347,13 +347,14 @@ std::string AssetLibraryService::normalize_asset_weak_reference_relative_asset_i
                                   group_name_sep_pos + 1);
 }

-/* TODO currently only works for asset libraries on disk (custom or essentials asset libraries).
- * Once there is a proper registry of asset libraries, this could contain an asset library locator
- * and/or identifier, so a full path (not necessarily file path) can be built for all asset
- * libraries. */
 std::string AssetLibraryService::resolve_asset_weak_reference_to_full_path(
    const AssetWeakReference &asset_reference)
 {
+  /* TODO currently only works for asset libraries on disk (custom or essentials asset libraries).
+   * Once there is a proper registry of asset libraries, this could contain an asset library
+   * locator and/or identifier, so a full path (not necessarily file path) can be built for all
+   * asset libraries. */
+
  if (asset_reference.relative_asset_identifier[0] == '\0') {
    return "";
  }
--- a/source/blender/blenkernel/BKE_gpencil_legacy.h
+++ b/source/blender/blenkernel/BKE_gpencil_legacy.h
@@ -68,7 +68,7 @@ bool BKE_gpencil_free_strokes(struct bGPDframe *gpf);
 void BKE_gpencil_free_frames(struct bGPDlayer *gpl);
 /** Free all of the gp-layers for a viewport (list should be `&gpd->layers` or so). */
 void BKE_gpencil_free_layers(struct ListBase *list);
-/** Free all of the palettes (list should be `&gpd->palettes` or so). */
+/** Free all of the palettes & colors (list should be `&gpd->palettes` or so). */
 void BKE_gpencil_free_legacy_palette_data(struct ListBase *list);
 /** Free (or release) any data used by this grease pencil (does not free the gpencil itself). */
 void BKE_gpencil_free_data(struct bGPdata *gpd, bool free_all);
--- a/source/blender/blenkernel/BKE_text.h
+++ b/source/blender/blenkernel/BKE_text.h
@@ -130,10 +130,17 @@ bool text_check_identifier_nodigit(char ch);
 bool text_check_whitespace(char ch);
 int text_find_identifier_start(const char *str, int i);

-/* EVIL: defined in `bpy_interface.cc`. */
+/* -------------------------------------------------------------------- */
+/** \name Character Classification
+ *
+ * Defined in `bpy_interface.cc` (not ideal).
+ * \{ */
+
 extern int text_check_identifier_unicode(unsigned int ch);
 extern int text_check_identifier_nodigit_unicode(unsigned int ch);

+/** \} */
+
 enum {
  TXT_MOVE_LINE_UP = -1,
  TXT_MOVE_LINE_DOWN = 1,
--- a/source/blender/blenkernel/intern/gpencil_legacy.cc
+++ b/source/blender/blenkernel/intern/gpencil_legacy.cc
@@ -448,7 +448,6 @@ void BKE_gpencil_free_layers(ListBase *list)
  }
 }

-/* Free all of the gp-palettes and colors. */
 void BKE_gpencil_free_legacy_palette_data(ListBase *list)
 {
  LISTBASE_FOREACH_MUTABLE (bGPDpalette *, palette, list) {
--- a/source/blender/blenkernel/intern/grease_pencil_vertex_groups.cc
+++ b/source/blender/blenkernel/intern/grease_pencil_vertex_groups.cc
@@ -134,7 +134,6 @@ void assign_to_vertex_group(GreasePencil &grease_pencil, const StringRef name, c
  }
 }

-/** Remove selected vertices from the vertex group. */
 bool remove_from_vertex_group(GreasePencil &grease_pencil,
                              const StringRef name,
                              const bool use_selection)
--- a/source/blender/blenkernel/intern/idprop.cc
+++ b/source/blender/blenkernel/intern/idprop.cc
@@ -410,10 +410,11 @@ static IDProperty *IDP_CopyString(const IDProperty *prop, const int flag)
  return newp;
 }

-/* FIXME: This function is broken for bytes (in case there are null chars in it), needs a
- * dedicated function which takes directly the size of the byte buffer. */
 void IDP_AssignStringMaxSize(IDProperty *prop, const char *st, const size_t st_maxncpy)
 {
+  /* FIXME: This function is broken for bytes (in case there are null chars in it),
+   * needs a dedicated function which takes directly the size of the byte buffer. */
+
  BLI_assert(prop->type == IDP_STRING);
  const bool is_byte = prop->subtype == IDP_STRING_SUB_BYTE;
  const int stlen = int((st_maxncpy > 0) ? BLI_strnlen(st, st_maxncpy - 1) : strlen(st)) +
@@ -427,9 +428,10 @@ void IDP_AssignStringMaxSize(IDProperty *prop, const char *st, const size_t st_m
  }
 }

-/* FIXME: Should never be called for `byte` subtype, needs an assert. */
 void IDP_AssignString(IDProperty *prop, const char *st)
 {
+  /* FIXME: Should never be called for `byte` subtype, needs an assert. */
+
  IDP_AssignStringMaxSize(prop, st, 0);
 }

--- a/source/blender/blenkernel/intern/image_partial_update.cc
+++ b/source/blender/blenkernel/intern/image_partial_update.cc
@@ -542,9 +542,10 @@ extern "C" {

 using namespace blender::bke::image::partial_update;

-/* TODO(@jbakker): cleanup parameter. */
 PartialUpdateUser *BKE_image_partial_update_create(const Image *image)
 {
+  /* TODO(@jbakker): cleanup parameter. */
+
  PartialUpdateUserImpl *user_impl = MEM_new<PartialUpdateUserImpl>(__func__);

 #ifdef NDEBUG
--- a/source/blender/blenkernel/intern/lib_id.cc
+++ b/source/blender/blenkernel/intern/lib_id.cc
@@ -477,9 +477,6 @@ void BKE_lib_id_expand_local(Main *bmain, ID *id, const int flags)
      bmain, id, lib_id_expand_local_cb, POINTER_FROM_INT(flags), IDWALK_READONLY);
 }

-/**
- * Ensure new (copied) ID is fully made local.
- */
 void lib_id_copy_ensure_local(Main *bmain, const ID *old_id, ID *new_id, const int flags)
 {
  if (ID_IS_LINKED(old_id)) {
--- a/source/blender/blenkernel/intern/lib_intern.hh
+++ b/source/blender/blenkernel/intern/lib_intern.hh
@@ -17,4 +17,7 @@ extern BKE_library_remap_editor_id_reference_cb remap_editor_id_reference_cb;
 struct ID;
 struct Main;

+/**
+ * Ensure new (copied) ID is fully made local.
+ */
 void lib_id_copy_ensure_local(Main *bmain, const ID *old_id, ID *new_id, const int flags);
--- a/source/blender/blenkernel/intern/lib_override.cc
+++ b/source/blender/blenkernel/intern/lib_override.cc
@@ -304,10 +304,10 @@ static ID *lib_override_library_create_from(Main *bmain,
  return local_id;
 }

-/* TODO: This could be simplified by storing a flag in #IDOverrideLibrary
- * during the diffing process? */
 bool BKE_lib_override_library_is_user_edited(const ID *id)
 {
+  /* TODO: This could be simplified by storing a flag in #IDOverrideLibrary
+   * during the diffing process? */

  if (!ID_IS_OVERRIDE_LIBRARY(id)) {
    return false;
@@ -511,8 +511,6 @@ static void lib_override_remapper_overrides_add(id::IDRemapper &id_remapper,
  }
 }

-/* TODO: Make this static local function instead? API is becoming complex, and it's not used
- * outside of this file anyway. */
 bool BKE_lib_override_library_create_from_tag(Main *bmain,
                                              Library *owner_library,
                                              const ID *id_root_reference,
@@ -521,6 +519,9 @@ bool BKE_lib_override_library_create_from_tag(Main *bmain,
                                              const bool do_no_main,
                                              const bool do_fully_editable)
 {
+  /* TODO: Make this static local function instead?
+   * API is becoming complex, and it's not used outside of this file anyway. */
+
  BLI_assert(id_root_reference != nullptr && ID_IS_LINKED(id_root_reference));
  /* If we do not have any hierarchy root given, then the root reference must be tagged for
   * override. */
--- a/source/blender/blenkernel/intern/object.cc
+++ b/source/blender/blenkernel/intern/object.cc
@@ -4254,12 +4254,13 @@ static int pc_cmp(const void *a, const void *b)
  return 0;
 }

-/* TODO: Review the usages of this function, currently with copy-on-eval it will be called for orig
- * object and then again for evaluated copies of it, think this is bad since there is no guarantee
- * that we get the same stack index in both cases? Order is important since this index is used for
- * filenames on disk. */
 int BKE_object_insert_ptcache(Object *ob)
 {
+  /* TODO: Review the usages of this function, currently with copy-on-eval it will be called for
+   * orig object and then again for evaluated copies of it, think this is bad since there is no
+   * guarantee that we get the same stack index in both cases? Order is important since this index
+   * is used for filenames on disk. */
+
  LinkData *link = nullptr;
  int i = 0;

--- a/source/blender/blenkernel/intern/tracking_auto.cc
+++ b/source/blender/blenkernel/intern/tracking_auto.cc
@@ -819,10 +819,11 @@ void BKE_autotrack_context_sync(AutoTrackContext *context)
  }
 }

-/* TODO(sergey): Find a way to avoid this, somehow making all needed logic in
- * #BKE_autotrack_context_sync(). */
 void BKE_autotrack_context_sync_user(AutoTrackContext *context, MovieClipUser *user)
 {
+  /* TODO(sergey): Find a way to avoid this function,
+   * somehow making all needed logic in #BKE_autotrack_context_sync(). */
+
  user->framenr = context->synchronized_scene_frame;
 }

--- a/source/blender/blenlib/BLI_mesh_boolean.hh
+++ b/source/blender/blenlib/BLI_mesh_boolean.hh
@@ -56,6 +56,11 @@ IMesh boolean_mesh(IMesh &imesh,
 * This is like boolean, but operates on #IMesh's whose faces are all triangles.
 * It is exposed mainly for unit testing, at the moment: boolean_mesh() uses
 * it to do most of its work.
+ *
+ * This function does a boolean operation on a #TriMesh with `nshapes` inputs.
+ * All the shapes are combined in `tm_in`.
+ * The shape_fn function should take a triangle index in `tm_in` and return
+ * a number in the range 0 to `nshapes - 1`, to say which shape that triangle is in.
 */
 IMesh boolean_trimesh(IMesh &tm_in,
                      BoolOpType op,
--- a/source/blender/blenlib/intern/mesh_boolean.cc
+++ b/source/blender/blenlib/intern/mesh_boolean.cc
@@ -3529,12 +3529,6 @@ static IMesh polymesh_from_trimesh_with_dissolve(const IMesh &tm_out,
  return imesh_out;
 }

-/**
- * This function does a boolean operation on a TriMesh with nshapes inputs.
- * All the shapes are combined in tm_in.
- * The shape_fn function should take a triangle index in tm_in and return
- * a number in the range 0 to `nshapes-1`, to say which shape that triangle is in.
- */
 IMesh boolean_trimesh(IMesh &tm_in,
                      BoolOpType op,
                      int nshapes,
--- a/source/blender/compositor/intern/COM_Converter.cc
+++ b/source/blender/compositor/intern/COM_Converter.cc
@@ -427,9 +427,10 @@ Node *COM_convert_bnode(bNode *b_node)
  return node;
 }

-/* TODO(jbakker): make this an std::optional<NodeOperation>. */
 NodeOperation *COM_convert_data_type(const NodeOperationOutput &from, const NodeOperationInput &to)
 {
+  /* TODO(jbakker): make the return value an #std::optional<NodeOperation>. */
+
  const DataType src_data_type = from.get_data_type();
  const DataType dst_data_type = to.get_data_type();

--- a/source/blender/compositor/operations/COM_BokehImageOperation.cc
+++ b/source/blender/compositor/operations/COM_BokehImageOperation.cc
@@ -42,18 +42,12 @@ void BokehImageOperation::init_execution()
  lens_shift_ = data_->lensshift;
 }

-/* Get the 2D vertex position of the vertex with the given index in the regular polygon
- * representing this bokeh. The polygon is rotated by the rotation amount and have a unit
- * circumradius. The regular polygon is one whose vertices' exterior angles are given by
- * exterior_angle. See the bokeh function for more information. */
 float2 BokehImageOperation::get_regular_polygon_vertex_position(int vertex_index)
 {
  float angle = exterior_angle_ * vertex_index - rotation_;
  return float2(math::cos(angle), math::sin(angle));
 }

-/* Find the closest point to the given point on the given line. This assumes the length of the
- * given line is not zero. */
 float2 BokehImageOperation::closest_point_on_line(float2 point, float2 line_start, float2 line_end)
 {
  float2 line_vector = line_end - line_start;
@@ -63,20 +57,6 @@ float2 BokehImageOperation::closest_point_on_line(float2 point, float2 line_star
  return line_start + line_vector * parameter;
 }

-/* Compute the value of the bokeh at the given point. The computed bokeh is essentially a regular
- * polygon centered in space having the given circumradius. The regular polygon is one whose
- * vertices' exterior angles are given by "exterior_angle", which relates to the number of vertices
- * n through the equation "exterior angle = 2 pi / n". The regular polygon may additionally morph
- * into a shape with the given properties:
- *
- * - The regular polygon may have a circular hole in its center whose radius is controlled by the
- *   "catadioptric" value.
- * - The regular polygon is rotated by the "rotation" value.
- * - The regular polygon can morph into a circle controlled by the "roundness" value, such that it
- *   becomes a full circle at unit roundness.
- *
- * The function returns 0 when the point lies inside the regular polygon and 1 otherwise. However,
- * at the edges, it returns a narrow band gradient as a form of anti-aliasing. */
 float BokehImageOperation::bokeh(float2 point, float circumradius)
 {
  /* Get the index of the vertex of the regular polygon whose polar angle is maximum but less than
--- a/source/blender/compositor/operations/COM_BokehImageOperation.h
+++ b/source/blender/compositor/operations/COM_BokehImageOperation.h
@@ -25,8 +25,34 @@ class BokehImageOperation : public MultiThreadedOperation {
  /* See the delete_data_on_finish method. */
  bool delete_data_;

+  /**
+   * Get the 2D vertex position of the vertex with the given index in the regular polygon
+   * representing this bokeh. The polygon is rotated by the rotation amount and have a unit
+   * circumradius. The regular polygon is one whose vertices' exterior angles are given by
+   * exterior_angle. See the bokeh function for more information.
+   */
  float2 get_regular_polygon_vertex_position(int vertex_index);
+  /**
+   * Find the closest point to the given point on the given line. This assumes the length of the
+   * given line is not zero.
+   */
  float2 closest_point_on_line(float2 point, float2 line_start, float2 line_end);
+  /**
+   * Compute the value of the bokeh at the given point. The computed bokeh is essentially a regular
+   * polygon centered in space having the given circumradius. The regular polygon is one whose
+   * vertices' exterior angles are given by "exterior_angle", which relates to the number of
+   * vertices n through the equation "exterior angle = 2 pi / n". The regular polygon may
+   * additionally morph into a shape with the given properties:
+   *
+   * - The regular polygon may have a circular hole in its center whose radius is controlled by the
+   *   "catadioptric" value.
+   * - The regular polygon is rotated by the "rotation" value.
+   * - The regular polygon can morph into a circle controlled by the "roundness" value,
+   *   such that it becomes a full circle at unit roundness.
+   *
+   * The function returns 0 when the point lies inside the regular polygon and 1 otherwise.
+   * However, at the edges, it returns a narrow band gradient as a form of anti-aliasing.
+   */
  float bokeh(float2 point, float circumradius);

 public:
--- a/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
@@ -1456,7 +1456,6 @@ void DepsgraphNodeBuilder::build_dimensions(Object *object)
  add_operation_node(&object->id, NodeType::PARAMETERS, OperationCode::DIMENSIONS);
 }

-/* Recursively build graph for world */
 void DepsgraphNodeBuilder::build_world(World *world)
 {
  if (built_map_.checkIsBuiltAndTag(world)) {
@@ -1662,7 +1661,6 @@ void DepsgraphNodeBuilder::build_particle_settings(ParticleSettings *particle_se
  }
 }

-/* Shape-keys. */
 void DepsgraphNodeBuilder::build_shapekeys(Key *key)
 {
  if (built_map_.checkIsBuiltAndTag(key)) {
@@ -2027,7 +2025,6 @@ void DepsgraphNodeBuilder::build_nodetree(bNodeTree *ntree)
  /* TODO: link from nodetree to owner_component? */
 }

-/* Recursively build graph for material */
 void DepsgraphNodeBuilder::build_material(Material *material)
 {
  if (built_map_.checkIsBuiltAndTag(material)) {
@@ -2060,7 +2057,6 @@ void DepsgraphNodeBuilder::build_materials(Material **materials, int num_materia
  }
 }

-/* Recursively build graph for texture */
 void DepsgraphNodeBuilder::build_texture(Tex *texture)
 {
  if (built_map_.checkIsBuiltAndTag(texture)) {
--- a/source/blender/depsgraph/intern/builder/deg_builder_nodes.h
+++ b/source/blender/depsgraph/intern/builder/deg_builder_nodes.h
@@ -245,23 +245,30 @@ class DepsgraphNodeBuilder : public DepsgraphBuilder {

  virtual void build_parameters(ID *id);
  virtual void build_dimensions(Object *object);
+  /** IK Solver Eval Steps. */
  virtual void build_ik_pose(Object *object, bPoseChannel *pchan, bConstraint *con);
+  /** Spline IK Eval Steps. */
  virtual void build_splineik_pose(Object *object, bPoseChannel *pchan, bConstraint *con);
+  /** Pose/Armature Bones Graph. */
  virtual void build_rig(Object *object);
  virtual void build_armature(bArmature *armature);
  virtual void build_armature_bones(ListBase *bones);
  virtual void build_armature_bone_collections(blender::Span<BoneCollection *> collections);
+  /** Shape-keys. */
  virtual void build_shapekeys(Key *key);
  virtual void build_camera(Camera *camera);
  virtual void build_light(Light *lamp);
  virtual void build_nodetree(bNodeTree *ntree);
  virtual void build_nodetree_socket(bNodeSocket *socket);
+  /** Recursively build graph for material. */
  virtual void build_material(Material *ma);
  virtual void build_materials(Material **materials, int num_materials);
  virtual void build_freestyle_lineset(FreestyleLineSet *fls);
  virtual void build_freestyle_linestyle(FreestyleLineStyle *linestyle);
+  /** Recursively build graph for texture. */
  virtual void build_texture(Tex *tex);
  virtual void build_image(Image *image);
+  /** Recursively build graph for world. */
  virtual void build_world(World *world);
  virtual void build_cachefile(CacheFile *cache_file);
  virtual void build_mask(Mask *mask);
--- a/source/blender/depsgraph/intern/builder/deg_builder_nodes_rig.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_nodes_rig.cc
@@ -64,7 +64,6 @@ void DepsgraphNodeBuilder::build_pose_constraints(Object *object,
                     });
 }

-/* IK Solver Eval Steps */
 void DepsgraphNodeBuilder::build_ik_pose(Object *object, bPoseChannel *pchan, bConstraint *con)
 {
  bKinematicConstraint *data = (bKinematicConstraint *)con->data;
@@ -96,7 +95,6 @@ void DepsgraphNodeBuilder::build_ik_pose(Object *object, bPoseChannel *pchan, bC
                     });
 }

-/* Spline IK Eval Steps */
 void DepsgraphNodeBuilder::build_splineik_pose(Object *object,
                                               bPoseChannel *pchan,
                                               bConstraint *con)
--- a/source/blender/depsgraph/intern/depsgraph_light_linking.cc
+++ b/source/blender/depsgraph/intern/depsgraph_light_linking.cc
@@ -446,7 +446,6 @@ void Cache::end_build(const Scene &scene)
  shadow_linking_.end_build(scene, shadow_emitter_data_map_);
 }

-/* Set runtime data in light linking. */
 void Cache::eval_runtime_data(Object &object_eval) const
 {
  static const LightLinkingRuntime runtime_no_links = {
--- a/source/blender/depsgraph/intern/eval/deg_eval_copy_on_write.cc
+++ b/source/blender/depsgraph/intern/eval/deg_eval_copy_on_write.cc
@@ -898,11 +898,10 @@ ID *deg_update_eval_copy_datablock(const Depsgraph *depsgraph, const IDNode *id_
  return id_cow;
 }

-/**
- * \note Depsgraph is supposed to have ID node already.
- */
 ID *deg_update_eval_copy_datablock(const Depsgraph *depsgraph, ID *id_orig)
 {
+  /* NOTE: Depsgraph is supposed to have ID node already. */
+
  IDNode *id_node = depsgraph->find_id_node(id_orig);
  BLI_assert(id_node != nullptr);
  return deg_update_eval_copy_datablock(depsgraph, id_node);
--- a/source/blender/draw/engines/eevee_next/eevee_depth_of_field.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_depth_of_field.hh
@@ -188,6 +188,10 @@ class DepthOfField {
  void hole_fill_pass_sync();
  void resolve_pass_sync();

+  /**
+   * Similar to #Film::update_sample_table()
+   * but with constant filter radius and constant sample count.
+   */
  void update_sample_table();
 };

--- a/source/blender/draw/engines/eevee_next/eevee_instance.cc
+++ b/source/blender/draw/engines/eevee_next/eevee_instance.cc
@@ -303,7 +303,6 @@ void Instance::object_sync(Object *ob)
  }
 }

-/* Wrapper to use with DRW_render_object_iter. */
 void Instance::object_sync_render(void *instance_,
                                  Object *ob,
                                  RenderEngine *engine,
@@ -395,10 +394,6 @@ bool Instance::do_planar_probe_sync() const
 /** \name Rendering
 * \{ */

-/**
- * Conceptually renders one sample per pixel.
- * Everything based on random sampling should be done here (i.e: DRWViews jitter)
- */
 void Instance::render_sample()
 {
  if (sampling.finished_viewport()) {
--- a/source/blender/draw/engines/eevee_next/eevee_instance.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_instance.hh
@@ -354,10 +354,15 @@ class Instance {
  }

 private:
+  /** Wrapper to use with #DRW_render_object_iter. */
  static void object_sync_render(void *instance_,
                                 Object *ob,
                                 RenderEngine *engine,
                                 Depsgraph *depsgraph);
+  /**
+   * Conceptually renders one sample per pixel.
+   * Everything based on random sampling should be done here (i.e: DRWViews jitter)
+   */
  void render_sample();
  void render_read_result(RenderLayer *render_layer, const char *view_name);

--- a/source/blender/draw/engines/eevee_next/eevee_sampling.cc
+++ b/source/blender/draw/engines/eevee_next/eevee_sampling.cc
@@ -315,8 +315,6 @@ void Sampling::dof_disk_sample_get(float *r_radius, float *r_theta) const
 /** \name Cumulative Distribution Function (CDF)
 * \{ */

-/* Creates a discrete cumulative distribution function table from a given curvemapping.
- * Output cdf vector is expected to already be sized according to the wanted resolution. */
 void Sampling::cdf_from_curvemapping(const CurveMapping &curve, Vector<float> &cdf)
 {
  BLI_assert(cdf.size() > 1);
@@ -334,8 +332,6 @@ void Sampling::cdf_from_curvemapping(const CurveMapping &curve, Vector<float> &c
  cdf.last() = 1.0f;
 }

-/* Inverts a cumulative distribution function.
- * Output vector is expected to already be sized according to the wanted resolution. */
 void Sampling::cdf_invert(Vector<float> &cdf, Vector<float> &inverted_cdf)
 {
  BLI_assert(cdf.first() == 0.0f && cdf.last() == 1.0f);
--- a/source/blender/draw/engines/eevee_next/eevee_sampling.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_sampling.hh
@@ -216,7 +216,16 @@ class Sampling {
  }

  /* Cumulative Distribution Function Utils. */
+
+  /**
+   * Creates a discrete cumulative distribution function table from a given curvemapping.
+   * Output cdf vector is expected to already be sized according to the wanted resolution.
+   */
  static void cdf_from_curvemapping(const CurveMapping &curve, Vector<float> &cdf);
+  /**
+   * Inverts a cumulative distribution function.
+   * Output vector is expected to already be sized according to the wanted resolution.
+   */
  static void cdf_invert(Vector<float> &cdf, Vector<float> &inverted_cdf);
 };

--- a/source/blender/draw/engines/eevee_next/eevee_shader.cc
+++ b/source/blender/draw/engines/eevee_next/eevee_shader.cc
@@ -998,8 +998,6 @@ GPUMaterial *ShaderModule::world_shader_get(::World *blender_world,
                               this);
 }

-/* Variation to compile a material only with a nodetree. Caller needs to maintain the list of
- * materials and call GPU_material_free on it to update the material. */
 GPUMaterial *ShaderModule::material_shader_get(const char *name,
                                               ListBase &materials,
                                               bNodeTree *nodetree,
--- a/source/blender/draw/engines/eevee_next/eevee_shader.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_shader.hh
@@ -194,6 +194,11 @@ class ShaderModule {
  GPUMaterial *world_shader_get(::World *blender_world,
                                bNodeTree *nodetree,
                                eMaterialPipeline pipeline_type);
+
+  /**
+   * Variation to compile a material only with a `nodetree`. Caller needs to maintain the list of
+   * materials and call GPU_material_free on it to update the material.
+   */
  GPUMaterial *material_shader_get(const char *name,
                                   ListBase &materials,
                                   bNodeTree *nodetree,
--- a/source/blender/draw/engines/eevee_next/eevee_shadow.cc
+++ b/source/blender/draw/engines/eevee_next/eevee_shadow.cc
@@ -304,10 +304,11 @@ void ShadowDirectional::cascade_tilemaps_distribution_near_far_points(const Came
      light.object_to_world, camera.position() - camera.forward() * cam_data.clip_near);
 }

-/* \note All tile-maps are meant to have the same LOD but we still return a range starting at the
- * unique LOD. */
 IndexRange ShadowDirectional::cascade_level_range(const Light &light, const Camera &camera)
 {
+  /* NOTE: All tile-maps are meant to have the same LOD
+   * but we still return a range starting at the unique LOD. */
+
  using namespace blender::math;

  /* 16 is arbitrary. To avoid too much tile-map per directional lights. */
@@ -342,10 +343,6 @@ IndexRange ShadowDirectional::cascade_level_range(const Light &light, const Came
  return IndexRange(lod_level, tilemap_len);
 }

-/**
- * Distribute tile-maps in a linear pattern along camera forward vector instead of a clipmap
- * centered on camera position.
- */
 void ShadowDirectional::cascade_tilemaps_distribution(Light &light, const Camera &camera)
 {
  using namespace blender::math;
@@ -1142,7 +1139,6 @@ void ShadowModule::debug_end_sync()
  debug_draw_ps_.draw_procedural(GPU_PRIM_TRIS, 1, 3);
 }

-/* Compute approximate screen pixel density (as world space radius). */
 float ShadowModule::screen_pixel_radius(const float4x4 &wininv,
                                        bool is_perspective,
                                        const int2 &extent)
@@ -1230,7 +1226,6 @@ int ShadowModule::max_view_per_tilemap()
  return max_view_count;
 }

-/* Special culling pass to take shadow linking into consideration. */
 void ShadowModule::ShadowView::compute_visibility(ObjectBoundsBuf &bounds,
                                                  ObjectInfosBuf &infos,
                                                  uint resource_len,
--- a/source/blender/draw/engines/eevee_next/eevee_shadow.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_shadow.hh
@@ -294,6 +294,7 @@ class ShadowModule {
    }

   protected:
+    /** Special culling pass to take shadow linking into consideration. */
    virtual void compute_visibility(ObjectBoundsBuf &bounds,
                                    ObjectInfosBuf &infos,
                                    uint resource_len,
@@ -385,7 +386,7 @@ class ShadowModule {
    do_full_update_ = true;
  }

-  /** Compute approximate screen pixel space radius. */
+  /** Compute approximate screen pixel space radius (as world space radius). */
  static float screen_pixel_radius(const float4x4 &wininv,
                                   bool is_perspective,
                                   const int2 &extent);
@@ -483,6 +484,10 @@ class ShadowDirectional : public NonCopyable, NonMovable {
  IndexRange clipmap_level_range(const Camera &camera);
  IndexRange cascade_level_range(const Light &light, const Camera &camera);

+  /**
+   * Distribute tile-maps in a linear pattern along camera forward vector instead of a clipmap
+   * centered on camera position.
+   */
  void cascade_tilemaps_distribution(Light &light, const Camera &camera);
  void clipmap_tilemaps_distribution(Light &light, const Camera &camera);

--- a/source/blender/draw/engines/eevee_next/eevee_velocity.cc
+++ b/source/blender/draw/engines/eevee_next/eevee_velocity.cc
@@ -303,10 +303,6 @@ void VelocityModule::geometry_steps_fill()
  geometry_map.clear();
 }

-/**
- * In Render, moves the next frame data to previous frame data. Nullify next frame data.
- * In Viewport, the current frame data will be used as previous frame data in the next frame.
- */
 void VelocityModule::step_swap()
 {
  auto swap_steps = [&](eVelocityStep step_a, eVelocityStep step_b) {
@@ -346,7 +342,6 @@ void VelocityModule::begin_sync()
  object_steps_usage[step_] = 0;
 }

-/* This is the end of the current frame sync. Not the step_sync. */
 void VelocityModule::end_sync()
 {
  Vector<ObjectKey, 0> deleted_obj;
--- a/source/blender/draw/engines/eevee_next/eevee_velocity.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_velocity.hh
@@ -112,10 +112,14 @@ class VelocityModule {
                        ModifierData *modifier_data = nullptr,
                        ParticleSystem *particle_sys = nullptr);

-  /* Moves next frame data to previous frame data. Nullify next frame data. */
+  /**
+   * In Render, moves the next frame data to previous frame data. Nullify next frame data.
+   * In Viewport, the current frame data will be used as previous frame data in the next frame.
+   */
  void step_swap();

  void begin_sync();
+  /** This is the end of the current frame sync. Not the step_sync. */
  void end_sync();

  void bind_resources(DRWShadingGroup *grp);
--- a/source/blender/draw/engines/eevee_next/eevee_world.cc
+++ b/source/blender/draw/engines/eevee_next/eevee_world.cc
@@ -43,7 +43,6 @@ DefaultWorldNodeTree::~DefaultWorldNodeTree()
  MEM_SAFE_FREE(ntree_);
 }

-/* Configure a default node-tree with the given world. */
 bNodeTree *DefaultWorldNodeTree::nodetree_get(::World *wo)
 {
  /* WARNING: This function is not thread-safe. Which is not a problem for the moment. */
--- a/source/blender/draw/engines/eevee_next/eevee_world.hh
+++ b/source/blender/draw/engines/eevee_next/eevee_world.hh
@@ -36,6 +36,7 @@ class DefaultWorldNodeTree {
  DefaultWorldNodeTree();
  ~DefaultWorldNodeTree();

+  /** Configure a default node-tree with the given world. */
  bNodeTree *nodetree_get(::World *world);
 };

--- a/source/blender/draw/engines/workbench/workbench_mesh_passes.cc
+++ b/source/blender/draw/engines/workbench/workbench_mesh_passes.cc
@@ -12,9 +12,10 @@ namespace blender::workbench {

 MeshPass::MeshPass(const char *name) : PassMain(name){};

-/* Move to draw::Pass */
 bool MeshPass::is_empty() const
 {
+  /* TODO: Move to #draw::Pass. */
+
  return is_empty_;
 }

--- a/source/blender/draw/intern/draw_cache.cc
+++ b/source/blender/draw/intern/draw_cache.cc
@@ -387,6 +387,7 @@ static blender::gpu::VertBuf *sphere_wire_vbo(const float rad, int flag)
 }

 /* Quads */
+
 blender::gpu::Batch *DRW_cache_fullscreen_quad_get()
 {
  if (!SHC.drw_fullscreen_quad) {
--- a/source/blender/draw/intern/draw_common.cc
+++ b/source/blender/draw/intern/draw_common.cc
@@ -33,6 +33,7 @@
 /**
 * Colors & Constant.
 */
+
 DRW_Global G_draw{};

 static bool weight_ramp_custom = false;
@@ -295,9 +296,10 @@ DRWView *DRW_view_create_with_zoffset(const DRWView *parent_view,

 /* ******************************************** COLOR UTILS ************************************ */

-/* TODO: FINISH. */
 int DRW_object_wire_theme_get(Object *ob, ViewLayer *view_layer, float **r_color)
 {
+  /* TODO: FINISH. */
+
  const DRWContextState *draw_ctx = DRW_context_state_get();
  const bool is_edit = (draw_ctx->object_mode & OB_MODE_EDIT) && (ob->mode & OB_MODE_EDIT);
  BKE_view_layer_synced_ensure(draw_ctx->scene, view_layer);
@@ -388,9 +390,10 @@ int DRW_object_wire_theme_get(Object *ob, ViewLayer *view_layer, float **r_color
  return theme_id;
 }

-/* XXX This is very stupid, better find something more general. */
 float *DRW_color_background_blend_get(int theme_id)
 {
+  /* XXX This is very stupid, better find something more general. */
+
  static float colors[11][4];
  float *ret;

--- a/source/blender/draw/intern/draw_debug.cc
+++ b/source/blender/draw/intern/draw_debug.cc
@@ -335,9 +335,10 @@ void DebugDraw::draw_line(float3 v1, float3 v2, uint color)
  }
 }

-/* Keep in sync with drw_debug_color_pack(). */
 uint DebugDraw::color_pack(float4 color)
 {
+  /* NOTE: keep in sync with #drw_debug_color_pack(). */
+
  color = math::clamp(color, 0.0f, 1.0f);
  uint result = 0;
  result |= uint(color.x * 255.0f) << 0u;
@@ -619,11 +620,10 @@ void drw_debug_draw()
 #endif
 }

-/**
- * NOTE: Init is once per draw manager cycle.
- */
 void drw_debug_init()
 {
+  /* NOTE: Init is once per draw manager cycle. */
+
  /* Module should not be used in release builds. */
  /* TODO(@fclem): Hide the functions declarations without using `ifdefs` everywhere. */
 #ifdef DRAW_DEBUG
--- a/source/blender/draw/intern/draw_resource.cc
+++ b/source/blender/draw/intern/draw_resource.cc
@@ -19,13 +19,10 @@
 /** \name ObjectAttributes
 * \{ */

-/**
- * Go through all possible source of the given object uniform attribute.
- * Returns true if the attribute was correctly filled.
- * This function mirrors lookup_instance_property in cycles/blender/blender_object.cpp
- */
 bool ObjectAttribute::sync(const blender::draw::ObjectRef &ref, const GPUUniformAttr &attr)
 {
+  /* This function mirrors `lookup_instance_property` in `cycles/blender/blender_object.cpp`. */
+
  hash_code = attr.hash_code;

  /* If requesting instance data, check the parent particle system and object. */
--- a/source/blender/draw/intern/draw_shader_shared.hh
+++ b/source/blender/draw/intern/draw_shader_shared.hh
@@ -274,6 +274,10 @@ struct ObjectAttribute {
  uint hash_code;

 #if !defined(GPU_SHADER) && defined(__cplusplus)
+  /**
+   * Go through all possible source of the given object uniform attribute.
+   * Returns true if the attribute was correctly filled.
+   */
  bool sync(const blender::draw::ObjectRef &ref, const GPUUniformAttr &attr);
 #endif
 };
--- a/source/blender/editors/include/ED_node_preview.hh
+++ b/source/blender/editors/include/ED_node_preview.hh
@@ -41,10 +41,17 @@ struct NestedTreePreviews {
 };

 void free_previews(wmWindowManager &wm, SpaceNode &snode);
+/**
+ * \note #node_release_preview_ibuf should be called after this.
+ */
 ImBuf *node_preview_acquire_ibuf(bNodeTree &ntree,
                                 NestedTreePreviews &tree_previews,
                                 const bNode &node);
 void node_release_preview_ibuf(NestedTreePreviews &tree_previews);
+/**
+ * This function returns the `NestedTreePreviews *` for the node-tree shown in the #SpaceNode.
+ * This is the first function in charge of the previews by calling `ensure_nodetree_previews`.
+ */
 NestedTreePreviews *get_nested_previews(const bContext &C, SpaceNode &snode);

 }  // namespace blender::ed::space_node
--- a/source/blender/editors/interface/views/grid_view.cc
+++ b/source/blender/editors/interface/views/grid_view.cc
@@ -45,9 +45,10 @@ AbstractGridViewItem &AbstractGridView::add_item(std::unique_ptr<AbstractGridVie
  return added_item;
 }

-/* Implementation for the base class virtual function. More specialized iterators below. */
 void AbstractGridView::foreach_view_item(FunctionRef<void(AbstractViewItem &)> iter_fn) const
 {
+  /* Implementation for the base class virtual function. More specialized iterators below. */
+
  for (const auto &item_ptr : items_) {
    iter_fn(*item_ptr);
  }
--- a/source/blender/editors/interface/views/tree_view.cc
+++ b/source/blender/editors/interface/views/tree_view.cc
@@ -95,9 +95,10 @@ void TreeViewItemContainer::foreach_parent(ItemIterFn iter_fn) const

 /* ---------------------------------------------------------------------- */

-/* Implementation for the base class virtual function. More specialized iterators below. */
 void AbstractTreeView::foreach_view_item(FunctionRef<void(AbstractViewItem &)> iter_fn) const
 {
+  /* Implementation for the base class virtual function. More specialized iterators below. */
+
  this->foreach_item_recursive(iter_fn);
 }

--- a/source/blender/editors/sculpt_paint/brushes/enhance_details.cc
+++ b/source/blender/editors/sculpt_paint/brushes/enhance_details.cc
@@ -187,12 +187,6 @@ static void calc_translations_bmesh(const bke::pbvh::BMeshNode &node,

 }  // namespace enhance_details_cc

-/**
- * The brush uses translations calculated at the beginning of the stroke. They can't be calculated
- * dynamically because changing positions will influence neighboring translations. However we can
- * reduce the cost in some cases by skipping initializing values for vertices in hidden or masked
- * nodes.
- */
 void calc_smooth_translations(const Depsgraph &depsgraph,
                              const Object &object,
                              const IndexMask &node_mask,
--- a/source/blender/editors/sculpt_paint/grease_pencil_intern.hh
+++ b/source/blender/editors/sculpt_paint/grease_pencil_intern.hh
@@ -78,8 +78,11 @@ float brush_point_influence(const Scene &scene,
                            const float2 &co,
                            const InputSample &sample,
                            float multi_frame_falloff);
-/* Compute the closest distance to a polygon. If the point is inside the polygon, the distance is
- * 0.0f. If the point is outside the polygon, the distance to the closest point is returned. */
+/**
+ * Compute the closest distance to the "surface".
+ * When the point is outside the polygon, compute the closest distance to the polygon points.
+ * When the point is inside the polygon return 0.
+ */
 float closest_distance_to_surface_2d(const float2 pt, const Span<float2> verts);
 /* Influence value for an entire fill. */
 float brush_fill_influence(const Scene &scene,
--- a/source/blender/editors/sculpt_paint/grease_pencil_paint_common.cc
+++ b/source/blender/editors/sculpt_paint/grease_pencil_paint_common.cc
@@ -104,8 +104,6 @@ float brush_point_influence(const Scene &scene,
  return influence_base * brush_falloff;
 }

-/* Compute the closest distance to the "surface". When the point is outside the polygon, compute
- * the closest distance to the polygon points. When the point is inside the polygon return 0.*/
 float closest_distance_to_surface_2d(const float2 pt, const Span<float2> verts)
 {
  int j = verts.size() - 1;
--- a/source/blender/editors/sculpt_paint/paint_intern.hh
+++ b/source/blender/editors/sculpt_paint/paint_intern.hh
@@ -136,6 +136,7 @@ void paint_stroke_jitter_pos(Scene &scene,
 bool paint_brush_tool_poll(bContext *C);
 /** Returns true if the brush cursor should be activated. */
 bool paint_brush_cursor_poll(bContext *C);
+/** Initialize the stroke cache variants from operator properties. */
 bool paint_brush_update(bContext *C,
                        const Brush &brush,
                        PaintMode mode,
@@ -545,6 +546,7 @@ void get_brush_alpha_data(const Scene &scene,

 void init_stroke(Depsgraph &depsgraph, Object &ob);
 void init_session_data(const ToolSettings &ts, Object &ob);
+/** Toggle operator for turning vertex paint mode on or off (copied from `sculpt.cc`) */
 void init_session(
    Main &bmain, Depsgraph &depsgraph, Scene &scene, Object &ob, eObjectMode object_mode);

@@ -562,7 +564,9 @@ bool mode_toggle_poll_test(bContext *C);
 void smooth_brush_toggle_off(const bContext *C, Paint *paint, StrokeCache *cache);
 void smooth_brush_toggle_on(const bContext *C, Paint *paint, StrokeCache *cache);

+/** Initialize the stroke cache variants from operator properties. */
 void update_cache_variants(bContext *C, VPaint &vp, Object &ob, PointerRNA *ptr);
+/** Initialize the stroke cache invariants from operator properties. */
 void update_cache_invariants(
    bContext *C, VPaint &vp, SculptSession &ss, wmOperator *op, const float mval[2]);
 void last_stroke_update(Scene &scene, const float location[3]);
--- a/source/blender/editors/sculpt_paint/paint_stroke.cc
+++ b/source/blender/editors/sculpt_paint/paint_stroke.cc
@@ -283,7 +283,6 @@ static bool image_paint_brush_type_require_inbetween_mouse_events(const Brush &b
  return true;
 }

-/* Initialize the stroke cache variants from operator properties */
 bool paint_brush_update(bContext *C,
                        const Brush &brush,
                        PaintMode mode,
--- a/source/blender/editors/sculpt_paint/paint_vertex.cc
+++ b/source/blender/editors/sculpt_paint/paint_vertex.cc
@@ -222,7 +222,6 @@ void init_stroke(Depsgraph &depsgraph, Object &ob)
  }
 }

-/* Toggle operator for turning vertex paint mode on or off (copied from sculpt.cc) */
 void init_session(
    Main &bmain, Depsgraph &depsgraph, Scene &scene, Object &ob, eObjectMode object_mode)
 {
@@ -436,7 +435,6 @@ void smooth_brush_toggle_off(const bContext *C, Paint *paint, StrokeCache *cache
    cache->saved_active_brush = nullptr;
  }
 }
-/* Initialize the stroke cache invariants from operator properties */
 void update_cache_invariants(
    bContext *C, VPaint &vp, SculptSession &ss, wmOperator *op, const float mval[2])
 {
@@ -506,7 +504,6 @@ void update_cache_invariants(
  cache->accum = true;
 }

-/* Initialize the stroke cache variants from operator properties */
 void update_cache_variants(bContext *C, VPaint &vp, Object &ob, PointerRNA *ptr)
 {
  using namespace blender;
@@ -577,6 +574,7 @@ void last_stroke_update(Scene &scene, const float location[3])
 }

 /* -------------------------------------------------------------------- */
+
 void smooth_brush_toggle_on(const bContext *C, Paint *paint, StrokeCache *cache)
 {
  Main *bmain = CTX_data_main(C);
--- a/source/blender/editors/sculpt_paint/sculpt_intern.hh
+++ b/source/blender/editors/sculpt_paint/sculpt_intern.hh
@@ -689,13 +689,18 @@ void SCULPT_tilt_effective_normal_get(const SculptSession &ss, const Brush &brus
 /** \} */

 namespace blender::ed::sculpt_paint {
-
+/**
+ * The brush uses translations calculated at the beginning of the stroke. They can't be calculated
+ * dynamically because changing positions will influence neighboring translations. However we can
+ * reduce the cost in some cases by skipping initializing values for vertices in hidden or masked
+ * nodes.
+ */
 void calc_smooth_translations(const Depsgraph &depsgraph,
                              const Object &object,
                              const IndexMask &node_mask,
                              MutableSpan<float3> translations);

-}
+}  // namespace blender::ed::sculpt_paint

 /**
 * Flip all the edit-data across the axis/axes specified by \a symm.
--- a/source/blender/editors/space_node/node_edit.cc
+++ b/source/blender/editors/space_node/node_edit.cc
@@ -675,11 +675,10 @@ void ED_node_texture_default(const bContext *C, Tex *tex)

 namespace blender::ed::space_node {

-/**
- * Here we set the active tree(s), even called for each redraw now, so keep it fast :)
- */
 void snode_set_context(const bContext &C)
 {
+  /* NOTE: Here we set the active tree(s), even called for each redraw now, so keep it fast :). */
+
  SpaceNode *snode = CTX_wm_space_node(&C);
  bke::bNodeTreeType *treetype = bke::node_tree_type_find(snode->tree_idname);
  bNodeTree *ntree = snode->nodetree;
--- a/source/blender/editors/space_node/node_intern.hh
+++ b/source/blender/editors/space_node/node_intern.hh
@@ -308,6 +308,7 @@ void NODE_OT_default_group_width_set(wmOperatorType *ot);

 void update_multi_input_indices_for_removed_links(bNode &node);
 bool all_links_muted(const bNodeSocket &socket);
+/** Get the "main" socket based on the node declaration or an heuristic. */
 bNodeSocket *get_main_socket(bNodeTree &ntree, bNode &node, eNodeSocketInOut in_out);

 void NODE_OT_link(wmOperatorType *ot);
--- a/source/blender/editors/space_node/node_relationships.cc
+++ b/source/blender/editors/space_node/node_relationships.cc
@@ -2518,7 +2518,6 @@ static int get_main_socket_priority(const bNodeSocket *socket)
  return -1;
 }

-/** Get the "main" socket based on the node declaration or an heuristic. */
 bNodeSocket *get_main_socket(bNodeTree &ntree, bNode &node, eNodeSocketInOut in_out)
 {
  ListBase *sockets = (in_out == SOCK_IN) ? &node.inputs : &node.outputs;
--- a/source/blender/editors/space_node/node_shader_preview.cc
+++ b/source/blender/editors/space_node/node_shader_preview.cc
@@ -130,10 +130,6 @@ static std::optional<ComputeContextHash> get_compute_context_hash_for_node_edito
  return compute_context_builder.hash();
 }

-/*
- * This function returns the `NestedTreePreviews *` for the nodetree shown in the SpaceNode.
- * This is the first function in charge of the previews by calling `ensure_nodetree_previews`.
- */
 NestedTreePreviews *get_nested_previews(const bContext &C, SpaceNode &snode)
 {
  if (snode.id == nullptr || GS(snode.id->name) != ID_MA) {
@@ -306,7 +302,6 @@ static ImBuf *get_image_from_viewlayer_and_pass(RenderResult &rr,
  return ibuf;
 }

-/* `node_release_preview_ibuf` should be called after this. */
 ImBuf *node_preview_acquire_ibuf(bNodeTree &ntree,
                                 NestedTreePreviews &tree_previews,
                                 const bNode &node)
--- a/source/blender/editors/space_outliner/outliner_intern.hh
+++ b/source/blender/editors/space_outliner/outliner_intern.hh
@@ -506,6 +506,10 @@ void OUTLINER_OT_orphans_manage(wmOperatorType *ot);

 /* `outliner_query.cc` */

+/**
+ * Iterate over the entire tree (including collapsed sub-elements),
+ * probing if any of the elements has a warning to be displayed.
+ */
 bool outliner_shows_mode_column(const SpaceOutliner &space_outliner);
 bool outliner_has_element_warnings(const SpaceOutliner &space_outliner);

--- a/source/blender/editors/space_outliner/outliner_query.cc
+++ b/source/blender/editors/space_outliner/outliner_query.cc
@@ -24,10 +24,6 @@ bool outliner_shows_mode_column(const SpaceOutliner &space_outliner)
  return tree_display.supports_mode_column() && (space_outliner.flag & SO_MODE_COLUMN);
 }

-/**
- * Iterate over the entire tree (including collapsed sub-elements), probing if any of the elements
- * has a warning to be displayed.
- */
 bool outliner_has_element_warnings(const SpaceOutliner &space_outliner)
 {
  std::function<bool(const ListBase &)> recursive_fn;
--- a/source/blender/editors/space_view3d/view3d_navigate_view_dolly.cc
+++ b/source/blender/editors/space_view3d/view3d_navigate_view_dolly.cc
@@ -27,9 +27,10 @@
 * which avoids #RegionView3D.dist approaching zero.
 * \{ */

-/* This is an exact copy of #viewzoom_modal_keymap. */
 void viewdolly_modal_keymap(wmKeyConfig *keyconf)
 {
+  /* NOTE: This is an exact copy of #viewzoom_modal_keymap. */
+
  static const EnumPropertyItem modal_items[] = {
      {VIEW_MODAL_CANCEL, "CANCEL", 0, "Cancel", ""},
      {VIEW_MODAL_CONFIRM, "CONFIRM", 0, "Confirm", ""},
--- a/source/blender/editors/space_view3d/view3d_navigate_view_zoom.cc
+++ b/source/blender/editors/space_view3d/view3d_navigate_view_zoom.cc
@@ -26,9 +26,10 @@
 /** \name View Zoom Operator
 * \{ */

-/* #viewdolly_modal_keymap has an exact copy of this, apply fixes to both. */
 void viewzoom_modal_keymap(wmKeyConfig *keyconf)
 {
+  /* NOTE: #viewdolly_modal_keymap has an exact copy of this, apply fixes to both. */
+
  static const EnumPropertyItem modal_items[] = {
      {VIEW_MODAL_CANCEL, "CANCEL", 0, "Cancel", ""},
      {VIEW_MODAL_CONFIRM, "CONFIRM", 0, "Confirm", ""},
--- a/source/blender/editors/transform/transform.cc
+++ b/source/blender/editors/transform/transform.cc
@@ -60,7 +60,6 @@ using namespace blender;
 /** \name General Utils
 * \{ */

-/* Calculates projection vector based on a location. */
 void transform_view_vector_calc(const TransInfo *t, const float focus[3], float r_vec[3])
 {
  if (t->persp != RV3D_ORTHO) {
--- a/source/blender/editors/transform/transform.hh
+++ b/source/blender/editors/transform/transform.hh
@@ -727,6 +727,7 @@ void transform_final_value_get(const TransInfo *t, float *value, int value_num);
 /** \name General Utils
 * \{ */

+/** Calculates projection vector based on a location. */
 void transform_view_vector_calc(const TransInfo *t, const float focus[3], float r_vec[3]);
 bool transdata_check_local_islands(TransInfo *t, short around);

--- a/source/blender/editors/transform/transform_snap_object.cc
+++ b/source/blender/editors/transform/transform_snap_object.cc
@@ -845,12 +845,13 @@ static eSnapMode snap_edge_points(SnapObjectContext *sctx, const float dist_px_s
      sctx, sctx->ret.ob, sctx->ret.data, sctx->ret.obmat, dist_px_sq_orig, sctx->ret.index);
 }

-/* May extend later (for now just snaps to empty or camera center). */
 eSnapMode snap_object_center(SnapObjectContext *sctx,
                             const Object *ob_eval,
                             const float4x4 &obmat,
                             eSnapMode snap_to_flag)
 {
+  /* May extend later (for now just snaps to empty or camera center). */
+
  if (ob_eval->transflag & OB_DUPLI) {
    return SCE_SNAP_TO_NONE;
  }
--- a/source/blender/gpu/opengl/gl_texture.cc
+++ b/source/blender/gpu/opengl/gl_texture.cc
@@ -758,9 +758,10 @@ void GLTexture::check_feedback_loop()
  }
 }

-/* TODO(fclem): Legacy. Should be removed at some point. */
 uint GLTexture::gl_bindcode_get() const
 {
+  /* TODO(fclem): Legacy. Should be removed at some point. */
+
  return tex_id_;
 }

--- a/source/blender/gpu/vulkan/vk_buffer.cc
+++ b/source/blender/gpu/vulkan/vk_buffer.cc
@@ -50,16 +50,17 @@ static VkMemoryPropertyFlags vma_required_flags(const bool is_host_visible)
  return is_host_visible ? VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT : 0;
 }

-/*
- * TODO: Check which memory is selected and adjust the creation flag to add mapping. This way the
- * staging buffer can be skipped, or in case of a vertex buffer an intermediate buffer can be
- * removed.
- */
 bool VKBuffer::create(size_t size_in_bytes,
                      GPUUsageType usage,
                      VkBufferUsageFlags buffer_usage,
                      const bool is_host_visible)
 {
+  /*
+   * TODO: Check which memory is selected and adjust the creation flag to add mapping. This way the
+   * staging buffer can be skipped, or in case of a vertex buffer an intermediate buffer can be
+   * removed.
+   */
+
  BLI_assert(!is_allocated());
  BLI_assert(vk_buffer_ == VK_NULL_HANDLE);
  BLI_assert(mapped_memory_ == nullptr);
--- a/source/blender/gpu/vulkan/vk_texture.cc
+++ b/source/blender/gpu/vulkan/vk_texture.cc
@@ -321,9 +321,10 @@ void VKTexture::update_sub(int offset_[3],
  update_sub(0, offset_, extent_, format, pixel_buffer.map());
 }

-/* TODO(fclem): Legacy. Should be removed at some point. */
 uint VKTexture::gl_bindcode_get() const
 {
+  /* TODO(fclem): Legacy. Should be removed at some point. */
+
  return 0;
 }

--- a/source/blender/imbuf/intern/cineon/logImageCore.cc
+++ b/source/blender/imbuf/intern/cineon/logImageCore.cc
@@ -235,9 +235,10 @@ static size_t getRowLength(size_t width, const LogImageElement &logElement)
  return 0;
 }

-/* For the C-API. */
 size_t getRowLength(size_t width, const LogImageElement *logElement)
 {
+  /* For the C-API. */
+
  return getRowLength(width, *logElement);
 }

--- a/source/blender/io/common/intern/subdiv_disabler.cc
+++ b/source/blender/io/common/intern/subdiv_disabler.cc
@@ -20,17 +20,18 @@

 namespace blender::io {

-/* Returns the last subdiv modifier associated with an object,
- * if that modifier should be disabled.
- * We do not disable the subdiv modifier if other modifiers are
- * applied after it, with the sole exception of particle modifiers,
- * which are allowed.
- * Returns nullptr if there is not any subdiv modifier to disable.
- */
 ModifierData *SubdivModifierDisabler::get_subdiv_modifier(Scene *scene,
                                                          const Object *ob,
                                                          ModifierMode mode)
 {
+  /* Returns the last subdiv modifier associated with an object,
+   * if that modifier should be disabled.
+   * We do not disable the subdiv modifier if other modifiers are
+   * applied after it, with the sole exception of particle modifiers,
+   * which are allowed.
+   * Returns nullptr if there is not any subdiv modifier to disable.
+   */
+
  ModifierData *md = static_cast<ModifierData *>(ob->modifiers.last);

  for (; md; md = md->prev) {
--- a/source/blender/io/usd/intern/usd_writer_material.cc
+++ b/source/blender/io/usd/intern/usd_writer_material.cc
@@ -933,9 +933,6 @@ std::string get_tex_image_asset_filepath(Image *ima,
  return get_tex_image_asset_filepath(path, stage_path, export_params);
 }

-/* Return a USD asset path referencing the given texture file. The resulting path
- * may be absolute, relative to the USD file, or in a 'textures' directory
- * in the same directory as the USD file, depending on the export parameters. */
 std::string get_tex_image_asset_filepath(const std::string &path,
                                         const std::string &stage_path,
                                         const USDExportParams &export_params)
--- a/source/blender/io/usd/intern/usd_writer_material.hh
+++ b/source/blender/io/usd/intern/usd_writer_material.hh
@@ -17,7 +17,8 @@ namespace blender::io::usd {
 struct USDExporterContext;
 struct USDExportParams;

-/* Create USDMaterial from Blender material.
+/**
+ * Create USDMaterial from Blender material.
 *
 * \param default_uv: used as the default UV set name sampled by the `primvar`
 * reader shaders generated for image texture nodes that don't have an attached UVMap node.
@@ -28,8 +29,10 @@ pxr::UsdShadeMaterial create_usd_material(const USDExporterContext &usd_export_c
                                          const std::string &active_uvmap_name,
                                          ReportList *reports);

-/* Returns a USDPreviewSurface token name for a given Blender shader Socket name,
- * or an empty TfToken if the input name is not found in the map. */
+/**
+ * Returns a USDPreviewSurface token name for a given Blender shader Socket name,
+ * or an empty TfToken if the input name is not found in the map.
+ */
 pxr::TfToken token_for_input(const char *input_name);

 void export_texture(bNode *node,
@@ -37,13 +40,15 @@ void export_texture(bNode *node,
                    const bool allow_overwrite = false,
                    ReportList *reports = nullptr);

-/* Gets an asset path for the given texture image / node. The resulting path
+/**
+ * Gets an asset path for the given texture image / node. The resulting path
 * may be absolute, relative to the USD file, or in a 'textures' directory
 * in the same directory as the USD file, depending on the export parameters.
 * The filename is typically the image filepath but might also be automatically
 * generated based on the image name for in-memory textures when exporting textures.
 * This function may return an empty string if the image does not have a filepath
- * assigned and no asset path could be determined. */
+ * assigned and no asset path could be determined.
+ */
 std::string get_tex_image_asset_filepath(bNode *node,
                                         const pxr::UsdStageRefPtr stage,
                                         const USDExportParams &export_params);
@@ -51,7 +56,12 @@ std::string get_tex_image_asset_filepath(bNode *node,
 std::string get_tex_image_asset_filepath(Image *ima,
                                         const pxr::UsdStageRefPtr stage,
                                         const USDExportParams &export_params);
-
+/**
+ * Return a USD asset path referencing the given texture file.
+ * The resulting path may be absolute, relative to the USD file,
+ * or in a 'textures' directory in the same directory as the USD file,
+ * depending on the export parameters.
+ */
 std::string get_tex_image_asset_filepath(const std::string &asset_path,
                                         const std::string &stage_path,
                                         const USDExportParams &export_params);
--- a/source/blender/python/intern/bpy_interface.cc
+++ b/source/blender/python/intern/bpy_interface.cc
@@ -980,7 +980,13 @@ bool BPY_string_is_keyword(const char *str)
  return false;
 }

-/* EVIL: define `text.cc` functions here (declared in `BKE_text.h`). */
+/* -------------------------------------------------------------------- */
+/** \name Character Classification
+ *
+ * Define `text.cc` functions here (declared in `BKE_text.h`),
+ * This could be removed if Blender gets its own unicode library.
+ * \{ */
+
 int text_check_identifier_unicode(const uint ch)
 {
  return (ch < 255 && text_check_identifier(char(ch))) || Py_UNICODE_ISALNUM(ch);
@@ -990,3 +996,5 @@ int text_check_identifier_nodigit_unicode(const uint ch)
 {
  return (ch < 255 && text_check_identifier_nodigit(char(ch))) || Py_UNICODE_ISALPHA(ch);
 }
+
+/** \} */
--- a/source/blender/windowmanager/intern/wm_event_query.cc
+++ b/source/blender/windowmanager/intern/wm_event_query.cc
@@ -614,14 +614,13 @@ int WM_event_absolute_delta_y(const wmEvent *event)
 * \{ */

 #ifdef WITH_INPUT_IME
-/**
- * Most OS's use `Ctrl+Space` / `OsKey+Space` to switch IME,
- * so don't type in the space character.
- *
- * \note Shift is excluded from this check since it prevented typing `Shift+Space`, see: #85517.
- */
 bool WM_event_is_ime_switch(const wmEvent *event)
 {
+  /* Most OS's use `Ctrl+Space` / `OsKey+Space` to switch IME,
+   * so don't type in the space character.
+   *
+   * NOTE: Shift is excluded from this check since it prevented typing `Shift+Space`, see: #85517.
+   */
  return (event->val == KM_PRESS) && (event->type == EVT_SPACEKEY) &&
         (event->modifier & (KM_CTRL | KM_OSKEY | KM_ALT));
 }
--- a/source/blender/windowmanager/intern/wm_window.cc
+++ b/source/blender/windowmanager/intern/wm_window.cc
@@ -2981,11 +2981,10 @@ bool WM_window_is_temp_screen(const wmWindow *win)
 * \{ */

 #ifdef WITH_INPUT_IME
-/**
- * \note Keep in mind #wm_window_IME_begin is also used to reposition the IME window.
- */
 void wm_window_IME_begin(wmWindow *win, int x, int y, int w, int h, bool complete)
 {
+  /* NOTE: Keep in mind #wm_window_IME_begin is also used to reposition the IME window. */
+
  BLI_assert(win);
  if ((WM_capabilities_flag() & WM_CAPABILITY_INPUT_IME) == 0) {
    return;