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

Ref T92709

16 files changed, 64 insertions, 52 deletions

diff --git a/source/blender/nodes/NOD_common.h b/source/blender/nodes/NOD_common.h
index fa979bb4799..e488352170b 100644
--- a/source/blender/nodes/NOD_common.h
+++ b/source/blender/nodes/NOD_common.h
@@ -35,9 +35,11 @@ void register_node_type_reroute(void);
 void register_node_type_group_input(void);
 void register_node_type_group_output(void);
 
-/* internal functions for editor */
+/* Internal functions for editor. */
+
 struct bNodeSocket *node_group_find_input_socket(struct bNode *groupnode, const char *identifier);
 struct bNodeSocket *node_group_find_output_socket(struct bNode *groupnode, const char *identifier);
+/** Make sure all group node in ntree, which use ngroup, are sync'd. */
 void node_group_update(struct bNodeTree *ntree, struct bNode *node);
 
 struct bNodeSocket *node_group_input_find_socket(struct bNode *node, const char *identifier);
diff --git a/source/blender/nodes/NOD_derived_node_tree.hh b/source/blender/nodes/NOD_derived_node_tree.hh
index 895f7ef6d5b..b4b81391fbe 100644
--- a/source/blender/nodes/NOD_derived_node_tree.hh
+++ b/source/blender/nodes/NOD_derived_node_tree.hh
@@ -72,8 +72,10 @@ class DTreeContext {
   bool is_root() const;
 };
 
