From c8530d93b7bdf1a3ca820ac030e94f9e0c145516 Mon Sep 17 00:00:00 2001
From: cmoineau <cyril.moineau@cea.fr>
Date: Wed, 2 Apr 2025 07:49:33 +0000
Subject: [PATCH] Review and update of Node doxygen.
---
include/aidge/graph/Node.hpp | 107 +++++++++++++++++++----------------
1 file changed, 59 insertions(+), 48 deletions(-)
diff --git a/include/aidge/graph/Node.hpp b/include/aidge/graph/Node.hpp
index cd523f862..7319db245 100644
--- a/include/aidge/graph/Node.hpp
+++ b/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.
*/
--
GitLab