[Bf-blender-cvs] [c347373fc66] functions: Comment on SourceInfo, FunctionGraph and DataFlowGraphBuilder

[Jacques Lucke]

Commit: c347373fc66a4bf8e4babc6b3d92f1587b9f815c
Author: Jacques Lucke
Date:   Tue Jul 2 17:51:10 2019 +0200
Branches: functions
https://developer.blender.org/rBc347373fc66a4bf8e4babc6b3d92f1587b9f815c

Comment on SourceInfo, FunctionGraph and DataFlowGraphBuilder

===================================================================

M	source/blender/functions/core/data_flow_graph_builder.hpp
M	source/blender/functions/core/function_graph.hpp
M	source/blender/functions/core/source_info.hpp

===================================================================

diff --git a/source/blender/functions/core/data_flow_graph_builder.hpp b/source/blender/functions/core/data_flow_graph_builder.hpp
index 500574b0ae3..6a2109752bd 100644
--- a/source/blender/functions/core/data_flow_graph_builder.hpp
+++ b/source/blender/functions/core/data_flow_graph_builder.hpp
@@ -1,5 +1,12 @@
 #pragma once
 
+/**
+ * This should be used to construct new data flow graphs. Nodes and links can be added dynamically.
+ * At the same time is it possible to query information (like connected sockets) at any point.
+ * Once all nodes and links are inserted, the actual data flow graph can be build from it, which
+ * allows much faster queries, but cannot be changed anymore.
+ */
+
 #include "function.hpp"
 #include "source_info.hpp"
 
diff --git a/source/blender/functions/core/function_graph.hpp b/source/blender/functions/core/function_graph.hpp
index e02936a7320..cbc963b3818 100644
--- a/source/blender/functions/core/function_graph.hpp
+++ b/source/blender/functions/core/function_graph.hpp
@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+ * A function graph is a data flow graph with specified inputs and outputs. Therefore, it can be
+ * used to define new functions. Multiple function graphs can be build on top of the same data flow
+ * graph.
+ */
+
 #include "data_flow_graph.hpp"
 
 namespace FN {
@@ -40,7 +46,16 @@ class FunctionGraph {
     return m_outputs;
   }
 
+  /**
+   * Create a new function with the given name. The inputs and outputs correspond to the sockets in
+   * the graph. The returned function does not contain any bodies.
+   */
   SharedFunction new_function(StringRef name) const;
+
+  /**
+   * Get a subset of all sockets in the graph that can influence the function execution (under the
+   * assumption, that functions do not have side effects).
+   */
   SmallSet<DFGraphSocket> find_used_sockets(bool include_inputs, bool include_outputs) const;
 };
 
diff --git a/source/blender/functions/core/source_info.hpp b/source/blender/functions/core/source_info.hpp
index 20a8d2f3401..56e36b61e66 100644
--- a/source/blender/functions/core/source_info.hpp
+++ b/source/blender/functions/core/source_info.hpp
@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+ * The SourceInfo class is used to track debugging information through the various stages of
+ * building an function. It is not directly part of a function, because the same function can be
+ * used in very different contexts.
+ */
+
 #include <string>
 
 namespace FN {