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: forward propagation function
+ * - mBackward: backward propagation function
  */
 class Node : public std::enable_shared_from_this<Node> {
 private:
@@ -68,7 +78,9 @@ 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.
@@ -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.
+   * length of ctors must be lower than the number of input of the Node
    * @return Connector
    */
   Connector operator()(const std::vector<Connector> &ctors);
@@ -140,8 +153,9 @@ 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 ``_``.
+   * To generate the new name the method appends
+   * the caracter ``_`` and a number, to ensure uniqueness, it checks if the
+   * name is taken, and if it isn't, increments the number until unique.
    * If no duplicate return name, this is the exit condition.
    * @param name Base name to make unique.
    * @return A unique name in all the GraphView which contains this one.
@@ -231,7 +245,10 @@ public:
     return (i < nbInputs()) ? i : gk_IODefaultIndex;
   }
 
-
+  /**
+   * @brief Returns the number of free data inputs of the Node
+   * @return IOIndex_t
+   */
   IOIndex_t getNbFreeDataInputs() const;
 
   /**
@@ -319,6 +336,11 @@ public:
     mViews.insert(std::weak_ptr<GraphView>(graphPtr));
   }
 
+ /**
+   * @brief Remove a GraphView pointer from the list of GraphView containing
+   * the current Node.
+   * @param graphPtr Pointer to GraphView to remove from the list.
+   */
   inline void removeView(const std::shared_ptr<GraphView> &graphPtr) {
     mViews.erase(graphPtr);
   }
@@ -329,7 +351,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),
@@ -376,6 +398,11 @@ 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);
 
   /**
@@ -386,6 +413,10 @@ public:
    */
   std::set<NodePtr> getChildren() const;
 
+/**
+   * @brief Get all sets of children of the node, grouped by which output of the Node they come from
+   * @returns std::vector<std::vector<std::shared_ptr<Node>>>
+   */
   std::vector<std::vector<NodePtr>> getOrderedChildren() const;
 
   /**
@@ -397,7 +428,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.
@@ -462,14 +493,22 @@ public:
 
   /**
    * @brief  Get the set of pointers to connected node at a distance of a delta.
-   * @details the recution are cut
+   * @details positive value are toward children, negative toward parents (ex: -2 would give grandparents)
+   * the recurtion are cut
    * Return a nullptr is nofing found.
-   * @param delta Input delta.
-   * @return std::shared_ptr<Node>
+   * @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())};
@@ -506,8 +545,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);