Review and update of Node doxygen.

include/aidge/graph/Node.hpp

@@ -49,8 +49,8 @@ class GraphView;
  * - 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, corresponding to the connected output index of the parent nodes.
- * - mChildren: a vector of vector of children nodes, which lists , for each output of the Node, all its children.
- * - mIdInChildren: a vector of vector of indexes, which gives for each children nodes, which of their input is linked to the current Node
+ * - mChildren: a vector of vector of children nodes, which lists, for each output of the Node, all its children.
+ * - mIdInChildren: a vector of vector of indexes, providing for each children nodes, the input index this node is connected to. The node can be connected to different input of the same child.
  * - mForward: queue of forward propagation function
  * - mBackward: queue of backward propagation function
  */
@@ -86,15 +86,15 @@ public:
   Node() = delete;
 
   /**
-   * @brief Construct a new Node object associated with the inputted Operator.
-   * @param std::shared_ptr<Operator> op: The Operator of the Node, it determines its number of connections.
-   * @param std::shared_ptr<DynamicAttributes> attrs: Attributes for the Node.
+   * @brief Construct a new Node object associated with the provided Operator.
+   * @param std::shared_ptr<Operator> op: The Operator held by the Node.
+   * @param std::shared_ptr<DynamicAttributes> attrs: DynamicAttributes of the Node.
    */
   Node(std::shared_ptr<Operator> op, std::shared_ptr<DynamicAttributes> attrs);
 //   Node(std::shared_ptr<Operator> op, const DynamicAttributes& attrs);
 
   /**
-   * @brief Construct a new Node object associated with the input Operator.
+   * @brief Construct a new Node object associated with the provided Operator.
    * @param op The Operator of the Node, it determines its number of connections.
    * @param name (optional) name for the Node.
    */
