From 09c455b96b42fd2fd3eaf45847b15af444de0220 Mon Sep 17 00:00:00 2001 From: George Nash Date: Fri, 15 Jan 2016 09:22:42 -0800 Subject: [PATCH] Clean up documentation warnings reported by doxygen Most of the documentation cleanup is due to overloaded member functions. The @overload tag was used to remove the warnings. All of the parameteres are documented for both functions with the @see tag added for each overloaded function. This is a balance between not repeating documentation yet still keeping the output clean. To have clean output some repetition is required. The @override tag was removed from the move constructors since @override is not a keyword understood by doxygen. The best I could tell the documentation should have been the same for the move constructors as it was for the the copy constructors. note: @overload automatically adds "This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts." to the output documentation. Change-Id: Id167dc8d38bcca65d91a8bd3d6e43f9ca291aa79 Signed-off-by: George Nash Reviewed-on: https://gerrit.iotivity.org/gerrit/4815 Tested-by: jenkins-iotivity Reviewed-by: Jon A. Cruz --- resource/include/OCPlatform.h | 292 +++++++++++++-------- resource/include/OCProvisioningManager.h | 11 +- .../resource-encapsulation/include/RCSException.h | 11 +- .../resource-encapsulation/include/RCSResponse.h | 74 +++++- 4 files changed, 266 insertions(+), 122 deletions(-) diff --git a/resource/include/OCPlatform.h b/resource/include/OCPlatform.h index 71c1dfd..fefeb35 100644 --- a/resource/include/OCPlatform.h +++ b/resource/include/OCPlatform.h @@ -50,40 +50,57 @@ namespace OC typedef OCDoHandle OCPresenceHandle; /** - * API for notifying base that resource's attributes have changed. - * - * @param OCResourceHandle resource handle of the resource - * @param QualityOfService the quality of communication - * - * @return Returns ::OC_STACK_OK if success. - * @note This API is for server side only. - * @note OCResourceHandle is defined in ocstack.h - * @note OCStackResult is defined in ocstack.h. - * @see notifyAllObservers(OCResourceHandle) - * @see notifyAllObservers(OCResourceHandle, QualityOfService) - */ + * API for notifying base that resource's attributes have changed. + * + * @param resourceHandle resource handle of the resource + * + * @return Returns ::OC_STACK_OK if success. + * @note This API is for server side only. + * @note OCResourceHandle is defined in ocstack.h + * @note OCStackResult is defined in ocstack.h. + * @see notifyAllObservers(OCResourceHandle, QualityOfService) + */ OCStackResult notifyAllObservers(OCResourceHandle resourceHandle); + + /** + * @overload + * + * @param resourceHandle resource handle of the resource + * @param QoS the quality of communication + * @see notifyAllObservers(OCResourceHandle) + */ OCStackResult notifyAllObservers(OCResourceHandle resourceHandle, QualityOfService QoS); /** - * API for notifying only specific clients that resource's attributes have changed. - * - * @param OCResourceHandle resource handle of the resource - * @param observationIds std vector of observationIds. These set of ids are ones which - * which will be notified upon resource change. - * @param responsePtr OCResourceResponse pointer used by app to fill the response for this - * resource change. - * @param QualityOfService the quality of communication - * - * @return Returns ::OC_STACK_OK if success. - * @note This API is for server side only. - * @note OCResourceHandle is defined in ocstack.h. - * @note OCStackResult is defined in ocstack.h. - */ + * API for notifying only specific clients that resource's attributes have changed. + * + * @param resourceHandle resource handle of the resource + * @param observationIds std vector of observationIds. These set of ids are ones which + * which will be notified upon resource change. + * @param responsePtr OCResourceResponse pointer used by app to fill the response for this + * resource change. + * + * @return Returns ::OC_STACK_OK if success. + * @note This API is for server side only. + * @note OCResourceHandle is defined in ocstack.h. + * @note OCStackResult is defined in ocstack.h. + * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr, QualityOfService) + */ OCStackResult notifyListOfObservers( OCResourceHandle resourceHandle, ObservationIds& observationIds, const std::shared_ptr responsePtr); + /** + * @overload + * + * @param resourceHandle resource handle of the resource + * @param observationIds std vector of observationIds. These set of ids are ones which + * which will be notified upon resource change. + * @param responsePtr OCResourceResponse pointer used by app to fill the response for this + * resource change. + * @param QoS the quality of communication + * @see notifyListOfObservers(OCResourceHandle, ObservationIds&, const std::shared_ptr) + */ OCStackResult notifyListOfObservers( OCResourceHandle resourceHandle, ObservationIds& observationIds, @@ -91,78 +108,126 @@ namespace OC QualityOfService QoS); /** - * API for Service and Resource Discovery. - * @note This API applies to client side only. - * - * @param host Host IP Address of a service to direct resource discovery query. If null or - * empty, performs multicast resource discovery query - * @param resourceURI name of the resource. If null or empty, performs search for all - * resource names - * @param connectivityType ::OCConnectivityType type of connectivity indicating the - * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL - * @param resourceHandler Handles callbacks, success states and failure states. - * - * Four modes of discovery defined as follows: - * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource - * discovery. - * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular - * resource(s) from ALL services. - * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service. - * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular - * resource(s) - * from a particular service. - * @param QualityOfService the quality of communication - * - * @return Returns ::OC_STACK_OK if success. - * @note First parameter 'host' currently represents an IP address. This will change in - * future and will refer to endpoint interface so that we can refer to other transports such - * as BTH etc. - * @note OCStackResult is defined in ocstack.h. - */ + * API for Service and Resource Discovery. + * @note This API applies to client side only. + * + * @param host Host IP Address of a service to direct resource discovery query. If null or + * empty, performs multicast resource discovery query + * @param resourceURI name of the resource. If null or empty, performs search for all + * resource names + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param resourceHandler Handles callbacks, success states and failure states. + * + * Four modes of discovery defined as follows: + * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource + * discovery. + * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) from ALL services. + * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service. + * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) + * from a particular service. + * + * @return Returns ::OC_STACK_OK if success. + * @note First parameter 'host' currently represents an IP address. This will change in + * future and will refer to endpoint interface so that we can refer to other transports such + * as BTH etc. + * @note OCStackResult is defined in ocstack.h. + * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback, QualityOfService) + */ OCStackResult findResource(const std::string& host, const std::string& resourceURI, OCConnectivityType connectivityType, FindCallback resourceHandler); + /** + * @overload + * + * @param host Host IP Address of a service to direct resource discovery query. If null or + * empty, performs multicast resource discovery query + * @param resourceURI name of the resource. If null or empty, performs search for all + * resource names + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param resourceHandler Handles callbacks, success states and failure states. + * + * Four modes of discovery defined as follows: + * (NULL/Empty, NULL/Empty) - Performs ALL service discovery AND ALL resource + * discovery. + * (NULL/Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) from ALL services. + * (Not Empty, NULL/Empty) - Performs ALL resource discovery on a particular service. + * (Not Empty, Not Empty) - Performs query for a filtered/scoped/particular + * resource(s) + * from a particular service. + * @param QoS QualityOfService the quality of communication + * @see findResource(const std::string&, const std::string&, OCConnectivityType, FindCallback) + */ OCStackResult findResource(const std::string& host, const std::string& resourceURI, OCConnectivityType connectivityType, FindCallback resourceHandler, QualityOfService QoS); /** - * API for Device Discovery - * - * - * @param host Host IP Address. If null or empty, Multicast is performed. - * @param deviceURI Uri containing address to the virtual device in C Stack + * API for Device Discovery + * + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param deviceURI Uri containing address to the virtual device in C Stack ("/oic/d") - * @param connectivityType ::OCConnectivityType type of connectivity indicating the - * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL - * @param deviceInfoHandler device discovery callback - * @param QoS the quality of communication - * - * @return Returns ::OC_STACK_OK if success. - * @note OCStackResult is defined in ocstack.h. - */ + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param deviceInfoHandler device discovery callback + * + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback, QualityOfService) + */ OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI, OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler); + /** + * @overload + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param deviceURI Uri containing address to the virtual device in C Stack + ("/oic/d") + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param deviceInfoHandler device discovery callback + * @param QoS the quality of communication + * @see getDeviceInfo(const std::string&, const std::string&, OCConnectivityType, FindDeviceCallback) + */ OCStackResult getDeviceInfo(const std::string& host, const std::string& deviceURI, OCConnectivityType connectivityType, FindDeviceCallback deviceInfoHandler, QualityOfService QoS); /** - * API for Platform Discovery - * - * - * @param host Host IP Address. If null or empty, Multicast is performed. - * @param platformURI Uri containing address to the virtual platform in C Stack + * API for Platform Discovery + * + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param platformURI Uri containing address to the virtual platform in C Stack ("/oic/p") - * @param connectivityType ::OCConnectivityType type of connectivity indicating the - * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL - * @param platformInfoHandler platform discovery callback - * @param QoS the quality of communication - * - * @return Returns ::OC_STACK_OK if success. - * @note OCStackResult is defined in ocstack.h. - */ + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param platformInfoHandler platform discovery callback + * + * @return Returns ::OC_STACK_OK if success. + * + * @note OCStackResult is defined in ocstack.h. + * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback, QualityOfService) + */ OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI, OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler); + /** + * @overload + * + * @param host Host IP Address. If null or empty, Multicast is performed. + * @param platformURI Uri containing address to the virtual platform in C Stack + ("/oic/p") + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param platformInfoHandler platform discovery callback + * @param QoS the quality of communication + * @see getPlatformInfo(const std::string&, const std::string&, OCConnectivityType, FindPlatformCallback) + */ OCStackResult getPlatformInfo(const std::string& host, const std::string& platformURI, OCConnectivityType connectivityType, FindPlatformCallback platformInfoHandler, QualityOfService QoS); @@ -202,15 +267,15 @@ namespace OC uint8_t resourceProperty); /** - * This API registers a resource with the server - * @note This API applies to server & client side. - - * @param resourceHandle Upon successful registration, resourceHandle will be filled - * @param OCResource The instance of OCResource that all data filled. - * - * @return Returns ::OC_STACK_OK if success. - * @note OCStackResult is defined in ocstack.h. - */ + * This API registers a resource with the server + * @note This API applies to server & client side. + * + * @param resourceHandle Upon successful registration, resourceHandle will be filled + * @param resource The instance of OCResource that all data filled. + * + * @return Returns ::OC_STACK_OK if success. + * @note OCStackResult is defined in ocstack.h. + */ OCStackResult registerResource(OCResourceHandle& resourceHandle, const std::shared_ptr< OCResource > resource); @@ -411,25 +476,40 @@ namespace OC OCStackResult stopPresence(); /** - * subscribes to a server's presence change events. By making this subscription, - * every time a server adds/removes/alters a resource, starts or is intentionally - * stopped (potentially more to be added later). - * - * @param presenceHandle a handle object that can be used to identify this subscription - * request. It can be used to unsubscribe from these events in the future. - * It will be set upon successful return of this method. - * @param host The IP address/addressable name of the server to subscribe to. - * This should be in the format coap://address:port - * @param connectivityType ::OCConnectivityType type of connectivity indicating the - * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL - * @param resourceType a resource type specified as a filter for subscription callbacks. - * @param presenceHandler callback function that will receive notifications/subscription - * events - * - * @return Returns ::OC_STACK_OK if success. - */ + * subscribes to a server's presence change events. By making this subscription, + * every time a server adds/removes/alters a resource, starts or is intentionally + * stopped (potentially more to be added later). + * + * @param presenceHandle a handle object that can be used to identify this subscription + * request. It can be used to unsubscribe from these events in the future. + * It will be set upon successful return of this method. + * @param host The IP address/addressable name of the server to subscribe to. + * This should be in the format coap://address:port + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param presenceHandler callback function that will receive notifications/subscription + * events + * + * @return Returns ::OC_STACK_OK if success. + * @copydoc subscribePresence(OCPresenceHandle&, const std::string&, resourceType, OCConnectivityType, SubscribeCallback) + */ OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, OCConnectivityType connectivityType, SubscribeCallback presenceHandler); + /** + * @overload + * + * @param presenceHandle a handle object that can be used to identify this subscription + * request. It can be used to unsubscribe from these events in the future. + * It will be set upon successful return of this method. + * @param host The IP address/addressable name of the server to subscribe to. + * This should be in the format coap://address:port + * @param resourceType a resource type specified as a filter for subscription callbacks. + * @param connectivityType ::OCConnectivityType type of connectivity indicating the + * interface. Example: OC_WIFI, OC_ETHERNET, OC_ALL + * @param presenceHandler callback function that will receive notifications/subscription + * events + * @see subscribePresence(OCPresenceHandle&, const std::string&, OCConnectivityType, SubscribeCallback) + */ OCStackResult subscribePresence(OCPresenceHandle& presenceHandle, const std::string& host, const std::string& resourceType, OCConnectivityType connectivityType, SubscribeCallback presenceHandler); diff --git a/resource/include/OCProvisioningManager.h b/resource/include/OCProvisioningManager.h index 63b94cf..8c3553c 100644 --- a/resource/include/OCProvisioningManager.h +++ b/resource/include/OCProvisioningManager.h @@ -125,7 +125,7 @@ namespace OC * * @param[in] oxm Ownership transfer method * @param[in] callbackData Methods for ownership transfer - * @param[in] InputPinCallback Method to input pin for verification + * @param[in] inputPin callback method to input pin for verification * @return OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult setOwnerTransferCallbackData(OicSecOxm_t oxm, @@ -140,8 +140,8 @@ namespace OC * - ON/OFF: Device is switched on or off. * * @param[in] timeout waitime for the API. - * @param[out] pOwnedDevList list of owned devices. - * @param[out] pUnownedDevList list of unowned devices. + * @param[out] ownedDevList list of owned devices. + * @param[out] unownedDevList list of unowned devices. * @return OC_STACK_OK in case of success and other value otherwise. */ static OCStackResult getDevInfoFromNetwork(unsigned short timeout, @@ -150,10 +150,10 @@ namespace OC /** * Server API to register callback to display stack generated PIN. * - * @param[in] GeneratePinCallback Method to display generated PIN. + * @param[in] displayPin GeneratePinCallback Method to display generated PIN. * @return OC_STACK_OK in case of success and other value otherwise. */ - static OCStackResult setDisplayPinCB(GeneratePinCallback); + static OCStackResult setDisplayPinCB(GeneratePinCallback displayPin); }; /** @@ -248,7 +248,6 @@ namespace OC * This method is used to get linked devices' IDs. * * @param[out] uuidList information about the list of linked devices' uuids. - * @param[out] numOfDevices total number of linked devices. * @return OC_STACK_OK in case of success and other value otherwise. */ OCStackResult getLinkedDevices(UuidList_t &uuidList); diff --git a/service/resource-encapsulation/include/RCSException.h b/service/resource-encapsulation/include/RCSException.h index d6156d3..1ced6af 100644 --- a/service/resource-encapsulation/include/RCSException.h +++ b/service/resource-encapsulation/include/RCSException.h @@ -45,18 +45,27 @@ namespace OIC /** * Constructs an exception with an empty description. + * + * @see RCSException(const std::string &) + * @see RCSException(std::string &&) */ RCSException(); /** * Constructs an exception with a description. - * + * @overload * @param what The description for the error. + * @see RCSException() + * @see RCSException(std::string &&) */ explicit RCSException(const std::string &what); /** * @overload + * + * @param what The description for the error. + * @see RCSException() + * @see RCSException(const std::string &) */ explicit RCSException(std::string &&what); diff --git a/service/resource-encapsulation/include/RCSResponse.h b/service/resource-encapsulation/include/RCSResponse.h index 6a1a36b..13d94c2 100644 --- a/service/resource-encapsulation/include/RCSResponse.h +++ b/service/resource-encapsulation/include/RCSResponse.h @@ -60,7 +60,10 @@ namespace OIC * The attributes of the RCSResourceObject will be set as the result attributes. * * @param errorCode The error code to set in response. - * + * @see create(const RCSResourceAttributes&) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) */ static RCSGetResponse create(int errorCode); @@ -69,15 +72,27 @@ namespace OIC * This sends the passed attributes as the result attributes * instead of the one the RCSResourceObject holds. * + * @overload * @param attrs The attributes to set. * * @see RCSResourceAttributes + * @see create(int) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) * */ static RCSGetResponse create(const RCSResourceAttributes& attrs); /** - * @override + * @overload + * @param attrs The attributes to set. + * + * @see RCSResourceAttributes + * @see create(int) + * @see create(const RCSResourceAttributes&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) */ static RCSGetResponse create(RCSResourceAttributes&& attrs); @@ -86,16 +101,29 @@ namespace OIC * This sends the passed attributes as the result attributes * instead of the one the RCSResourceObject holds. * + * @overload * @param attrs The attributes to set. * @param errorCode The error code for response. * * @see RCSResourceAttributes - * + * @see create(int) + * @see create(const RCSResourceAttributes&) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) */ static RCSGetResponse create(const RCSResourceAttributes& attrs, int errorCode); /** - * @override + * @overload + * @param attrs The attributes to set. + * @param errorCode The error code for response. + * + * @see RCSResourceAttributes + * @see create(int) + * @see create(const RCSResourceAttributes&) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) */ static RCSGetResponse create(RCSResourceAttributes&& attrs, int errorCode); @@ -160,6 +188,7 @@ namespace OIC * The response will have 200 for the errorCode. * The attributes of RCSResourceObject will be set as the result attributes. * + * @see accept(int) */ static RCSSetResponse accept(); @@ -167,8 +196,10 @@ namespace OIC * Creates a RCSSetResponse that has AcceptanceMethod::ACCEPT and error code passed. * The attributes of the RCSResourceObject will be set as the result attributes. * + * @overload * @param errorCode The error code to set in response. * + * @see accept() */ static RCSSetResponse accept(int errorCode); @@ -193,8 +224,12 @@ namespace OIC * Creates a RCSSetResponse that has AcceptanceMethod::DEFAULT and error code passed. * The attributes of the RCSResourceObject will be set as the result attributes. * + * @overload * @param errorCode The error code to set in response. - * + * @see create(const RCSResourceAttributes&) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) */ static RCSSetResponse create(int errorCode); @@ -203,15 +238,25 @@ namespace OIC * This sends the passed attributes as the result attributes * instead of the one the RCSResourceObject holds. * + * @overload * @param attrs The attributes to set. * * @see RCSResourceAttributes - * + * @see create(int) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) */ static RCSSetResponse create(const RCSResourceAttributes& attrs); /** - * @override + * @overload + * @param attrs The attributes to set. + * @see RCSResourceAttributes + * @see create(int) + * @see create(const RCSResourceAttributes&) + * @see create(const RCSResourceAttributes&, int) + * @see create(RCSResourceAttributes&&, int) */ static RCSSetResponse create(RCSResourceAttributes&& attrs); @@ -220,16 +265,27 @@ namespace OIC * This sends the passed attributes as the result attributes * instead of the one the RCSResourceObject holds. * + * @overload * @param attrs The attributes to set. * @param errorCode The error code for response. * * @see RCSResourceAttributes - * + * @see create(int) + * @see create(const RCSResourceAttributes&) + * @see create(RCSResourceAttributes&&) + * @see create(RCSResourceAttributes&&, int) */ static RCSSetResponse create(const RCSResourceAttributes& attrs, int errorCode); /** - * @override + * @overload + * @param attrs The attributes to set. + * @param errorCode The error code for response. + * @see RCSResourceAttributes + * @see create(int) + * @see create(const RCSResourceAttributes&) + * @see create(RCSResourceAttributes&&) + * @see create(const RCSResourceAttributes&, int) */ static RCSSetResponse create(RCSResourceAttributes&& attrs, int errorCode); -- 2.7.4