Merge pull request #1794 from damn1/doc_ros_classes

add documentation to Node, Nodes, Contactables

src/libYARP_OS/include/yarp/os/Contactables.h

@@ -12,20 +12,43 @@
 #include <yarp/os/Contactable.h>
 
 namespace yarp {
-    namespace os {
-        class Contactables;
-    }
-}
+namespace os {
 
-class YARP_OS_API yarp::os::Contactables {
+/**
+ * @brief The yarp::os::Contactables class
+ *
+ * Generic interface for a container of `yarp::os::Contactable` objects.
+ * Implemented by ROS related classes `yarp::os::Node` and `yarp::os::Nodes`.
+ */
+class YARP_OS_API Contactables {
 public:
     virtual ~Contactables() {}
 
+    /**
+     * add a Contactable to the container.
+     * @param contactable to be added
+     */
     virtual void add(Contactable& contactable) = 0;
+
+    /**
+     * remove a Contactable from the container.
+     * @param contactable to be removed
+     */
     virtual void remove(Contactable& contactable) = 0;
 
+    /**
+     * query the container to obtain a specified contact.
+     * @param name the name of the Contact
+     * @param category the category of the Contact (tells if the Contact has a
+     *        nested writer or reader, see NestedContact.category)
+     * @return the first matched Contact with the specified name [and category]
+     *         if found, an empty contact otherwise
+     */
     virtual Contact query(const std::string& name,
                           const std::string& category = "") = 0;
 };
 
+} // namespace os
+} // namespace yarp
+
 #endif // YARP_OS_CONTACTABLES_H

src/libYARP_OS/include/yarp/os/Node.h

@@ -13,34 +13,76 @@
 #include <yarp/conf/compiler.h>
 
 namespace yarp {
-    namespace os {
-        class Node;
-    }
-}
+namespace os {
 
-
-class YARP_OS_API yarp::os::Node : public Contactables
+/**
+ * @brief The Node class
+ *
+ * A simple entity containing information about multiple contacts. Holds a port
+ * representing the Node itself and a list of other contactables that represent
+ * Publishers and Subscribers nested within the Node.
+ */
+class YARP_OS_API Node : public Contactables
 {
 public:
     Node();
     Node(const std::string& name);
     virtual ~Node();
 
+    /**
+     * add a contactable to this node. If this node still has no defined name,
+     * takes the name from the node specified in the contactable.
+     * @param contactable to be adde
+     */
     virtual void add(Contactable& contactable) override;
-    virtual void update(Contactable& contactable);
+
+    /**
+     * remove specified contactable from the list of contactables associated
+     * with this Node.
+     * @param contactable to be removed
+     */
     virtual void remove(Contactable& contactable) override;
 
+    /**
+     * query the Node to obtain Contact information about a nested port
+     * associated with this Node.
+     * @param name the nestedName to query (see NestedContact.nestedName)
+     * @param category of the contact to be queried (see NestedContact.category)
+     * @return Contact with information about required port if found, empty
+     *         Contact otherwise
+     */
     virtual Contact query(const std::string& name,
                           const std::string& category = "") override;
 
-    virtual Contact where();
+    /**
+     * update should update the contactable with new information.
+     * @param contactable to be updated
+     */
+    void update(Contactable& contactable);
 
+    /**
+     * prepare if it is not already been done, opens the port of the Node.
+     * @param name of the Node port to be opened
+     */
+    void prepare(const std::string& name);
+
+    /**
+     * interrupt delegates the call to the Node port interrupt.
+     */
     void interrupt();
 
-    virtual void prepare(const std::string& name);
+    /**
+     * where getter fot information about the port of the Node.
+     * @return a Contact with network information about this Node
+     */
+    Contact where();
+
 private:
     class Helper;
-    Helper * const mPriv;
+    Helper* const mPriv;
 };
 
+} // namespace os
+} // namespace yarp
+
 #endif // YARP_OS_NODE_H

src/libYARP_OS/include/yarp/os/Nodes.h

@@ -11,39 +11,130 @@
 
 #include <yarp/os/Contactables.h>
 
