[Bf-blender-cvs] [f5358bc1226] functions: comment on Function class

[Jacques Lucke]

Commit: f5358bc12266c3168e5383ea95804581620b26b0
Author: Jacques Lucke
Date:   Tue Jul 2 17:27:00 2019 +0200
Branches: functions
https://developer.blender.org/rBf5358bc12266c3168e5383ea95804581620b26b0

comment on Function class

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

M	source/blender/functions/core/function.hpp

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

diff --git a/source/blender/functions/core/function.hpp b/source/blender/functions/core/function.hpp
index dd238b1abfc..be9b790abbc 100644
--- a/source/blender/functions/core/function.hpp
+++ b/source/blender/functions/core/function.hpp
@@ -1,5 +1,24 @@
 #pragma once
 
+/**
+ * The `Function` class is a fundamental type of the functions system. It generically represents
+ * something that has named inputs and outputs of specific types. The function itself does not know
+ * about how it is executed, because this differs between different execution backends. It is
+ * similar to the declaration of a function in a C program, with two main differences:
+ *
+ *   - It can have an arbitrary but fixed number of inputs AND outputs.
+ *   - It can have multiple implementations. However, every implementation corresponds to a
+ *     different execution backend.
+ *
+ * The ownership semantics of instances of Function are the same as for Type.
+ *
+ * In the same way types have type extensions, a function has function bodies. These are also
+ * identified by their C++ type.
+ *
+ * The inputs and outputs of a function are immutable after it has been created. New functions
+ * should be created using the corresponding builder class.
+ */
+
 #include "type.hpp"
 #include "BLI_chained_strings.hpp"
 
@@ -28,6 +47,10 @@ class Function final : public RefCountedBase {
  public:
   Function(Function &fn) = delete;
 
+  /**
+   * Construct a new function. Instead of calling this directly, the FunctionBuilder should be
+   * used.
+   */
   Function(ChainedStringRef name,
            ArrayRef<ChainedStringRef> input_names,
            ArrayRef<SharedType> input_types,
@@ -37,25 +60,84 @@ class Function final : public RefCountedBase {
 
   ~Function();
 
+  /**
+   * Get the name of the function.
+   */
   const StringRefNull name() const;
 
+  /**
+   * Return true when the function has a body of type T. Otherwise false.
+   */
   template<typename T> inline bool has_body() const;
+
+  /**
+   * Return a type extension of type T if it exists in the function. Otherwise nullptr.
+   */
   template<typename T> inline T *body() const;
-  template<typename T, typename... Args> bool add_body(Args &&... args);
 
-  void print();
+  /**
+   * Add another implementation to the function. Every type of implementation can only be added
+   * once. Future calls with the same type are ignored.
+   */
+  template<typename T, typename... Args> bool add_body(Args &&... args);
 
+  /**
+   * Get the number of inputs.
+   */
   uint input_amount() const;
+
+  /**
+   * Get the number of outputs.
+   */
   uint output_amount() const;
+
+  /**
+   * Get the type of the input at the given index.
+   */
   SharedType &input_type(uint index);
+
+  /**
+   * Get the type of the output at the given index.
+   */
   SharedType &output_type(uint index);
+
+  /**
+   * Get the name of the input at the given index.
+   */
   StringRefNull input_name(uint index);
+
+  /**
+   * Get the name of the output at the given index.
+   */
   StringRefNull output_name(uint index);
+
+  /**
+   * Utility to get a specific type extension for all inputs.
+   * Asserts, when at least one input does not have the extension.
+   */
   template<typename T> SmallVector<T *> input_extensions() const;
+
+  /**
+   * Utility to get a specific type extension for all outputs.
+   * Asserts when at least one output does not have the extension.
+   */
   template<typename T> SmallVector<T *> output_extensions() const;
+
+  /**
+   * Get an array containing all input types.
+   */
   ArrayRef<SharedType> input_types() const;
+
+  /**
+   * Get an array containing all output types.
+   */
   ArrayRef<SharedType> output_types() const;
 
+  /**
+   * Print some debug information for the function.
+   */
+  void print();
+
  private:
   ChainedStringRef m_name;
   Composition m_bodies;
@@ -81,9 +163,20 @@ class FunctionBuilder {
 
  public:
   FunctionBuilder();
+
+  /**
+   * Add an input to the function with the given name and type.
+   */
   void add_input(StringRef input_name, SharedType &type);
+
+  /**
+   * Add an output to the function with the given name and type.
+   */
   void add_output(StringRef output_name, SharedType &type);
 
+  /**
+   * Create a new function with the given name and all the inputs and outputs previously added.
+   */
   SharedFunction build(StringRef function_name);
 };