@@ -107,7 +107,7 @@ public:
   }
 
    /**
-   * @brief Add a function before the operator's Forward
+   * @brief Add a lambda function that will be called before the operator's Forward
    * @param std::function<bool()> func: The function to add
    */
   void addBeforeForward(std::function<bool()> func) {
@@ -115,7 +115,7 @@ public:
   }
 
    /**
-   * @brief Add a function after the operator's Forward
+   * @brief Add a lambda function that will be called after the operator's Forward
    * @param std::function<bool()> func: The function to add
    */
   void addAfterForward(std::function<bool()> func) {
@@ -123,7 +123,7 @@ public:
   }
 
    /**
-   * @brief Add a function before the operator's Backward
+   * @brief Add a lambda function that will be called before the operator's Backward
    * @param std::function<bool()> func: The function to add
    */
   void addBeforeBackward(std::function<bool()> func) {
@@ -131,7 +131,7 @@ public:
   }
 
    /**
-   * @brief Add a function after the operator's Backward
+   * @brief Add a lambda function that will be called after the operator's Backward
    * @param std::function<bool()> func: The function to add
    */
   void addAfterBackward(std::function<bool()> func) {
@@ -144,9 +144,11 @@ public:
   ///////////////////////////////////////////////////////
 
   /**
-   * @brief Functional operator for user-friendly connection interface using an ordered set of Connectors.
-   * @param std::vector<Connector> 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
+   * @brief Method to enable the functional declaration of a graph using an ordered set of Connectors.
+   * With this method, the node will register itself to the connector and return a new connector that
+   * contains the list of nodes that have been called.
+   * @param std::vector<Connector> ctors: Ordered Aidge::Connector 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 inputs of the Node
    * @return Connector: the new connector of the Node
    */
   Connector operator()(const std::vector<Connector> &ctors);
@@ -157,7 +159,7 @@ public:
   ///////////////////////////////////////////////////////
   /**
    * @brief Returns the attributes of the Node.
-   * @return std::shared_ptr<DynamicAttributes>: The mAttrs of the Node
+   * @return std::shared_ptr<DynamicAttributes>: The DynamicAttributes of the Node.
    */
   inline std::shared_ptr<DynamicAttributes> attributes() const {
     return mAttrs;
@@ -165,27 +167,26 @@ public:
 
   /**
    * @brief Returns the name of the Node.
-   * @todo there is no error handling, what if node has no name?
+   * @warning name is not mandatory and may be empty.
    * @return std::string: The Name of the Node
    */
   std::string name() const noexcept { return mAttrs->getAttr<std::string>("name"); }
 
   /**
    * @brief Set the Node's Name.
-   * @warning Undefined behaviour when several Nodes have the same name, use createUniqueName to avoid complications.
-   * @see createUniqueName
+   * @warning Undefined behaviour when several Nodes have the same name, use Node::createUniqueName to avoid complications.
    * @param std::string name: New name for the node.
    */
   void setName(const std::string &name);
 
   /**
    * @brief Given the parameter name generate a new name which is unique
-   * in all the GraphView which contains this node.
-   * @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
+   * in all the GraphView which contains this Node.
+   * @details if the provided name is not yet used, it will be used as is
+   * else, the returned name will be "name_X"
+   * name being the value provided by the name argument and X the smaller integer allowing name uniqueness.
    * @param std::string name: Base name to make unique.
-   * @return std::string A name not yet used in any of the GraphView which contains this node.
+   * @return std::string A name not used in any of the GraphView which contains this node.
   */
   std::string createUniqueName(std::string name);
 
@@ -200,18 +201,18 @@ public:
   ///////////////////////////////////////////////////////
 
   /**
-   * @brief Run forward() function of the associated Operator.
+   * @brief Run Operator::forward() function of the associated Operator.
    */
   void forward();
 
   /**
-   * @brief Run backward() function of the associated Operator.
+   * @brief Run Operator::backward() function of the associated Operator.
    */
   void backward();
 
   /**
-   * @brief Get the Operator object of the Node.
-   * @return std::shared_ptr<Operator> the Operator of the Node
+   * @brief Get the Operator help by the Node.
+   * @return std::shared_ptr<Operator> the Operator held by the Node
    */
   inline std::shared_ptr<Operator> getOperator() const { return mOperator; }
 //   inline std::shared_ptr<Operator> getOperator() const { return mOperator; }
@@ -221,8 +222,8 @@ public:
   ///////////////////////////////////////////////////////
 
   /**
-   * @brief Whether or not every input of the Node is linked to a Parent.
-   * @return bool: True if every input of the Node is linked to a Parent, false otherwise.
+   * @brief Whether or not every input of the Node are linked to a Parent.
+   * @return bool: True if every input of the Node are linked to a Parent, false otherwise.
    */
   bool valid() const;
 
@@ -243,32 +244,32 @@ public:
   std::vector<std::pair<NodePtr, IOIndex_t>> inputs() const;
 
   /**
-   * @brief List of names. When an input is not linked
-   * to any Parent, the value is "".
+   * @brief Return a vector of the name of the inputs of the Node
+   * The vector has the same order of the Node inputs.
    * @return std::vector<std::string>
    */
   std::vector<std::string> inputsNames() const;
 
   /**
-   * @brief Accessor of <parent_node, parent_node_output> linked to the  inID-th input input of this node.
+   * @brief Accessor of <parent_node, parent_node_output> linked to the inID-th input input of this node.
    * If the input is not linked to any Parent, the pair is <nullptr, gk_IODefaultIndex>.
-   * @param IOIndex_t inID : the ID of the input that we want to know the parent of
+   * @param IOIndex_t inID : the ID of the input we want to know the parent of
    * @return std::pair<std::shared_ptr<Node>, IOIndex_t>: The pair <Parent, output ID of the Parent> of the Node's inID-th input.
    */
   std::pair<std::shared_ptr<Node>, IOIndex_t> input(const IOIndex_t inID) const;
 
   /**
-   * @brief Name of the input.
+   * @brief Return the name of the inId-th input of the Node.
    * @param inID
    * @return std::string
    */
   std::string inputName(const IOIndex_t inID) const;
 
   /**
-   * @brief Update Name of the input.
+   * @brief Update the name of the inId-th input of the Node.
    * @param inID
    * @param newName
-   * @return std::string
+   * @return std::string the updated name
    */
   std::string inputName(const IOIndex_t inID, std::string newName);
 
@@ -294,7 +295,7 @@ public:
   /**
    * @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 mandatory inputs are filled
+   * @note Node cannot run until all of its mandatory inputs are filled
    * @return IOIndex_t: the number of free (parentless) data inputs
    */
   IOIndex_t getNbFreeDataInputs() const;
@@ -307,7 +308,11 @@ public:
    */
   std::vector<std::vector<std::pair<NodePtr, IOIndex_t>>> outputs() const;
 
-
+  /**
+   * @brief Return a vector of the name of the output of the Node
+   * The vector has the same order of the Node outputs.
+   * @return std::vector<std::string>
+   */
   std::vector<std::string> outputsNames() const;
 
   /**
@@ -319,7 +324,7 @@ public:
 
 
   /**
-   * @brief Return the output name of the Node for index.
+   * @brief Return the name of the outId-th output of the Node.
    * @param outId
    * @return std::string
    */
@@ -327,7 +332,7 @@ public:
 
 
   /**
-   * @brief Update the output name of the Node for index.
+   * @brief Update the name of the outId-th output of the Node.
    * @param outId
    * @param newName
    * @return std::string
@@ -370,7 +375,7 @@ public:
   IOIndex_t nbValidInputs() const;
 
   /**
-   * @brief Getter for the number of Output Tensors of the Node.
+   * @brief Getter for the number of Outputs of the Node.
    * @return IOIndex_t, the number of outputs of the Node's Operator
    */
   inline IOIndex_t nbOutputs() const noexcept { return mOperator->nbOutputs(); }
@@ -378,7 +383,8 @@ public:
 
   /**
    * @brief Number of outputs linked to a Child's input.
-   * @details an output having several children still counts only as one
+   * @details each output ID are counted once.
+   * So if two Nodes are connected to the 0-th output they will count as one valid output.
    * @return IOIndex_t: The number of outputs that have at least a child.
    */
   IOIndex_t nbValidOutputs() const;
@@ -395,7 +401,7 @@ public:
 
   /**
    * @brief Add a GraphView pointer to the list of GraphView containing
-   * the current Node. This feature allows transparent GraphViews.
+   * the current Node.
    * @param std::shared_ptr<GraphView> graphPtr Weak pointer to GraphView to add to the list.
    */
   inline void addView(const std::shared_ptr<GraphView> &graphPtr) {
@@ -413,7 +419,7 @@ public:
   }
 
   /**
-   * @brief Link another Node to an output of the current Node.
+   * @brief Link an other Node to an output of the current Node.
    * @param NodePtr otherNode: Pointer to the other Node.
    * @param IOIndex_t outId: ID of the current Node output to connect to the other Node.
    * Default to 0.
@@ -441,7 +447,7 @@ public:
                 std::pair<NodePtr, IOIndex_t>(nullptr, gk_IODefaultIndex));
 
   /**
-   * @brief Get the list of parent Nodes.
+   * @brief Return 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>> The vector of parent Nodes
@@ -480,7 +486,7 @@ public:
    */
   std::set<NodePtr> getChildren() const;
 
-/**
+  /**
    * @brief Get all children of the node
    * @details The parent vector size matches the number of outputs of the node.
    * Each sub-vector size will match the number of children connected to the n-th output
@@ -563,6 +569,11 @@ public:
   }
 
 #ifdef PYBIND
+    /**
+     * @brief Define a string to represent this object.
+     * See python ``__repr__`` method.
+     * @return std::string
+     */
     std::string repr() const {
         std::string nodeString{fmt::format("Node(name='{}', optype='{}'", name(), type())};
         if (mParents.size() > 0) {
@@ -608,7 +619,7 @@ private:
   ///////////////////////////////////////////////////////
 
   /**
-   * @brief Add the given Node as a child for the current Node.
+   * @brief Set the given Node as a child of the current Node.
    * @param NodePtr otherNode: The new child of the current Node
    * @param IOIndex_t outId: The output of the current Node that will welcome the new child
    * @param IOIndex_t otherInId: the input of the new child that welcomes the current Node
@@ -619,7 +630,7 @@ private:
                   const IOIndex_t otherInId);
 
   /**
-   * @brief Add the given GraphView's input Node as a child for the current Node
+   * @brief Set the given GraphView's input Node as a child for the current Node
    * @param std::shared_ptr<GraphView> otherGraph: Graphview that will take the current Node as parent
    * @param IOIndex_t outId: The output of the current Node that will be linked to the graphView
    * @param std::pair<NodePtr, IOIndex_t> otherInId) otherInId: pointer the GraphView's input Node and its input index.
@@ -629,7 +640,7 @@ private:
                     std::pair<NodePtr, IOIndex_t> otherInId);
 
   /**
-   * @brief Add a Node to the list of parents.
+   * @brief Set the given Node as a parent of the current Node.
    * @param NodePtr otherNode: Node to add to parents list.
    * @param IOIndex_t inId: input index of the Node where the parent will be added.
    */