+// forward declarations:
+namespace yarp { namespace os { class Node; }}
+
 namespace yarp {
 namespace os {
 
-class Node;
-
+/**
+ * @brief The Nodes class
+ *
+ * A container for multiple nodes, keeping information about the currently
+ * active node. When a Publisher or a Subscriber is registered, a NestedContact
+ * will be created associating the topic to the active Node if present. The
+ * active Node is the last instantiated in temporal order. Instantiation of
+ * multiple Publisher/Subscriber associated with multiple Node is not thread
+ * safe.
+ */
 class YARP_OS_API Nodes : public yarp::os::Contactables
 {
 public:
     Nodes();
     virtual ~Nodes();
 
+    /**
+     * add a Contactable to the Node specified in the contactable name (see
+     * NestedContact.nodeName). If the specified node is in this container, add
+     * the contactable to it, otherwise firstly creates the node and add it to
+     * this container.
+     * @param contactable to be added
+     */
     virtual void add(Contactable& contactable) override;
+
+    /**
+     * remove a Contactable from the Node specified in the contactable's name.
+     * @param contactable to be removed
+     */
     virtual void remove(Contactable& contactable) override;
 
+    /**
+     * query the list of Node to find a Contact with the specified name.
+     * @param name of the Contact (see NestedContact.nestedName)
+     * @param category of the Contact (see NestedContact.category)
+     * @return first matching Contact or an empty one
+     */
     virtual Contact query(const std::string& name,
                           const std::string& category = "") override;
 
-    virtual Contact getParent(const std::string& name);
-
-    virtual Contact getURI(const std::string& name);
-
-    virtual void prepare(const std::string& name);
-
+    /**
+     * update a Node information in this container.
+     * @param contactable to be updated
+     */
     virtual void update(Contactable& contactable);
 
+    /**
+     * getParent get info about node associated with the specified port.
+     * @param name of a registered port (in the format /topic@/node)
+     * @return Contact information about the /node port if found, empty Contact
+     *         otherwise
+     */
+    Contact getParent(const std::string& name);
+
+    /**
+     * getURI queries the Node specified in the name parameter to get Contact
+     * information about the specified port
+     * @param name of a registered port (in the format /topic@/node)
+     * @return Contact information about /topic@/node port or empty Contact
+     */
+    Contact getURI(const std::string& name);
+
+    /**
+     * prepare checks for the existence of the node specified in the name
+     * parameter. If the node doesn't exists, creates it. If the name parameter
+     * is not representing a NestedContact, does nothing.
+     * @param name of a port in the format /topic@/node
+     */
+    void prepare(const std::string& name);
+
+    /**
+     * interrupt delegates interrupt call to all of the Node in this container.
+     */
     void interrupt();
 
+    /**
+     * enable setter for the activity state of the container. If disabling
+     * (parameter is false) clears the container.
+     * @param flag
+     * @return current activity state, after setting
+     */
     bool enable(bool flag);
+
+    /**
+     * clear empties the container
+     */
     void clear();
+
+    /**
+     * setActiveName setter for the currently active node
+     * @param name of the Node to be set as active
+     */
     void setActiveName(const std::string& name);
+
+    /**
+     * addExternalNode adds a Node to this container.
+     * ! Do NOT add two times the same Node.
+     * @param name of the node to be added
+     * @param node to be added
+     */
     void addExternalNode(const std::string& name, Node& node);
+
+    /**
+     * removeExternalNode erase the node from the container.
+     * @param name of the Node to be removed
+     */
     void removeExternalNode(const std::string& name);
+
+    /**
+     * getActiveName getter for the currently active node's name
+     * @return the currently active node's name.
+     */
     std::string getActiveName();
+
+    /**
+     * requireActiveName if there is no active node, creates a temporary one.
+     * @return true
+     */
     bool requireActiveName();
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS

src/libYARP_OS/src/Nodes.cpp

@@ -23,25 +23,19 @@ class yarp::os::Nodes::Private
     ~Private();
 
     void clear();
-
     Node* getNode(const std::string& name, bool create);
-
     void add(Contactable& contactable);
     void update(Contactable& contactable);
     void prepare(const std::string& name);
     void remove(Contactable& contactable);
     Contact query(const std::string& name, const std::string& category);
     void interrupt();
-
     bool enable(bool flag);
-
     Contact getParent(const std::string& name);
     Contact getURI(const std::string& name);
-
     void setActiveName(const std::string& name);
     std::string getActiveName();
     bool requireActiveName();
-
     void addExternalNode(const std::string& name, Node& node);
     void removeExternalNode(const std::string& name);
 
@@ -108,7 +102,7 @@ Node* yarp::os::Nodes::Private::getNode(const std::string& name, bool create)
             nodes_map[nc.getNodeName()] = std::make_pair(node, false);
             node->prepare(nc.getNodeName());
         } else {
-            // The node was not created by some other thread while this
+            // The node was created by some other thread while this
             // thread was waiting on the lock.
             delete node;
             node = it->second.first;