String templates modified with doxygen comments.

showna · Dec 17, 2013 · 93b8ee9 · 93b8ee9
1 parent b9ecfe7
commit 93b8ee9
Show file tree

Hide file tree

Showing 18 changed files with 207 additions and 31 deletions.
diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/DDSProtocolHeader.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/DDSProtocolHeader.stg
@@ -36,14 +36,29 @@ namespace eprosima
         {
             namespace dds
             {
+                /*!
+                 * @brief This class is responsible for serializing and deserializing the requests and responses of this application.
+                 *  It uses DDS.
+                 */
                 class RPCDDSUSERDllExport  $ctx.filename$Protocol : public eprosima::rpcdds::protocol::$ctx.filename$Protocol
                 {
                     public:
 
+                       /*!
+                        * @brief Default constructor
+                        */
                         $ctx.filename$Protocol();
 
+                       /*!
+                        * @brief Default destructor
+                        */
                         virtual ~$ctx.filename$Protocol();
 
+                       /*!
+                        * @brief This method sets the transport for the communications.
+                        * @param transport Transport to use
+                        * @return True if the assignment is successful, false otherwise
+                        */
                         virtual bool setTransport(eprosima::rpcdds::transport::Transport &transport);
 
                         bool activateInterface(const char* interfaceName);
@@ -100,10 +115,16 @@ exception(ctx, exception) ::= <<>>
 
 operation(ctx, operation, param_list) ::= <<
 $if(ctx.client)$
+/*!
+ * @brief This method implements the proxy part of the protocol for the operation $operation.name$
+ */
 $paramRetType(operation.rettype)$ $operation.parent.formatedScopedname$_$operation.name$($paramDeclsOnlyOutByRef(params=operation.parameters)$);
 $endif$
 
 $if(ctx.server)$
+/*!
+ * @brief This method implements the server part of the protocol for the operation $operation.name$
+ */
 static void $operation.parent.formatedScopedname$_$operation.name$_serve(eprosima::rpcdds::protocol::Protocol &protocol,
     void *data , eprosima::rpcdds::transport::Endpoint *endpoint);
 $endif$

diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ProtocolHeader.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ProtocolHeader.stg
@@ -20,16 +20,28 @@ namespace eprosima
     {
         namespace protocol
         {
+            /*!
+             * @brief Protocol base class for the specific application
+             */
             class RPCDDSUSERDllExport $ctx.filename$Protocol : public Protocol
             {
                 public:
 
+                   /*!
+                    * @brief This method sets the transport for the communications. It has to be implemented by the children classes.
+                    * @param transport Transport to use.
+                    * @return True if the assignment is successful, false otherwise
+                    */
                     virtual bool setTransport(eprosima::rpcdds::transport::Transport &transport) = 0;
 
                     virtual bool activateInterface(const char* interfaceName) = 0;
 
                     $if(ctx.server)$
                     $ctx.interfaces : { interface |
+                   /*!
+                    * @brief This method links a specific servant with the protocol.
+                    * @param impl Servant implementation.
+                    */
                     void link$interface.formatedScopedname$Impl($interface.scopedname$ServerImpl &impl)
                     {
                         _$interface.formatedScopedname$_impl = &impl;
@@ -87,6 +99,10 @@ exception(ctx, exception) ::= <<>>
 
 operation(ctx, operation, param_list) ::= <<
 $if(ctx.client)$
+/*!
+ * @brief This method implements the proxy part of the protocol for the operation $operation.name$
+ *        It has to be implemented by the child classes.
+ */
 virtual $paramRetType(operation.rettype)$ $operation.parent.formatedScopedname$_$operation.name$($paramDeclsOnlyOutByRef(params=operation.parameters)$) = 0;
 $endif$
 

diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ProxyHeader.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ProxyHeader.stg
@@ -56,13 +56,10 @@ class RPCDDSUSERDllExport $interface.name$Proxy : public eprosima::rpcdds::proxy
         /*!
          * @brief This constructor sets the transport that will be used by the server's proxy.
          *
-         * @param remoteServiceName The service's name that the remote server uses and the proxy will use to connect with it.
          * @param transport The network transport that server's proxy has to use.
          *        This transport's object is not deleted by this class in its destructor. Cannot be NULL.
          * @param protocol The protocol used to send the information over the transport.
          *        This protocol's object is not deleted by this class in its destructor. Cannot be NULL.
-         * @param timeout Timeout used in each call to remotely procedures.
-         *        If the call exceeds the time, a eprosima::rpcdds::exception::ServerTimeoutException is thrown.
          * @exception eprosima::rpcdds::exception::InitializeException This exception is thrown when the initialization was wrong.
          */
         $interface.name$Proxy(eprosima::rpcdds::transport::ProxyTransport &transport,
@@ -85,6 +82,7 @@ $exports; separator="\n"$
 exception(ctx, exception) ::= <<>>
 
 operation(ctx, operation, param_list) ::= <<
+//! @brief Proxy method for the operation $operation.name$
 $paramRetType(operation.rettype)$ $operation.name$($paramDeclsOnlyOutByRef(params=operation.parameters)$);
 
 >>
@@ -135,6 +133,7 @@ $endif$
 
 functionAsyncHeader(operation) ::= <<
 $if(!operation.oneway)$
+//! @brief Proxy asynchronous method for the operation $operation.name$
 void $operation.name$_async($operation.parent.name$_$operation.name$CallbackHandler &obj$paramDeclsByValue(params=operation.inputparam, separatorInicial=", ")$);
 
 $endif$

diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/RESTProtocolHeader.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/RESTProtocolHeader.stg
@@ -30,18 +30,44 @@ namespace eprosima
                 // TODO Quitar
                 class RESTSerializer;
 
+                /*!
+                 * @brief This class is responsible for serializing and deserializing the requests and responses of this application.
+                 *  It uses a RESTful protocol.
+                 */
                 class RPCDDSUSERDllExport $ctx.filename$Protocol : public eprosima::rpcdds::protocol::$ctx.filename$Protocol
                 {
                     public:
 
+                       /*!
+                        * @brief Default constructor
+                        */
                         $ctx.filename$Protocol();
 
+                       /*!
+                        * @brief Default destructor
+                        */
                         virtual ~$ctx.filename$Protocol();
 
+                       /*!
+                        * @brief This method sets the transport for the communications.
+                        *        It must be an HTTP transport.
+                        * @param transport Transport to use
+                        * @return True if the assignment is successful, false otherwise
+                        */
                         bool setTransport(eprosima::rpcdds::transport::Transport &transport);
 
+                       /*!
+                        * @brief This method does not apply to this class
+                        */
                         bool activateInterface(const char* interfaceName);
 
+                       /*!
+                        * @brief This callback receives the requests and calls the specific protocol to process them
+                        * @param protocol Protocol that must process the request
+                        * @param data Received data
+                        * @param dataLength received data length
+                        * @param endpoint Proxy endpoint where the request came from
+                        */
                         static void worker(Protocol& protocol, void *&data, size_t dataLength, eprosima::rpcdds::transport::Endpoint *endpoint);
 
                         $definitions; separator="\n"$
@@ -87,15 +113,27 @@ $exports; separator="\n"$
 exception(ctx, exception) ::= <<>>
 
 operation(ctx, operation, param_list) ::= <<
+/*!
+ * @brief This method implements the server part of the protocol for the operation $operation.name$
+ */
 eprosima::rpcdds::transport::HttpMessage deserialize_$operation.parent.name$_$operation.name$(RESTSerializer &restSerializer, eprosima::rpcdds::transport::HttpMessage &httpMessage);
 
 $if(operation.parent.pathHasBrackets)$
+/*!
+ * @brief This method deserializes the path and fills an structure that will contain every embedded parameter in the path
+ */
 void deserializePath_$operation.name$(RESTSerializer &restSerializer, $paramDeclsByRef(params=first(operation.parameters))$);
 $endif$
 
 $if(operation.parent.pathHasBrackets)$
+/*!
+ * @brief This method fills the path with the content of a structure containing every embedded parameter
+ */
 std::string expandPath_$operation.name$(std::string &&path, $paramRetType(typecode=first(operation.parameters).typecode)$ $first(operation.parameters).name$);
 $endif$
+/*!
+ * @brief This method implements the proxy part of the protocol for the operation $operation.name$
+ */
 $paramRetType(operation.rettype)$ $operation.parent.formatedScopedname$_$operation.name$($paramDeclsOnlyOutByRef(params=operation.parameters)$);
 
 >>

diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ServerHeader.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ServerHeader.stg
@@ -51,13 +51,13 @@ class RPCDDSUSERDllExport $interface.name$Server : public eprosima::rpcdds::serv
         /**
          * \brief This constructor sets the transport that will be used by the server.
          *
-         * \param serviceName The service's name that proxies will use to connect with the server.
          * \param strategy Strategy used by server to work with new requests.
          *        This class doesn't delete this object in its destructor. Cannot be NULL.
-         * \param transport The network transport that server has to use.
-         *        This transport's object is not deleted by this class in its destrcutor. Cannot be NULL.
-         * \param servant Servant that server will use to invoke user's functions.
-         * \param domainId The DDS domain that DDS will use to work. Default value: 0.
+         * \param transport The network transport that the server has to use.
+         *        This transport's object is not deleted by this class in its destructor. Cannot be NULL.
+         * \param protocol Generated protocol that the server has to use.
+         *        This class has the information to process requests and build responses for this application environment. 
+         * \param servant Servant that the server will use to invoke user's functions.
          * \exception eProsima::RPCDDS::InitializeException This exception is thrown when the initialization was wrong.
          */
         $interface.name$Server(eprosima::rpcdds::strategy::ServerStrategy &strategy, eprosima::rpcdds::transport::ServerTransport &transport,

diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ServerImplHeader.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ServerImplHeader.stg
@@ -55,6 +55,7 @@ $exports; separator="\n"$
 exception(ctx, exception) ::= <<>>
 
 operation(ctx, operation, param_list) ::= <<
+/// \brief Skeleton of the operation $operation.name$
 virtual $paramRetType(operation.rettype)$ $operation.name$($paramDeclsOnlyOutByRef(params=operation.parameters)$) = 0;
 
 >>

diff --git a/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ServerImplHeaderExample.stg b/rpcddsgen/src/com/eprosima/rpcdds/idl/templates/ServerImplHeaderExample.stg
@@ -51,6 +51,7 @@ $exports; separator="\n"$
 exception(ctx, exception) ::= <<>>
 
 operation(ctx, operation, param_list) ::= <<
+//! @brief Implementation of the remote procedure $operation.name$
 $paramRetType(operation.rettype)$ $operation.name$($paramDeclsOnlyOutByRef(params=operation.parameters)$);
 
 >>

diff --git a/utils/doxygen/doxygenfiles/mainpage.dox b/utils/doxygen/doxygenfiles/mainpage.dox
@@ -39,23 +39,23 @@
 
  /*!
  * @defgroup RPCDDSAPIREFERENCE RPCDDS API Reference
- * @brief RPCDDS internal API groped in modules.
+ * @brief RPCDDS internal API grouped in modules.
  */
 
  /*!
  * @defgroup PROXYMODULE Client Module
  * @ingroup RPCDDSAPIREFERENCE
  * @brief This group contains related API to create a client application.
  * This API is used by the tool \e rpcddsgen to generate custom code based in a defined interface.
- * That interface and its remote procedure have to be defined in IDL language.
+ * That interface and its remote procedures have to be defined in IDL or WADL.
  */
 
  /*!
  * @defgroup SERVERMODULE Server Module
  * @ingroup RPCDDSAPIREFERENCE
  * @brief This group contains related API to create a server application.
  * Except the custom server's strategies, this API is used by the tool \e rpcddsgen to generate custom code based in a defined interface.
- * That interface and its remote procedure have to be defined in IDL language.
+ * That interface and its remote procedure have to be defined in IDL or WADL.
  */
 
  /*!
@@ -79,6 +79,11 @@
  */
 
  /*!
- * @defgroup FOOEXAMPLE Generated API example
- * @brief This group contains the generated API by the tool \e rpcddsgen \e for an example of interface named FooInterface.
+ * @defgroup FOODDSEXAMPLE Generated API example for DDS
+ * @brief This group contains the generated API by the tool \e rpcddsgen \e for a DDS example of an interface named FooInterface.
+ */
+
+  /*!
+ * @defgroup FOORESTEXAMPLE Generated API example for RESTful
+ * @brief This group contains the generated API by the tool \e rpcddsgen \e for a RESTful example of a resource named FooInterface.
  */
diff --git a/utils/doxygen/foo_dds/FooInterfaceDDSProtocol.h b/utils/doxygen/foo_dds/FooInterfaceDDSProtocol.h
@@ -35,19 +35,41 @@ namespace eprosima
         {
             namespace dds
             {
+                /*!
+                 * @brief This class is responsible for serializing and deserializing the requests and responses of this application.
+                 *  It uses DDS.
+				 * @ingroup FOODDSEXAMPLE
+                 */
                 class RPCDDSUSERDllExport  FooInterfaceProtocol : public eprosima::rpcdds::protocol::FooInterfaceProtocol
                 {
                     public:
 
+                       /*!
+                        * @brief Default constructor
+                        */
                         FooInterfaceProtocol();
 
+                       /*!
+                        * @brief Default destructor
+                        */
                         virtual ~FooInterfaceProtocol();
 
+                       /*!
+                        * @brief This method sets the transport for the communications.
+                        * @param transport Transport to use
+                        * @return True if the assignment is successful, false otherwise
+                        */
                         virtual bool setTransport(eprosima::rpcdds::transport::Transport &transport);
 
                         bool activateInterface(const char* interfaceName);
 
+                        /*!
+                         * @brief This method implements the proxy part of the protocol for the operation FooProcedure
+                         */
                         void FooInterface_FooProcedure();
+                        /*!
+                         * @brief This method implements the server part of the protocol for the operation FooProcedure
+                         */
                         static void FooInterface_FooProcedure_serve(eprosima::rpcdds::protocol::Protocol &protocol,
                             void *data , eprosima::rpcdds::transport::Endpoint *endpoint);
 

diff --git a/utils/doxygen/foo_dds/FooInterfaceProtocol.h b/utils/doxygen/foo_dds/FooInterfaceProtocol.h
@@ -26,20 +26,37 @@ namespace eprosima
     {
         namespace protocol
         {
+            /*!
+             * @brief Protocol base class for the specific application
+			 * @ingroup FOODDSEXAMPLE
+             */
             class RPCDDSUSERDllExport FooInterfaceProtocol : public Protocol
             {
                 public:
 
+                   /*!
+                    * @brief This method sets the transport for the communications. It has to be implemented by the children classes.
+                    * @param transport Transport to use.
+                    * @return True if the assignment is successful, false otherwise
+                    */
                     virtual bool setTransport(eprosima::rpcdds::transport::Transport &transport) = 0;
 
                     virtual bool activateInterface(const char* interfaceName) = 0;
 
+                                       /*!
+                                        * @brief This method links a specific servant with the protocol.
+                                        * @param impl Servant implementation.
+                                        */
                                         void linkFooInterfaceImpl(FooInterfaceServerImpl &impl)
                                         {
                                             _FooInterface_impl = &impl;
                                         }
 
 
+                    /*!
+                     * @brief This method implements the proxy part of the protocol for the operation FooProcedure
+                     *        It has to be implemented by the child classes.
+                     */
                     virtual void FooInterface_FooProcedure() = 0;
 
 

diff --git a/utils/doxygen/foo_dds/FooInterfaceProxy.h b/utils/doxygen/foo_dds/FooInterfaceProxy.h
@@ -35,6 +35,7 @@ namespace eprosima
 /*!
  * @brief This abstract class defines the callbacks that RPCDDS will call in an asynchronous call.
  *        These callback has to be implemented in a derived class.
+ * @ingroup FOODDSEXAMPLE
  */
 class FooInterface_FooProcedureCallbackHandler
 {
@@ -64,13 +65,10 @@ class RPCDDSUSERDllExport FooInterfaceProxy : public eprosima::rpcdds::proxy::Pr
         /*!
          * @brief This constructor sets the transport that will be used by the server's proxy.
          *
-         * @param remoteServiceName The service's name that the remote server uses and the proxy will use to connect with it.
          * @param transport The network transport that server's proxy has to use.
          *        This transport's object is not deleted by this class in its destructor. Cannot be NULL.
          * @param protocol The protocol used to send the information over the transport.
          *        This protocol's object is not deleted by this class in its destructor. Cannot be NULL.
-         * @param timeout Timeout used in each call to remotely procedures.
-         *        If the call exceeds the time, a eprosima::rpcdds::exception::ServerTimeoutException is thrown.
          * @exception eprosima::rpcdds::exception::InitializeException This exception is thrown when the initialization was wrong.
          */
         FooInterfaceProxy(eprosima::rpcdds::transport::ProxyTransport &transport,
@@ -79,10 +77,12 @@ class RPCDDSUSERDllExport FooInterfaceProxy : public eprosima::rpcdds::proxy::Pr
         //! @brief The default destructor.
         virtual ~FooInterfaceProxy();
 
+        //! @brief Proxy method for the operation FooProcedure
         void FooProcedure();
 
 
-        //void FooProcedure_async(FooInterface_FooProcedureCallbackHandler &obj);
+        ////! @brief Proxy asynchronous method for the operation FooProcedure
+        void FooProcedure_async(FooInterface_FooProcedureCallbackHandler &obj);
 
 };