Cleanup: move public doc-strings into headers for 'depsgraph'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.

Ref T92709

7 files changed, 43 insertions, 39 deletions

diff --git a/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc b/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
index 7da3ab78575..51582508b6f 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_nodes.cc
@@ -390,8 +390,6 @@ void DepsgraphNodeBuilder::begin_build()
  * NOTE: This is split in two, a static function and a public method of the node builder, to allow
  * the code to access the builder's data more easily. */
 
-/* `id_cow_self` is the user of `id_pointer`, see also `LibraryIDLinkCallbackData` struct
- * definition. */
 int DepsgraphNodeBuilder::foreach_id_cow_detect_need_for_update_callback(ID *id_cow_self,
                                                                          ID *id_pointer)
 {
@@ -440,21 +438,18 @@ static int foreach_id_cow_detect_need_for_update_callback(LibraryIDLinkCallbackD
   return builder->foreach_id_cow_detect_need_for_update_callback(id_cow_self, id);
 }
 
-/* Check for IDs that need to be flushed (COW-updated) because the depsgraph itself created or
- * removed some of their evaluated dependencies.
- *
- * NOTE: Currently the only ID types that depsgraph may decide to not evaluate/generate COW
- * copies for, even though they are referenced by other data-blocks, are Collections and Objects
- * (through their various visibility flags, and the ones from LayerCollections too). However, this
- * code is kept generic as it makes it more future-proof, and optimization here would give
- * negligible performance improvements in typical cases.
- *
- * NOTE: This mechanism may also 'fix' some missing update tagging from non-depsgraph code in
- * some cases. This is slightly unfortunate (as it may hide issues in other parts of Blender
- * code), but cannot really be avoided currently.
- */
 void DepsgraphNodeBuilder::update_invalid_cow_pointers()
 {
+  /* NOTE: Currently the only ID types that depsgraph may decide to not evaluate/generate COW
+   * copies for, even though they are referenced by other data-blocks, are Collections and Objects
+   * (through their various visibility flags, and the ones from #LayerCollections too). However,
+   * this code is kept generic as it makes it more future-proof, and optimization here would give
+   * negligible performance improvements in typical cases.
+   *
+   * NOTE: This mechanism may also 'fix' some missing update tagging from non-depsgraph code in
+   * some cases. This is slightly unfortunate (as it may hide issues in other parts of Blender
+   * code), but cannot really be avoided currently. */
+
   for (const IDNode *id_node : graph_->id_nodes) {
     if (id_node->previously_visible_components_mask == 0) {
       /* Newly added node/ID, no need to check it. */
@@ -1071,10 +1066,6 @@ void DepsgraphNodeBuilder::build_object_pointcache(Object *object)
                      });
 }
 
-/**
- * Build graph nodes for AnimData block and any animated images used.
- * \param id: ID-Block which hosts the AnimData
- */
 void DepsgraphNodeBuilder::build_animdata(ID *id)
 {
   /* Special handling for animated images/sequences. */
@@ -1128,9 +1119,6 @@ void DepsgraphNodeBuilder::build_animdata_nlastrip_targets(ListBase *strips)
   }
 }
 
