From 3060217d39747589d66bc4501ceaf30f59923cdc Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Fri, 10 Dec 2021 21:40:30 +1100 Subject: Cleanup: move public doc-strings into headers for 'nodes' Ref T92709 --- source/blender/nodes/NOD_common.h | 4 ++- source/blender/nodes/NOD_derived_node_tree.hh | 37 ++++++++++++++++++---- source/blender/nodes/NOD_geometry_exec.hh | 5 +++ .../blender/nodes/NOD_geometry_nodes_eval_log.hh | 4 +++ source/blender/nodes/NOD_node_tree_ref.hh | 7 ++++ .../composite/nodes/node_composite_colorbalance.cc | 3 +- source/blender/nodes/intern/derived_node_tree.cc | 15 --------- .../nodes/intern/geometry_nodes_eval_log.cc | 4 --- source/blender/nodes/intern/node_common.cc | 5 --- source/blender/nodes/intern/node_common.h | 5 +++ source/blender/nodes/intern/node_exec.cc | 2 -- source/blender/nodes/intern/node_exec.h | 2 ++ source/blender/nodes/intern/node_geometry_exec.cc | 5 --- source/blender/nodes/intern/node_tree_ref.cc | 7 ---- source/blender/nodes/intern/node_util.c | 5 --- source/blender/nodes/intern/node_util.h | 6 ++++ 16 files changed, 64 insertions(+), 52 deletions(-) (limited to 'source/blender/nodes') 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 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 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; + /** + * 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 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 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 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 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 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 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 origin_fn) const { BLI_assert(*this); @@ -233,9 +222,6 @@ void DInputSocket::foreach_origin_socket(FunctionRef 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 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); -- cgit v1.2.3