Update comments for doxygen of RCSRequest and RCSResponse

Now these have more appropriate descriptions.

Change-Id: Ibd1554ae8a5477b219a8f4e606c1b9d48c03712e
Signed-off-by: coderhyme <jhyo.kim@samsung.com>
Reviewed-on: https://gerrit.iotivity.org/gerrit/2075
Reviewed-by: Hun-je Yeon <hunje.yeon@samsung.com>
Tested-by: jenkins-iotivity <jenkins-iotivity@opendaylight.org>
Reviewed-by: Uze Choi <uzchoi@samsung.com>

diff --git a/service/resource-encapsulation/include/RCSRequest.h b/service/resource-encapsulation/include/RCSRequest.h
index 2dd32e1..6b531db 100644 (file)
--- a/service/resource-encapsulation/include/RCSRequest.h
+++ b/service/resource-encapsulation/include/RCSRequest.h
@@ -33,9 +33,8 @@ namespace OIC
     namespace Service
     {
         /**
-        * @class  RCSRequest
-        * @brief   This class describes the resource request.
-        *              It provides API to get the resource URI from the request.
+        * This class describes the request.
+        *
         */
         class RCSRequest
         {
@@ -50,17 +49,12 @@ namespace OIC
                 RCSRequest &operator=(RCSRequest &) = delete;
 
                 /**
-                * API to get the URI from the request.
+                * Returns the URI of the request.
                 *
-                * @return string - uri of resource.
                 */
                 std::string getResourceUri() const;
 
             private:
-                /**
-                 *  resource uri value stored as a string.
-                 *  value set once during request initialization.
-                 */
                 std::string m_resourceUri;
         };
 

diff --git a/service/resource-encapsulation/include/RCSResponse.h b/service/resource-encapsulation/include/RCSResponse.h
index a73b57c..afe6c10 100644 (file)
--- a/service/resource-encapsulation/include/RCSResponse.h
+++ b/service/resource-encapsulation/include/RCSResponse.h
@@ -35,108 +35,79 @@ namespace OIC
 {
     namespace Service
     {
-        //forward declaration of classes
         class RCSResourceAttributes;
 
         class RequestHandler;
         class SetRequestHandler;
 
         /**
-         * @class   RCSGetResponse
-         * @brief   This class provides APIs to create the response for the recieved Get request.
+         * This class provides factory methods to create the response for a received get request.
+         * The response consists of a result code, an error code and result attributes.
+         *
+         * @see RCSResourceObject
          */
         class RCSGetResponse
         {
         public:
             /**
-             * Create RCSGetResponse with default response.
+             * Creates a default RCSGetResponse.
+             * The response will have OC_EH_OK for the result and 200 for the errorCode.
+             * The attributes of RCSResourceObject will be set as the result attributes.
              *
-             * @return RCSGetResponse - instance of RCSGetResponse
              */
             static RCSGetResponse defaultAction();
 
             /**
-             * Create RCSGetResponse using OCEntityHandlerResult value and error code provided.
+             * Creates a RCSGetResponse with a result and error code passed.
+             * The attributes of the RCSResourceObject will be set as the result attributes.
              *
-             * @param result -OCEntityHandlerResult
+             * @param result The response result.
+             * @param errorCode The error code to set in response.
              *
-             * @param errorCode - error code to set in response
-             *
-             * @return RCSGetResponse - instance of RCSGetResponse
-             *
-             * NOTE : OCEntityHandlerResult is defined in octypes.h
              */
-            static RCSGetResponse create(const OCEntityHandlerResult &result, int errorCode);
+            static RCSGetResponse create(const OCEntityHandlerResult& result, int errorCode);
 
             /**
-             * Create RCSGetResponse using resource attributes.
-             *
-             * @param attrs -RCSResourceAttributes to set
+             * Creates a RCSGetResponse with custom attributes.
+             * This sends the passed attributes as the result attributes
+             * instead of the one the RCSResourceObject holds.
              *
-             * @return RCSGetResponse - instance of RCSGetResponse
+             * @param attrs The attributes to set.
              *
              * @see RCSResourceAttributes
              *
-             * NOTE : RCSResourceAttributes is defined in RCSResourceAttributes.h
              */
-            static RCSGetResponse create(const RCSResourceAttributes &attrs);
-            /**
-             * Create RCSGetResponse using RCSResourceAttributes, OCEntityHandlerResult and error code.
-             *
-             * @param attrs - RCSResourceAttributes to set
-             *
-             * @param result - OCEntityHandlerResult
-             *
-             * @param errorCode - error code for response
-             *
-             * @return RCSGetResponse - instance of RCSGetResponse
-             *
-             * @see RCSResourceAttributes
-             *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h.
-             *           RCSResourceAttributes is defined in RCSResourceAttributes.h.
-             */
-            static RCSGetResponse create(const RCSResourceAttributes &attrs,
-                    const OCEntityHandlerResult &result, int errorCode);
+            static RCSGetResponse create(const RCSResourceAttributes& attrs);
 
             /**
-             * Create RCSGetResponse using RCSResourceAttributes value.
-             *
-             * @param attrs - RCSResourceAttributes to set
-             *
-             * @return RCSGetResponse - instance of RCSGetResponse
-             *
-             * @see RCSResourceAttributes
-             *
-             *NOTE : RCSResourceAttributes is defined in RCSResourceAttributes.h.
+             * @override
              */
-            static RCSGetResponse create(RCSResourceAttributes &&attrs);
+            static RCSGetResponse create(RCSResourceAttributes&& attrs);
+
             /**
-             * Create RCSGetResponse using RCSResourceAttributes value.
+             * Creates a RCSGetResponse with a result and error code passed.
+             * This sends the passed attributes as the result attributes
+             * instead of the one the RCSResourceObject holds.
              *
-             * @param attrs - RCSResourceAttributes to set
-             *
-             * @param result - OCEntityHandlerResult
-             *
-             * @param errorCode - error code for response
-             *
-             * @return RCSGetResponse - instance of RCSGetResponse
+             * @param attrs The attributes to set.
+             * @param result The response result.
+             * @param errorCode The error code for response.
              *
              * @see RCSResourceAttributes
              *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h.
-             *           RCSResourceAttributes is defined in RCSResourceAttributes.h.
              */
-            static RCSGetResponse create(RCSResourceAttributes &&attrs,
-                    const OCEntityHandlerResult &result, int errorCode);
+            static RCSGetResponse create(const RCSResourceAttributes& attrs,
+                    const OCEntityHandlerResult& result, int errorCode);
 
             /**
-             * Get the request handler.
-             *
-             * @return RequestHandler - RequestHandler pointer.
-             *
+             * @override
              */
+            static RCSGetResponse create(RCSResourceAttributes&& attrs,
+                    const OCEntityHandlerResult& result, int errorCode);
+
+            //! @cond
             RequestHandler* getHandler() const;
+            //! @endcond
 
         private:
             RCSGetResponse(std::shared_ptr< RequestHandler >&&);
@@ -146,176 +117,160 @@ namespace OIC
         };
 
         /**
-         * @class   RCSSetResponse
-         * @brief   This class provides API to create a response for received Set request.
+         * This class provides factory methods to create the response for a received set request.
+         * The response consists of a result code, an error code and result attributes.
+         *
+         * AcceptanceMethod provides ways how to handle attributes from a request.
+         *
+         * @see RCSResourceObject
          */
         class RCSSetResponse
         {
         public:
             /**
-             * AcceptanceMethod enum provides values for different acceptance method policy to be
-             * used in setting response.
+             * Options for handling a set request.
+             *
+             * This overrides SetRequestHandlerPolicy.
+             *
+             * @see SetRequestHandlerPolicy
+             *
              */
             enum class AcceptanceMethod
             {
-                DEFAULT, ACCEPT, IGNORE
+                /**
+                 * Follow SetRequestHandlerPolicy of the RCSResourceObject.
+                 */
+                DEFAULT,
+
+                /**
+                 * Accept the request attributes even if there is an unknown key or mismatched type.
+                 */
+                ACCEPT,
+
+                /**
+                 * Ignore the request attributes.
+                 */
+                IGNORE
             };
 
             /**
-             * Create default RCSSetResponse with default response.
+             * Creates a default RCSSetResponse that has AcceptanceMethod::DEFAULT.
+             * The response will have OC_EH_OK for the result and 200 for the errorCode.
+             * The attributes of RCSResourceObject will be set as the result attributes.
              *
-             * @return RCSSetResponse - instance of RCSSetResponse
              */
             static RCSSetResponse defaultAction();
 
             /**
-             * Internally it invokes the defaultAction() API.
-             *  It sets the AcceptanceMethod as ACCEPT.
-             *
-             * @return RCSSetResponse - instance of RCSSetResponse
+             * Creates a default RCSSetResponse that has AcceptanceMethod::ACCEPT.
+             * The response will have OC_EH_OK for the result and 200 for the errorCode.
+             * The attributes of RCSResourceObject will be set as the result attributes.
              *
-             * @see AcceptanceMethod
              */
             static RCSSetResponse accept();
+
             /**
-             * Internally it invokes the create(const OCEntityHandlerResult&, int errorCode) API.
-             * It sets the AcceptanceMethod as ACCEPT.
+             * Creates a RCSSetResponse that has AcceptanceMethod::ACCEPT
+             * with a result and error code passed.
+             * The attributes of the RCSResourceObject will be set as the result attributes.
              *
-             * @param result - OCEntityHandlerResult value.
-             *
-             * @param errorCode - error code for the response
-             *
-             * @return RCSSetResponse - instance of RCSSetResponse
-             *
-             * @see AcceptanceMethod
+             * @param result The response result.
+             * @param errorCode The error code to set in response.
              *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h
              */
-            static RCSSetResponse accept(const OCEntityHandlerResult &result, int errorCode);
+            static RCSSetResponse accept(const OCEntityHandlerResult& result, int errorCode);
 
             /**
-             * Internally it invokes the defaultAction() API.
-             * It sets the AcceptanceMethod as IGNORE.
+             * Creates a default RCSSetResponse that has AcceptanceMethod::IGNORE.
+             * The response will have OC_EH_OK for the result and 200 for the errorCode.
+             * The attributes of RCSResourceObject will be set as the result attributes.
              *
-             * @return RCSSetResponse - instance of RCSSetResponse.
-             *
-             *  @see AcceptanceMethod
              */
             static RCSSetResponse ignore();
-            /**
-             * Internaly it invokes the create(const OCEntityHandlerResult&, int errorCode) API.
-             * It sets the AcceptanceMethod as IGNORE.
-             *
-             * @param result - OCEntityHandlerResult value.
-             *
-             * @param errorCode - error code for the response.
-             *
-             * @return RCSSetResponse - instance of RCSSetResponse.
-             *
-             *  @see AcceptanceMethod
-             *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h
-             */
-            static RCSSetResponse ignore(const OCEntityHandlerResult &result, int errorCode);
 
             /**
-             * Create RCSSetResponse with OCEntityHandlerResult and errorCode.
-             *
-             * @param result - OCEntityHandlerResult value
-             *
-             * @param errorCode - error code for the response
+             * Creates a RCSSetResponse that has AcceptanceMethod::IGNORE
+             * with a result and error code passed.
+             * The attributes of the RCSResourceObject will be set as the result attributes.
              *
-             * @return RCSSetResponse - instance of RCSSetResponse
+             * @param result The response result.
+             * @param errorCode The error code to set in response.
              *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h
              */
-            static RCSSetResponse create(const OCEntityHandlerResult &result, int errorCode);
+            static RCSSetResponse ignore(const OCEntityHandlerResult& result, int errorCode);
 
             /**
-             * Create RCSSetResponse with RCSResourceAttributes.
+             * Creates a RCSSetResponse that has AcceptanceMethod::DEFAULT
+             * with a result and error code passed.
+             * The attributes of the RCSResourceObject will be set as the result attributes.
              *
-             * @param attrs - RCSResourceAttributes to set
+             * @param result The response result.
+             * @param errorCode The error code to set in response.
              *
-             * @return RCSSetResponse - instance of RCSSetResponse
-             *
-             * @see RCSResourceAttributes
              */
-            static RCSSetResponse create(const RCSResourceAttributes &attrs);
+            static RCSSetResponse create(const OCEntityHandlerResult& result, int errorCode);
+
             /**
-             * Create RCSSetResponse with RCSResourceAttributes, OCEntityHandlerResult and errorCode.
-             *
-             * @param attrs - RCSResourceAttributes to set.
-             *
-             * @param result - OCEntityHandlerResult value
+             * Creates a RCSSetResponse that has AcceptanceMethod::DEFAULT with custom attributes.
+             * This sends the passed attributes as the result attributes
+             * instead of the one the RCSResourceObject holds.
              *
-             * @param errorCode - error code for the response
-             *
-             * @return RCSSetResponse - instance of RCSSetResponse
+             * @param attrs The attributes to set.
              *
              * @see RCSResourceAttributes
              *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h.
              */
-            static RCSSetResponse create(const RCSResourceAttributes &attrs,
-                    const OCEntityHandlerResult &result, int errorCode);
+            static RCSSetResponse create(const RCSResourceAttributes& attrs);
 
             /**
-             * Create RCSSetResponse with RCSResourceAttributes.
-             *
-             * @param attrs - RCSResourceAttributes value to set
-             *
-             * @return RCSSetResponse - instance of RCSSetResponse
-             *
-             * @see RCSResourceAttributes
+             * @override
              */
             static RCSSetResponse create(RCSResourceAttributes &&attrs);
+
             /**
-             * Create RCSSetResponse with RCSResourceAttributes, OCEntityHandlerResult and errorCode.
-             *
-             * @param attrs - RCSResourceAttributes value to set
-             *
-             * @param result - OCEntityHandlerResult value
+             * Creates a RCSSetResponse with a result and error code passed.
+             * This sends the passed attributes as the result attributes
+             * instead of the one the RCSResourceObject holds.
              *
-             * @param errorCode - error code for the response
-             *
-             * @return RCSSetResponse - instance of RCSSetResponse
+             * @param attrs The attributes to set.
+             * @param result The response result.
+             * @param errorCode The error code for response.
              *
              * @see RCSResourceAttributes
              *
-             *NOTE : OCEntityHandlerResult is defined in octypes.h.
              */
-            static RCSSetResponse create(RCSResourceAttributes &&attrs,
-                    const OCEntityHandlerResult &result, int errorCode);
+            static RCSSetResponse create(const RCSResourceAttributes& attrs,
+                    const OCEntityHandlerResult& result, int errorCode);
+
 
             /**
-             * API to get the set request handler.
-             *
-             * @return SetRequestHandler - pointer to SetRequestHandler.
-             *
+             * @override
              */
+            static RCSSetResponse create(RCSResourceAttributes &&attrs,
+                    const OCEntityHandlerResult &result, int errorCode);
+
+
+            //! @cond/
             SetRequestHandler* getHandler() const;
+            //! @endcond
 
             /**
-             * API to get the acceptance method of the  RCSSetResponse.
-             *
-             * @return AcceptanceMethod - acceptance methods enum value.
-             *
-             * @see AcceptanceMethod
+             * Returns the acceptance method.
              *
              */
             AcceptanceMethod getAcceptanceMethod() const;
 
             /**
-             * API to get the acceptance method of the  RCSSetResponse.
+             * Sets the acceptance method for the RCSSetResponse.
              *
              * @param method - AcceptanceMethod value to set
              *
-             * @return RCSSetResponse - reference to RCSSetResponse
+             * @return The reference to this RCSSetResponse
              *
              * @see AcceptanceMethod
              *
              */
-            RCSSetResponse &setAcceptanceMethod(AcceptanceMethod method);
+            RCSSetResponse& setAcceptanceMethod(AcceptanceMethod method);
 
         private:
             RCSSetResponse(std::shared_ptr< SetRequestHandler >&&);