-/* A (nullable) reference to a node and the context it is in. It is unique within an entire nested
- * node group hierarchy. This type is small and can be passed around by value. */
+/**
+ * A (nullable) reference to a node and the context it is in. It is unique within an entire nested
+ * node group hierarchy. This type is small and can be passed around by value.
+ */
 class DNode {
  private:
   const DTreeContext *context_ = nullptr;
@@ -100,11 +102,13 @@ class DNode {
   DOutputSocket output_by_identifier(StringRef identifier) const;
 };
 
-/* A (nullable) reference to a socket and the context it is in. It is unique within an entire
+/**
+ * A (nullable) reference to a socket and the context it is in. It is unique within an entire
  * nested node group hierarchy. This type is small and can be passed around by value.
  *
  * A #DSocket can represent an input or an output socket. If the type of a socket is known at
- * compile time is preferable to use #DInputSocket or #DOutputSocket instead. */
+ * compile time is preferable to use #DInputSocket or #DOutputSocket instead.
+ */
 class DSocket {
  protected:
   const DTreeContext *context_ = nullptr;
@@ -129,7 +133,7 @@ class DSocket {
   DNode node() const;
 };
 
-/* A (nullable) reference to an input socket and the context it is in. */
+/** A (nullable) reference to an input socket and the context it is in. */
 class DInputSocket : public DSocket {
  public:
   DInputSocket() = default;
@@ -142,10 +146,15 @@ class DInputSocket : public DSocket {
   DOutputSocket get_corresponding_group_node_output() const;
   Vector<DOutputSocket, 4> get_corresponding_group_input_sockets() const;
 
+  /**
+   * Call `origin_fn` for every "real" origin socket. "Real" means that reroutes, muted nodes
+   * and node groups are handled by this function. Origin sockets are ones where a node gets its
+   * inputs from.
+   */
   void foreach_origin_socket(FunctionRef<void(DSocket)> origin_fn) const;
 };
 
-/* A (nullable) reference to an output socket and the context it is in. */
+/** A (nullable) reference to an output socket and the context it is in. */
 class DOutputSocket : public DSocket {
  public:
   DOutputSocket() = default;
@@ -166,6 +175,11 @@ class DOutputSocket : public DSocket {
   using ForeachTargetSocketFn =
       FunctionRef<void(DInputSocket, const TargetSocketPathInfo &path_info)>;
 
+  /**
+   * Calls `target_fn` for every "real" target socket. "Real" means that reroutes, muted nodes
+   * and node groups are handled by this function. Target sockets are on the nodes that use the
+   * value from this socket.
+   */
   void foreach_target_socket(ForeachTargetSocketFn target_fn) const;
 
  private:
@@ -180,16 +194,27 @@ class DerivedNodeTree {
   VectorSet<const NodeTreeRef *> used_node_tree_refs_;
 
  public:
+  /**
+   * Construct a new derived node tree for a given root node tree. The generated derived node tree
+   * does not own the used node tree refs (so that those can be used by others as well). The caller
+   * has to make sure that the node tree refs added to #node_tree_refs live at least as long as the
+   * derived node tree.
+   */
   DerivedNodeTree(bNodeTree &btree, NodeTreeRefMap &node_tree_refs);
   ~DerivedNodeTree();
 
   const DTreeContext &root_context() const;
   Span<const NodeTreeRef *> used_node_tree_refs() const;
 
+  /**
+   * \return True when there is a link cycle. Unavailable sockets are ignored.
+   */
   bool has_link_cycles() const;
   bool has_undefined_nodes_or_sockets() const;
+  /** Calls the given callback on all nodes in the (possibly nested) derived node tree. */
   void foreach_node(FunctionRef<void(DNode)> callback) const;
 
+  /** Generates a graph in dot format. The generated graph has all node groups inlined. */
   std::string to_dot() const;
 
  private:
diff --git a/source/blender/nodes/NOD_geometry_exec.hh b/source/blender/nodes/NOD_geometry_exec.hh
index 7e8c3551f33..5f55794d88c 100644
--- a/source/blender/nodes/NOD_geometry_exec.hh
+++ b/source/blender/nodes/NOD_geometry_exec.hh
@@ -354,6 +354,11 @@ class GeoNodeExecParams {
                                                const GeometryComponent &component,
                                                const CustomDataType default_type) const;
 
+  /**
+   * If any of the corresponding input sockets are attributes instead of single values,
+   * use the highest priority attribute domain from among them.
+   * Otherwise return the default domain.
+   */
   AttributeDomain get_highest_priority_input_domain(Span<std::string> names,
                                                     const GeometryComponent &component,
                                                     const AttributeDomain default_domain) const;
diff --git a/source/blender/nodes/NOD_geometry_nodes_eval_log.hh b/source/blender/nodes/NOD_geometry_nodes_eval_log.hh
index 53ead9af241..ac2c29b4ec2 100644
--- a/source/blender/nodes/NOD_geometry_nodes_eval_log.hh
+++ b/source/blender/nodes/NOD_geometry_nodes_eval_log.hh
@@ -216,6 +216,10 @@ class LocalGeoLogger {
   void log_multi_value_socket(DSocket socket, Span<GPointer> values);
   void log_node_warning(DNode node, NodeWarningType type, std::string message);
   void log_execution_time(DNode node, std::chrono::microseconds exec_time);
+  /**
+   * Log a message that will be displayed in the node editor next to the node.
+   * This should only be used for debugging purposes and not to display information to users.
+   */
   void log_debug_message(DNode node, std::string message);
 };
 
diff --git a/source/blender/nodes/NOD_node_tree_ref.hh b/source/blender/nodes/NOD_node_tree_ref.hh
index 26a5dc9d60f..65789069231 100644
--- a/source/blender/nodes/NOD_node_tree_ref.hh
+++ b/source/blender/nodes/NOD_node_tree_ref.hh
@@ -279,6 +279,9 @@ class NodeTreeRef : NonCopyable, NonMovable {
 
   const NodeRef *find_node(const bNode &bnode) const;
 
+  /**
+   * \return True when there is a link cycle. Unavailable sockets are ignored.
+   */
   bool has_link_cycles() const;
   bool has_undefined_nodes_or_sockets() const;
 
@@ -297,6 +300,10 @@ class NodeTreeRef : NonCopyable, NonMovable {
     bool has_cycle = false;
   };
 
+  /**
+   * Sort nodes topologically from left to right or right to left.
+   * In the future the result if this could be cached on #NodeTreeRef.
+   */
   ToposortResult toposort(ToposortDirection direction) const;
 
   bNodeTree *btree() const;
diff --git a/source/blender/nodes/composite/nodes/node_composite_colorbalance.cc b/source/blender/nodes/composite/nodes/node_composite_colorbalance.cc
index 2e39a6e1ebe..1de8c486afb 100644
--- a/source/blender/nodes/composite/nodes/node_composite_colorbalance.cc
+++ b/source/blender/nodes/composite/nodes/node_composite_colorbalance.cc
@@ -39,8 +39,7 @@ static void cmp_node_colorbalance_declare(NodeDeclarationBuilder &b)
 /* Sync functions update formula parameters for other modes, such that the result is comparable.
  * Note that the results are not exactly the same due to differences in color handling
  * (sRGB conversion happens for LGG),
- * but this keeps settings comparable.
- */
+ * but this keeps settings comparable. */
 
 void ntreeCompositColorBalanceSyncFromLGG(bNodeTree *UNUSED(ntree), bNode *node)
 {
diff --git a/source/blender/nodes/intern/derived_node_tree.cc b/source/blender/nodes/intern/derived_node_tree.cc
index 420b53b62b0..dc223f07a26 100644
--- a/source/blender/nodes/intern/derived_node_tree.cc
+++ b/source/blender/nodes/intern/derived_node_tree.cc
@@ -20,10 +20,6 @@
 
 namespace blender::nodes {
 
-/* Construct a new derived node tree for a given root node tree. The generated derived node tree
- * does not own the used node tree refs (so that those can be used by others as well). The caller
- * has to make sure that the node tree refs added to #node_tree_refs live at least as long as the
- * derived node tree. */
 DerivedNodeTree::DerivedNodeTree(bNodeTree &btree, NodeTreeRefMap &node_tree_refs)
 {
   /* Construct all possible contexts immediately. This is significantly cheaper than inlining all
@@ -73,9 +69,6 @@ void DerivedNodeTree::destruct_context_recursively(DTreeContext *context)
   context->~DTreeContext();
 }
 
-/**
- * \return True when there is a link cycle. Unavailable sockets are ignored.
- */
 bool DerivedNodeTree::has_link_cycles() const
 {
   for (const NodeTreeRef *tree_ref : used_node_tree_refs_) {
@@ -96,7 +89,6 @@ bool DerivedNodeTree::has_undefined_nodes_or_sockets() const
   return false;
 }
 
-/* Calls the given callback on all nodes in the (possibly nested) derived node tree. */
 void DerivedNodeTree::foreach_node(FunctionRef<void(DNode)> callback) const
 {
   this->foreach_node_in_context_recursive(*root_context_, callback);
@@ -184,9 +176,6 @@ DInputSocket DOutputSocket::get_active_corresponding_group_output_socket() const
   return {};
 }
 
-/* Call `origin_fn` for every "real" origin socket. "Real" means that reroutes, muted nodes
- * and node groups are handled by this function. Origin sockets are ones where a node gets its
- * inputs from. */
 void DInputSocket::foreach_origin_socket(FunctionRef<void(DSocket)> origin_fn) const
 {
   BLI_assert(*this);
@@ -233,9 +222,6 @@ void DInputSocket::foreach_origin_socket(FunctionRef<void(DSocket)> origin_fn) c
   }
 }
 
-/* Calls `target_fn` for every "real" target socket. "Real" means that reroutes, muted nodes
- * and node groups are handled by this function. Target sockets are on the nodes that use the value
- * from this socket. */
 void DOutputSocket::foreach_target_socket(ForeachTargetSocketFn target_fn) const
 {
   TargetSocketPathInfo path_info;
@@ -342,7 +328,6 @@ static dot::Cluster *get_dot_cluster_for_context(
   });
 }
 
-/* Generates a graph in dot format. The generated graph has all node groups inlined. */
 std::string DerivedNodeTree::to_dot() const
 {
   dot::DirectedGraph digraph;
diff --git a/source/blender/nodes/intern/geometry_nodes_eval_log.cc b/source/blender/nodes/intern/geometry_nodes_eval_log.cc
index f504dbfd4b4..f522740b905 100644
--- a/source/blender/nodes/intern/geometry_nodes_eval_log.cc
+++ b/source/blender/nodes/intern/geometry_nodes_eval_log.cc
@@ -489,10 +489,6 @@ void LocalGeoLogger::log_execution_time(DNode node, std::chrono::microseconds ex
   node_exec_times_.append({node, exec_time});
 }
 
-/**
- * Log a message that will be displayed in the node editor next to the node. This should only be
- * used for debugging purposes and not to display information to users.
- */
 void LocalGeoLogger::log_debug_message(DNode node, std::string message)
 {
   node_debug_messages_.append({node, std::move(message)});
diff --git a/source/blender/nodes/intern/node_common.cc b/source/blender/nodes/intern/node_common.cc
index 7387047c413..9b5436bccfb 100644
--- a/source/blender/nodes/intern/node_common.cc
+++ b/source/blender/nodes/intern/node_common.cc
@@ -75,7 +75,6 @@ bNodeSocket *node_group_find_output_socket(bNode *groupnode, const char *identif
   return nullptr;
 }
 
-/* groups display their internal tree name as label */
 void node_group_label(bNodeTree *UNUSED(ntree), bNode *node, char *label, int maxlen)
 {
   BLI_strncpy(label, (node->id) ? node->id->name + 2 : IFACE_("Missing Data-Block"), maxlen);
@@ -197,7 +196,6 @@ static void group_verify_socket_list(bNodeTree *ntree,
   }
 }
 
-/* make sure all group node in ntree, which use ngroup, are sync'd */
 void node_group_update(struct bNodeTree *ntree, struct bNode *node)
 {
   /* check inputs and outputs, and remove or insert them */
@@ -305,9 +303,6 @@ static void propagate_reroute_type_from_start_socket(
   }
 }
 
-/* Global update function for Reroute node types.
- * This depends on connected nodes, so must be done as a tree-wide update.
- */
 void ntree_update_reroute_nodes(bNodeTree *ntree)
 {
   /* Contains nodes that are linked to at least one reroute node. */
diff --git a/source/blender/nodes/intern/node_common.h b/source/blender/nodes/intern/node_common.h
index cdb7b6897b9..7aa356dbc01 100644
--- a/source/blender/nodes/intern/node_common.h
+++ b/source/blender/nodes/intern/node_common.h
@@ -31,11 +31,16 @@ extern "C" {
 
 struct bNodeTree;
 
+/** Groups display their internal tree name as label. */
 void node_group_label(struct bNodeTree *ntree, struct bNode *node, char *label, int maxlen);
 bool node_group_poll_instance(struct bNode *node,
                               struct bNodeTree *nodetree,
                               const char **r_disabled_hint);
 
+/**
+ * Global update function for Reroute node types.
+ * This depends on connected nodes, so must be done as a tree-wide update.
+ */
 void ntree_update_reroute_nodes(struct bNodeTree *ntree);
 
 #ifdef __cplusplus
diff --git a/source/blender/nodes/intern/node_exec.cc b/source/blender/nodes/intern/node_exec.cc
index 18403417af3..95070bf735e 100644
--- a/source/blender/nodes/intern/node_exec.cc
+++ b/source/blender/nodes/intern/node_exec.cc
@@ -34,14 +34,12 @@
 #include "node_exec.h"
 #include "node_util.h"
 
-/* supported socket types in old nodes */
 int node_exec_socket_use_stack(bNodeSocket *sock)
 {
   /* NOTE: INT supported as FLOAT. Only for EEVEE. */
   return ELEM(sock->type, SOCK_INT, SOCK_FLOAT, SOCK_VECTOR, SOCK_RGBA, SOCK_SHADER);
 }
 
-/* for a given socket, find the actual stack entry */
 bNodeStack *node_get_socket_stack(bNodeStack *stack, bNodeSocket *sock)
 {
   if (stack && sock && sock->stack_index >= 0) {
diff --git a/source/blender/nodes/intern/node_exec.h b/source/blender/nodes/intern/node_exec.h
index de7cbb8cedb..b2e1c6564b6 100644
--- a/source/blender/nodes/intern/node_exec.h
+++ b/source/blender/nodes/intern/node_exec.h
@@ -71,8 +71,10 @@ typedef struct bNodeThreadStack {
   bool used;
 } bNodeThreadStack;
 
+/** Supported socket types in old nodes. */
 int node_exec_socket_use_stack(struct bNodeSocket *sock);
 
+/** For a given socket, find the actual stack entry. */
 struct bNodeStack *node_get_socket_stack(struct bNodeStack *stack, struct bNodeSocket *sock);
 void node_get_stack(struct bNode *node,
                     struct bNodeStack *stack,
diff --git a/source/blender/nodes/intern/node_geometry_exec.cc b/source/blender/nodes/intern/node_geometry_exec.cc
index ca89e4f67c3..b5c4e71df74 100644
--- a/source/blender/nodes/intern/node_geometry_exec.cc
+++ b/source/blender/nodes/intern/node_geometry_exec.cc
@@ -216,11 +216,6 @@ CustomDataType GeoNodeExecParams::get_input_attribute_data_type(
   return default_type;
 }
 
-/**
- * If any of the corresponding input sockets are attributes instead of single values,
- * use the highest priority attribute domain from among them.
- * Otherwise return the default domain.
- */
 AttributeDomain GeoNodeExecParams::get_highest_priority_input_domain(
     Span<std::string> names,
     const GeometryComponent &component,
diff --git a/source/blender/nodes/intern/node_tree_ref.cc b/source/blender/nodes/intern/node_tree_ref.cc
index d58521e7b72..912d5e5322c 100644
--- a/source/blender/nodes/intern/node_tree_ref.cc
+++ b/source/blender/nodes/intern/node_tree_ref.cc
@@ -441,9 +441,6 @@ static bool has_link_cycles_recursive(const NodeRef &node,
   return false;
 }
 
-/**
- * \return True when there is a link cycle. Unavailable sockets are ignored.
- */
 bool NodeTreeRef::has_link_cycles() const
 {
   const int node_amount = nodes_by_id_.size();
@@ -570,10 +567,6 @@ static void toposort_from_start_node(const NodeTreeRef::ToposortDirection direct
   }
 }
 
-/**
- * Sort nodes topologically from left to right or right to left.
- * In the future the result if this could be cached on #NodeTreeRef.
- */
 NodeTreeRef::ToposortResult NodeTreeRef::toposort(const ToposortDirection direction) const
 {
   ToposortResult result;
diff --git a/source/blender/nodes/intern/node_util.c b/source/blender/nodes/intern/node_util.c
index ecd08431e18..e4756d71114 100644
--- a/source/blender/nodes/intern/node_util.c
+++ b/source/blender/nodes/intern/node_util.c
@@ -301,11 +301,6 @@ static bNodeSocket *node_find_linkable_socket(bNodeTree *ntree,
   return NULL;
 }
 
-/**
- * The idea behind this is: When a user connects an input to a socket that is
- * already linked (and if its not an Multi Input Socket), we try to find a replacement socket for
- * the link that we try to overwrite and connect that previous link to the new socket.
- */
 void node_insert_link_default(bNodeTree *ntree, bNode *node, bNodeLink *link)
 {
   bNodeSocket *socket = link->tosock;
diff --git a/source/blender/nodes/intern/node_util.h b/source/blender/nodes/intern/node_util.h
index c064ef4ab36..5cb3540d617 100644
--- a/source/blender/nodes/intern/node_util.h
+++ b/source/blender/nodes/intern/node_util.h
@@ -82,6 +82,12 @@ void node_vector_math_label(struct bNodeTree *ntree, struct bNode *node, char *l
 void node_filter_label(struct bNodeTree *ntree, struct bNode *node, char *label, int maxlen);
 
 /*** Link Handling */
+
+/**
+ * The idea behind this is: When a user connects an input to a socket that is
+ * already linked (and if its not an Multi Input Socket), we try to find a replacement socket for
+ * the link that we try to overwrite and connect that previous link to the new socket.
+ */
 void node_insert_link_default(struct bNodeTree *ntree, struct bNode *node, struct bNodeLink *link);
 
 float node_socket_get_float(struct bNodeTree *ntree, struct bNode *node, struct bNodeSocket *sock);