aidge#199: Add documentation for Node

aidge#199 (closed)

Context

update doc API NOde

Modified files

• Node.hpp: several doxygen descriptions have been updated
• pybind_node.cpp: several descriptions have been changed

Detailed major modifications

TODO

include/aidge/graph/Node.hpp

@@ -41,6 +41,16 @@ class GraphView;
 
 /**
  * @brief Object carrying the topological information of the computational graph.
+ * A Node contains :
+ * - mName: the name of the Node, should be unique
+ * - mViews: a set of pointers to GraphView instances including this Node instance
+ * - mOperator: a pointer to the Operator associated to the node
+ * - mParents: a vector of parent nodes, which are its inputs
+ * - mIdOutParents: a vector of indexes, which tells for all the parent nodes from which of their output we take the value
+ * - mChildren: a vector of vector of children nodes, which lists all the recipient nodes, for all of the outputs
+ * - mIdInChildren: a vector of vector of indexes, which gives for all the recipient nodes in which of their input the current value is taken
+ * - mForward: queue of forward propagation function
+ * - mBackward: queue of backward propagation function
  */
 class Node : public std::enable_shared_from_this<Node> {
 private:
@@ -68,11 +78,13 @@ private:
   std::deque<std::function<bool()>> mBackward;
 
 public:
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
   Node() = delete;
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
   /**
-   * @brief Construct a new Node object associated with the input Operator.
-   * @param op Operator giving the Node its number of connections.
+   * @brief Construct a new Node object associated with the inputted Operator.
+   * @param op The Operator of the Node, it determines its number of connections.
    * @param attrs Attributes for the Node.
    */
   Node(std::shared_ptr<Operator> op, std::shared_ptr<DynamicAttributes> attrs);
@@ -80,7 +92,7 @@ public:
 
   /**
    * @brief Construct a new Node object associated with the input Operator.
-   * @param op Operator giving the Node its number of connections.
+   * @param op The Operator of the Node, it determines its number of connections.
    * @param name (optional) name for the Node.
    */
   Node(std::shared_ptr<Operator> op, const std::string& name = "");
@@ -115,6 +127,7 @@ public:
   /**
    * @brief Functional operator for user-friendly connection interface using an ordered set of Connectors.
    * @param ctors Ordered Connectors linking their associated Node to the input of the current Node with the same index.
+   * @warning length of ctors must be lower than the number of input of the Node
    * @return Connector
    */
   Connector operator()(const std::vector<Connector> &ctors);
@@ -135,7 +148,7 @@ public:
 
   /**
    * @brief Set the Node name.
-   * @warning Undefined behaviour when several Nodes have the same name.
+   * @warning Undefined behaviour when several Nodes have the same name, use createUniqueName to avoid complications.
    * @param name New name for the node.
    */
   void setName(const std::string &name);
@@ -143,16 +156,16 @@ public:
   /**
    * @brief Given the parameter name generate a new name which is unique
    * in all the GraphView which contains this node.
-   * To generate the new name the method is called recursively and append
-   * the caracter ``_``.
-   * If no duplicate return name, this is the exit condition.
+   * @details if the inputted name is not yet used, it will be used as is
+   * if it is used, the returned name will be "name_X"
+   * name being the inputted name and X the smaller integer allowing name uniqueness
    * @param name Base name to make unique.
    * @return A unique name in all the GraphView which contains this one.
   */
   std::string createUniqueName(std::string name);
 
   /**
-   * @brief Type of the node.
+   * @brief Type of the Node's operator.
    * @return std::string
    */
   inline std::string type() const { return mOperator->type(); }
@@ -185,22 +198,22 @@ public:
   /**
    * @brief Whether or not every input of the Node is linked to a Parent.
    * If true then the Node is ready to be executed.
-   * @return true
-   * @return false
+   * @return bool
    */
   bool valid() const;
 
   /**
-   * @brief List of pair <Parent, ID of the data intput>. When an input is not
-   * linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
+   * @brief List the pairs <Parent, ID of the data intput> of the Node's inputs.
+   * @details When an input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
    * Data inputs exclude inputs expecting parameters (weights or bias).
    * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>
    */
   std::vector<std::pair<NodePtr, IOIndex_t>> dataInputs() const;
 
   /**
-   * @brief List of pair <Parent, ID of the parent output>. When an input is not linked
-   * to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
+   * @brief List the pairs <Parent, ID of the in    put> of the Node's inputs.
+   * @details When an input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
+   * as opposed to dataInputs, inputs includes inputs expecting parameters (weights or biases)
    * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>
    */
   std::vector<std::pair<NodePtr, IOIndex_t>> inputs() const;
@@ -208,7 +221,7 @@ public:
   /**
    * @brief Parent and its output Tensor ID linked to the inID-th input Tensor.
    * If the input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
-   * @param inID
+   * @param inID : the ID of the input that we want to know its parent
    * @return std::pair<std::shared_ptr<Node>, IOIndex_t>
    */
   inline std::pair<NodePtr, IOIndex_t> input(const IOIndex_t inID) const {
@@ -219,7 +232,7 @@ public:
 
   /**
    * @brief Get the lowest index in the InputData Parent list equal to the
-   * nullptr.
+   * nullptr (i.e. the ID of the first free data input).
    * Data inputs exclude inputs expecting parameters (weights or bias).
    * @return std::size_t
    */
@@ -235,22 +248,27 @@ public:
     return (i < nbInputs()) ? i : gk_IODefaultIndex;
   }
 
-
+  /**
+   * @brief Returns the number of free data inputs of the Node
+   * (i.e. data inputs that are not linked to an other node)
+   * @warning Node cannot run until all of its inputs are filled"
+   * @return IOIndex_t
+   */
   IOIndex_t getNbFreeDataInputs() const;
 
   /**
-   * @brief List input ids of children linked to outputs of the node. The vector
-   * size is garanteed to match the number of outputs of the node. If there is
-   * no connection to a given output, the corresponding sub-vector will be empty.
+   * @brief Lists Nodes and input ids of children linked to each of the outputs of the node.
+   * @details Primary vector size matches the number of outputs of the node as each sub-vector
+   * will contain the children taking from a different output
+   * If there is no connection to a given output, the corresponding sub-vector will be empty.
    * @return std::vector<std::vector<std::pair<std::shared_ptr<Node>,
    * IOIndex_t>>>
    */
   std::vector<std::vector<std::pair<NodePtr, IOIndex_t>>> outputs() const;
 
   /**
-   * @brief Children and their input Tensor ID linked to the outId-th output
-   * Tensor.
-   * @param outId
+   * @brief Lists Nodes and input ids of children linked to specified output of the Node
+   * @param outId ID of the output from which we want to know the children
    * @return std::vector<std::pair<std::shared_ptr<Node>, IOIndex_t>>
    */
   std::vector<std::pair<NodePtr, IOIndex_t>>
@@ -258,7 +276,7 @@ public:
 
   /**
    * @brief Number of inputs, including both data and learnable parameters.
-   * @details [data, data, weight, bias] => 4
+   * @details ex: [data, data, weight, bias] => 4
    * @return IOIndex_t
    */
   inline IOIndex_t nbInputs() const noexcept { return getOperator()->nbInputs(); }
@@ -266,6 +284,7 @@ public:
   /**
    * @brief Category of a specific input (Data or Param, optional or not).
    * Data inputs exclude inputs expecting parameters (weights or bias).
+   * @details ex: [data, data, weight, bias] => 2
    * @return InputCategory
    */
   inline InputCategory inputCategory(IOIndex_t idx) const {
@@ -274,8 +293,8 @@ public:
 
   /**
    * @brief Returns whether the given node parent index is a back edge
-   * A back edge is defined by the operator and node parent index
-   * correspond to operator input index.
+   * A back edge is a Node's input coming from the output of a Node later later in the GraphView
+   * @details the information is stored and taken from the Operator object of the Node
    * @return true if the operator defines it as a back edge
    */
   inline bool parentIsBackEdge(IOIndex_t idx) const {
@@ -284,6 +303,7 @@ public:
 
   /**
    * @brief Number of inputs linked to a Parent's output.
+   * @warning Inputs that are not linked will prevent the node from functioning
    * @return IOIndex_t
    */
   IOIndex_t nbValidInputs() const;
@@ -323,6 +343,12 @@ public:
     mViews.insert(std::weak_ptr<GraphView>(graphPtr));
   }
 
+ /**
+   * @brief Remove the reference of this Node to the GraphView passed as argument.
+   * @warning This function does not remove the reference of the GraphView to the Node.
+   * As such, this function is used in other function and should be not used as is by an user
+   * @param graphPtr Pointer to GraphView to remove from the list.
+   */
   inline void removeView(const std::shared_ptr<GraphView> &graphPtr) {
     mViews.erase(graphPtr);
   }
@@ -333,7 +359,7 @@ public:
    * @param outId ID of the current Node output to connect to the other Node.
    * Default to 0.
    * @param otherInId ID of the other Node input to connect to the current Node.
-   * Default to the first avaible data input.
+   * Default to the first available data input.
    */
   void addChild(NodePtr otherNode,
                 const IOIndex_t outId = IOIndex_t(0),
@@ -356,8 +382,9 @@ public:
                 std::pair<NodePtr, IOIndex_t>(nullptr, gk_IODefaultIndex));
 
   /**
-   * @brief Get the list of parent Nodes. As an input is linked to a unique Node,
-   * if none is linked then the parent is a nullptr.
+   * @brief Get the list of parent Nodes.
+   * Each input can only be linked to one Node.
+   * If an input has no linked node, the associated parent is nullptr
    * @return std::vector<std::shared_ptr<Node>>
    */
   std::vector<NodePtr> getParents() const;
@@ -380,16 +407,28 @@ public:
    */
   NodePtr popParent(const IOIndex_t inId);
 
+  /**
+   * @brief unlinks the parent from the Node and replaces it with nullptr (for coherence with remaining parents)
+   * @param inId Input index of the parent to be removed
+   * @return std::bool true if parent has been removed.
+   */
   bool removeParent(const IOIndex_t inId);
 
   /**
    * @brief Get the set of pointers to children Nodes linked to the current Node.object.
    * @details The returned set does not include any nullptr as an output maybe linked to
-   * an undifined number of Nodes. It does not change the computation of its associated Operator.
+   * an undefined number of Nodes. It does not change the computation of its associated Operator.
    * @return std::set<std::shared_ptr<Node>>>
    */
   std::set<NodePtr> getChildren() const;
 
+/**
+   * @brief Get all sets of children of the node
+   * @details Each output of the Node have a set of children (might be empty)
+   * Those sets are ordered in a set of set of children
+   *
+   * @returns std::vector<std::vector<std::shared_ptr<Node>>>
+   */
   std::vector<std::vector<NodePtr>> getOrderedChildren() const;
 
   /**
@@ -401,7 +440,7 @@ public:
 
   /**
    * @brief Remove registered child from children list of specified output if possible.
-   * If so, also remove current Node from child Node from parent.
+   * If so, also remove current Node from child's parent.
    * @param std::shared_ptr<Node> Node to remove.
    * @param outId Output index. Default 0.
    * @return true Child found and removed for given output index.
@@ -466,14 +505,21 @@ public:
 
   /**
    * @brief  Get the set of pointers to connected node at a distance of a delta.
-   * @details the recution are cut
-   * Return a nullptr is nofing found.
-   * @param delta Input delta.
-   * @return std::shared_ptr<Node>
+   * @details positive value are toward children, negative toward parents (ex: -2 would give grandparents)
+   * Return a nullptr is nothing found.
+   * @param int delta Input delta.
+   * @param std::set<Aidge::NodePtr> nodeSee is used in the recursion to avoid looping on the same nodes,
+   * should be empty when calling the method
+   * @return std::set<Aidge::NodePtr> set of nodes within expected distance from the original node
    */
-
   std::set<NodePtr> getNodeDelta(int delta,std::set<Aidge::NodePtr> nodeSee);
 
+/**
+ * @brief Makes an object taking all relevant info of the node into some string.
+ * being in a string would allow these information to be easily shown.
+ * As it shows  the node's connection it is a tool for comprehension or debugging of the Node and graph.
+ * thanks to pybind, this object should be accessible in python.
+ */
 #ifdef PYBIND
     std::string repr() const {
         std::string nodeString{fmt::format("Node(name='{}', optype='{}'", name(), type())};
@@ -510,8 +556,8 @@ private:
 
   /**
    * @brief Set the idInChildren parameter.
-   * @param inID
-   * @param newNodeOutID
+   * @param IOIndex_t inID
+   * @param IOIndex_t newNodeOutID
    */
   void setInputId(const IOIndex_t inID, const IOIndex_t newNodeOutID);