From 0fc70929eac9bad23233ff1eb6791696968861a0 Mon Sep 17 00:00:00 2001 From: Damiano Enerli Date: Wed, 11 Jul 2018 16:55:39 +0200 Subject: [PATCH] add documentation to Node, Nodes, Contactables --- src/libYARP_OS/include/yarp/os/Contactables.h | 33 +++++- src/libYARP_OS/include/yarp/os/Node.h | 62 ++++++++-- src/libYARP_OS/include/yarp/os/Nodes.h | 107 ++++++++++++++++-- src/libYARP_OS/src/Nodes.cpp | 8 +- 4 files changed, 180 insertions(+), 30 deletions(-) diff --git a/src/libYARP_OS/include/yarp/os/Contactables.h b/src/libYARP_OS/include/yarp/os/Contactables.h index 089a5bc7073..f117272ae38 100644 --- a/src/libYARP_OS/include/yarp/os/Contactables.h +++ b/src/libYARP_OS/include/yarp/os/Contactables.h @@ -12,20 +12,43 @@ #include 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 diff --git a/src/libYARP_OS/include/yarp/os/Node.h b/src/libYARP_OS/include/yarp/os/Node.h index dd8bb18adb3..f948c18c25f 100644 --- a/src/libYARP_OS/include/yarp/os/Node.h +++ b/src/libYARP_OS/include/yarp/os/Node.h @@ -13,34 +13,76 @@ #include 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 diff --git a/src/libYARP_OS/include/yarp/os/Nodes.h b/src/libYARP_OS/include/yarp/os/Nodes.h index d9810247d95..b2ad1769245 100644 --- a/src/libYARP_OS/include/yarp/os/Nodes.h +++ b/src/libYARP_OS/include/yarp/os/Nodes.h @@ -11,39 +11,130 @@ #include +// 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 diff --git a/src/libYARP_OS/src/Nodes.cpp b/src/libYARP_OS/src/Nodes.cpp index b3f3bf17b8f..bc565edbc58 100644 --- a/src/libYARP_OS/src/Nodes.cpp +++ b/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;