-/**
- * Build graph nodes to update the current frame in image users.
- */
 void DepsgraphNodeBuilder::build_animation_images(ID *id)
 {
   if (BKE_image_user_id_has_animation(id)) {
@@ -1152,12 +1140,6 @@ void DepsgraphNodeBuilder::build_action(bAction *action)
   add_operation_node(&action->id, NodeType::ANIMATION, OperationCode::ANIMATION_EVAL);
 }
 
-/**
- * Build graph node(s) for Driver
- * \param id: ID-Block that driver is attached to
- * \param fcu: Driver-FCurve
- * \param driver_index: Index in animation data drivers list
- */
 void DepsgraphNodeBuilder::build_driver(ID *id, FCurve *fcurve, int driver_index)
 {
   /* Create data node for this driver */
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_nodes.h b/source/blender/depsgraph/intern/builder/deg_builder_nodes.h
index d31290ecbff..c1c80042833 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_nodes.h
+++ b/source/blender/depsgraph/intern/builder/deg_builder_nodes.h
@@ -102,6 +102,10 @@ class DepsgraphNodeBuilder : public DepsgraphBuilder {
   virtual void begin_build();
   virtual void end_build();
 
+  /**
+   * `id_cow_self` is the user of `id_pointer`,
+   * see also `LibraryIDLinkCallbackData` struct definition.
+   */
   int foreach_id_cow_detect_need_for_update_callback(ID *id_cow_self, ID *id_pointer);
 
   IDNode *add_id_node(ID *id);
@@ -199,10 +203,23 @@ class DepsgraphNodeBuilder : public DepsgraphBuilder {
   virtual void build_rigidbody(Scene *scene);
   virtual void build_particle_systems(Object *object, bool is_object_visible);
   virtual void build_particle_settings(ParticleSettings *part);
+  /**
+   * Build graph nodes for #AnimData block and any animated images used.
+   * \param id: ID-Block which hosts the #AnimData
+   */
   virtual void build_animdata(ID *id);
   virtual void build_animdata_nlastrip_targets(ListBase *strips);
+  /**
+   * Build graph nodes to update the current frame in image users.
+   */
   virtual void build_animation_images(ID *id);
   virtual void build_action(bAction *action);
+  /**
+   * Build graph node(s) for Driver
+   * \param id: ID-Block that driver is attached to
+   * \param fcu: Driver-FCurve
+   * \param driver_index: Index in animation data drivers list
+   */
   virtual void build_driver(ID *id, FCurve *fcurve, int driver_index);
   virtual void build_driver_variables(ID *id, FCurve *fcurve);
   virtual void build_driver_id_property(ID *id, const char *rna_path);
@@ -280,6 +297,10 @@ class DepsgraphNodeBuilder : public DepsgraphBuilder {
                               void *user_data);
 
   void tag_previously_tagged_nodes();
+  /**
+   * Check for IDs that need to be flushed (COW-updated)
+   * because the depsgraph itself created or removed some of their evaluated dependencies.
+   */
   void update_invalid_cow_pointers();
 
   /* State which demotes currently built entities. */
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.cc b/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.cc
index 17c2925b7f4..79f358213d3 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.cc
@@ -30,7 +30,6 @@
 
 namespace blender::deg {
 
-/* Debug contents of map */
 void RootPChanMap::print_debug()
 {
   map_.foreach_item([](StringRefNull key, const Set<StringRefNull> &values) {
@@ -42,13 +41,11 @@ void RootPChanMap::print_debug()
   });
 }
 
-/* Add a mapping. */
 void RootPChanMap::add_bone(const char *bone, const char *root)
 {
   map_.lookup_or_add_default(bone).add(root);
 }
 
-/* Check if there's a common root bone between two bones. */
 bool RootPChanMap::has_common_root(const char *bone1, const char *bone2) const
 {
   const Set<StringRefNull> *bone1_roots = map_.lookup_ptr(bone1);
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.h b/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.h
index 0dd4062c353..42f9ec9cc6a 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.h
+++ b/source/blender/depsgraph/intern/builder/deg_builder_pchanmap.h
@@ -29,13 +29,13 @@ namespace blender {
 namespace deg {
 
 struct RootPChanMap {
-  /* Debug contents of map. */
+  /** Debug contents of map. */
   void print_debug();
 
-  /* Add a mapping. */
+  /** Add a mapping. */
   void add_bone(const char *bone, const char *root);
 
-  /* Check if there's a common root bone between two bones. */
+  /** Check if there's a common root bone between two bones. */
   bool has_common_root(const char *bone1, const char *bone2) const;
 
  protected:
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_relations.cc b/source/blender/depsgraph/intern/builder/deg_builder_relations.cc
index a333f67839a..b195b2d9e11 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_relations.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_relations.cc
@@ -2073,7 +2073,8 @@ void DepsgraphRelationBuilder::build_shapekeys(Key *key)
  *        and also for the links coming from the shapekey data-blocks
  * - Animation/Drivers affecting the parameters of the geometry are made to
  *   trigger updates on the obdata geometry component, which then trigger
- *   downstream re-evaluation of the individual instances of this geometry. */
+ *   downstream re-evaluation of the individual instances of this geometry.
+ */
 void DepsgraphRelationBuilder::build_object_data_geometry(Object *object)
 {
   ID *obdata = (ID *)object->data;
@@ -2868,7 +2869,8 @@ void DepsgraphRelationBuilder::build_copy_on_write_relations()
   }
 }
 
-/* Nested datablocks (node trees, shape keys) requires special relation to
+/**
+ * Nested datablocks (node trees, shape keys) requires special relation to
  * ensure owner's datablock remapping happens after node tree itself is ready.
  *
  * This is similar to what happens in ntree_hack_remap_pointers().
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.cc b/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.cc
index bf3af571f0b..6e5c1f05cf3 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.cc
+++ b/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.cc
@@ -83,7 +83,6 @@ bool DriverDescriptor::is_array() const
   return is_array_;
 }
 
-/* Assumes that 'other' comes from the same RNA group, that is, has the same RNA path prefix. */
 bool DriverDescriptor::is_same_array_as(const DriverDescriptor &other) const
 {
   if (!is_array_ || !other.is_array_) {
diff --git a/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.h b/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.h
index c80c69be9e2..4ad5bdda1ef 100644
--- a/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.h
+++ b/source/blender/depsgraph/intern/builder/deg_builder_relations_drivers.h
@@ -37,14 +37,17 @@ namespace deg {
 /* Helper class for determining which relations are needed between driver evaluation nodes. */
 class DriverDescriptor {
  public:
-  /* Drivers are grouped by their RNA prefix. The prefix is the part of the RNA
+  /**
+   * Drivers are grouped by their RNA prefix. The prefix is the part of the RNA
    * path up to the last dot, the suffix is the remainder of the RNA path:
    *
+   * \code{.unparsed}
    * fcu->rna_path                     rna_prefix              rna_suffix
    * -------------------------------   ----------------------  ----------
    * 'color'                           ''                      'color'
    * 'rigidbody_world.time_scale'      'rigidbody_world'       'time_scale'
    * 'pose.bones["master"].location'   'pose.bones["master"]'  'location'
+   * \endcode
    */
   StringRef rna_prefix;
   StringRef rna_suffix;
@@ -54,7 +57,7 @@ class DriverDescriptor {
 
   bool driver_relations_needed() const;
   bool is_array() const;
-  /* Assumes that 'other' comes from the same RNA group, that is, has the same RNA path prefix. */
+  /** Assumes that 'other' comes from the same RNA group, that is, has the same RNA path prefix. */
   bool is_same_array_as(const DriverDescriptor &other) const;
   OperationKey depsgraph_key() const;