documented new node classes

app/node/node.h

@@ -27,16 +27,68 @@
 #include "node/input.h"
 #include "node/output.h"
 
+/**
+ * @brief A single processing unit that can be connected with others to create intricate processing systems
+ *
+ * A cornerstone of "visual programming", a node is a single "function" that takes input and returns an output that can
+ * be connected to other nodes. Inputs can be either user-set or retrieved from the output of another node. By joining
+ * several nodes together, intricate, highly customizable, and infinitely extensible systems can be made for processing
+ * data. It can also all be exposed to the user without forcing them to write code or compile anything.
+ *
+ * A major example in Olive is the entire rendering workflow. To render a frame, Olive will work through a node graph
+ * that can be infinitely customized by the user to create images.
+ *
+ * This is a simple base class designed to contain all the functionality for this kind of processing connective unit.
+ * It is an abstract class intended to be subclassed to create nodes with actual functionality.
+ */
 class Node : public QObject
 {
   Q_OBJECT
 public:
   Node();
 
+  /**
+   * @brief Return the name of the node
+   *
+   * This is the node's name shown to the user. This must be overridden by subclasses, and preferably run through the
+   * translator.
+   */
   virtual QString Name() = 0;
+
+  /**
+   * @brief Return the unique identifier of the node
+   *
+   * This is used in save files and any other times a specific node must be picked out at runtime. This must be an ID
+   * completely unique to this node, and preferably in bundle identifier format (e.g. "org.company.Name"). This string
+   * should NOT be translated.
+   */
+  virtual QString id() = 0;
+
+  /**
+   * @brief Return the category this node is in (optional for subclassing, but recommended)
+   *
+   * In any organized node menus, show the node in this category. If this node should be in a subfolder of a subfolder,
+   * use a "/" to separate categories (e.g. "Distort/Noise"). The string should not start with a "/" as this will be
+   * interpreted as an empty string category. This value should be run through a translator as its largely user
+   * oriented.
+   */
   virtual QString Category();
+
+  /**
+   * @brief Return a description of this node's purpose (optional for subclassing, but recommended)
+   *
+   * A short (1-2 sentence) description of what this node should do to help the user understand its purpose. This should
+   * be run through a translator.
+   */
   virtual QString Description();
 
+  /**
+   * @brief Add a parameter to this node
+   *
+   * The Node takes ownership of this parameter.
+   *
+   * This can be either an output or an input at any time. Parameters will always appear in the order they're added.
+   */
   void AddParameter(NodeParam* param);
 
   /**
@@ -72,10 +124,38 @@ public:
   int IndexOfParameter(NodeParam* param);
 
 public slots:
+  /**
+   * @brief The main processing function
+   *
+   * The node's main purpose is to take values from inputs to set values in outputs. For whatever subclass node you
+   * create, this is where the code for that goes.
+   *
+   * Note that as a video editor, the node graph has to work across time. Depending on the purpose of your node, it may
+   * output different values depending on the time, and even if not, it will likely be receiving different input
+   * depending on the time. Most of the difficult work here is handled by NodeInput::get_value() which you should pass
+   * the `time` parameter to. It will return its value (at that time, if it's keyframed), or pass the time to a
+   * corresponding output if it's connected to one. If your node doesn't directly deal with time, the default behavior
+   * of the NodeParam objects will handle everything related to it automatically.
+   */
   virtual void Process(const rational& time) = 0;
 
 signals:
+  /**
+   * @brief Signal emitted when a node is connected to another node (creating an "edge")
+   *
+   * @param edge
+   *
+   * The edge that was added
+   */
   void EdgeAdded(NodeEdgePtr edge);
+
+  /**
+   * @brief Signal emitted when a node is disconnected from another node (removing an "edge")
+   *
+   * @param edge
+   *
+   * The edge that was removed
+   */
   void EdgeRemoved(NodeEdgePtr edge);
 };