From 538ac4f969b6973f284a703e230fa407d9eca787 Mon Sep 17 00:00:00 2001 From: coderhyme Date: Mon, 3 Aug 2015 22:23:07 +0900 Subject: [PATCH] Update comments for doxygen of RCSRequest and RCSResponse Now these have more appropriate descriptions. Change-Id: Ibd1554ae8a5477b219a8f4e606c1b9d48c03712e Signed-off-by: coderhyme Reviewed-on: https://gerrit.iotivity.org/gerrit/2075 Reviewed-by: Hun-je Yeon Tested-by: jenkins-iotivity Reviewed-by: Uze Choi --- .../resource-encapsulation/include/RCSRequest.h | 12 +- .../resource-encapsulation/include/RCSResponse.h | 277 +++++++++------------ 2 files changed, 119 insertions(+), 170 deletions(-) diff --git a/service/resource-encapsulation/include/RCSRequest.h b/service/resource-encapsulation/include/RCSRequest.h index 2dd32e1..6b531db 100644 --- 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 --- 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 >&&); -- 2.7.4