Merge branch 'master' into soc-2021-uv-edge-select-supportsoc-2021-uv-edge-select-support

1 files changed, 36 insertions, 6 deletions

diff --git a/source/blender/nodes/NOD_derived_node_tree.hh b/source/blender/nodes/NOD_derived_node_tree.hh
index 895f7ef6d5b..dc619deb5d2 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:
@@ -246,6 +271,7 @@ inline bool DTreeContext::is_root() const
 {
   return parent_context_ == nullptr;
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -312,6 +338,7 @@ inline DOutputSocket DNode::output_by_identifier(StringRef identifier) const
 {
   return {context_, &node_ref_->output_by_identifier(identifier)};
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -374,6 +401,7 @@ inline DNode DSocket::node() const
   BLI_assert(socket_ref_ != nullptr);
   return {context_, &socket_ref_->node()};
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -399,6 +427,7 @@ inline const InputSocketRef *DInputSocket::operator->() const
 {
   return (const InputSocketRef *)socket_ref_;
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -424,6 +453,7 @@ inline const OutputSocketRef *DOutputSocket::operator->() const
 {
   return (const OutputSocketRef *)socket_ref_;
 }
+
 /** \} */
 
 /* -------------------------------------------------------------------- */