Merge pull request #5701 from pan-/ble-doxy-fixes

Ble doxy fixes

Author: adbridge

doxyfile_options

@@ -841,10 +841,15 @@ EXCLUDE_PATTERNS       = */tools/* \
                          */BUILD/* \
                          */rtos/TARGET_CORTEX/rtx* \
                          */cmsis/* \
-                         */FEATURE_* \
                          */features/mbedtls/* \
                          */features/storage/* \
                          */features/unsupported/* \
+                         */features/FEATURE_COMMON_PAL/* \
+                         */features/FEATURE_LWIP/* \
+                         */features/FEATURE_UVISOR/* \
+                         */features/nanostack/* \
+                         */ble/generic/* \
+                         */ble/pal/*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -2081,7 +2086,8 @@ PREDEFINED             = DOXYGEN_ONLY            \
                          DEVICE_SPISLAVE         \
                          DEVICE_STORAGE          \
                          "MBED_DEPRECATED_SINCE(d, m)=" \
-                         "MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)="
+                         "MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)=" \
+                         "MBED_DEPRECATED(s)="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

doxygen_options.json

@@ -6,8 +6,8 @@
     "SEARCH_INCLUDES": "YES",
     "INCLUDE_PATH": "", 
     "INCLUDE_FILE_PATTERNS": "", 
-    "PREDEFINED": "DOXYGEN_ONLY DEVICE_ANALOGIN DEVICE_ANALOGOUT DEVICE_CAN DEVICE_ETHERNET DEVICE_EMAC DEVICE_FLASH  DEVICE_I2C DEVICE_I2CSLAVE DEVICE_I2C_ASYNCH DEVICE_INTERRUPTIN DEVICE_LOWPOWERTIMER DEVICE_PORTIN DEVICE_PORTINOUT DEVICE_PORTOUT DEVICE_PWMOUT DEVICE_RTC DEVICE_TRNG DEVICE_SERIAL DEVICE_SERIAL_ASYNCH DEVICE_SERIAL_FC DEVICE_SLEEP DEVICE_SPI DEVICE_SPI_ASYNCH DEVICE_SPISLAVE DEVICE_STORAGE \"MBED_DEPRECATED_SINCE(f, g)=\" \"MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)=\"",
+    "PREDEFINED": "DOXYGEN_ONLY DEVICE_ANALOGIN DEVICE_ANALOGOUT DEVICE_CAN DEVICE_ETHERNET DEVICE_EMAC DEVICE_FLASH  DEVICE_I2C DEVICE_I2CSLAVE DEVICE_I2C_ASYNCH DEVICE_INTERRUPTIN DEVICE_LOWPOWERTIMER DEVICE_PORTIN DEVICE_PORTINOUT DEVICE_PORTOUT DEVICE_PWMOUT DEVICE_RTC DEVICE_TRNG DEVICE_SERIAL DEVICE_SERIAL_ASYNCH DEVICE_SERIAL_FC DEVICE_SLEEP DEVICE_SPI DEVICE_SPI_ASYNCH DEVICE_SPISLAVE DEVICE_STORAGE \"MBED_DEPRECATED_SINCE(f, g)=\" \"MBED_ENABLE_IF_CALLBACK_COMPATIBLE(F, M)=\" \"MBED_DEPRECATED(s)=\"",
     "EXPAND_AS_DEFINED": "", 
     "SKIP_FUNCTION_MACROS": "NO",
-    "EXCLUDE_PATTERNS": "*/tools/* */targets/* */FEATURE_*/* */features/mbedtls/* */features/storage/* */features/unsupported/* */BUILD/* */rtos/TARGET_CORTEX/rtx*/* */cmsis/* */features/FEATURES_*"
+    "EXCLUDE_PATTERNS": "*/tools/* */targets/* */features/mbedtls/* */features/storage/* */features/unsupported/* */BUILD/* */rtos/TARGET_CORTEX/rtx*/* */cmsis/* */features/FEATURE_COMMON_PAL/* */features/FEATURE_LWIP/* */features/FEATURE_UVISOR/* */features/nanostack/* */ble/generic/* */ble/pal/*"
 }

features/FEATURE_BLE/ble/BLE.h

@@ -280,7 +280,7 @@ class BLE
      * function-pointer, init() can also take an <Object, member> pair as its
      * callback target.
      *
-     * @important This should be called before using anything else in the BLE
+     * @attention This should be called before using anything else in the BLE
      * API.
      */
     ble_error_t init(InitializationCompleteCallback_t completion_cb = NULL) {
@@ -321,7 +321,7 @@ class BLE
      * @return BLE_ERROR_NONE if the instance was shut down without error or the
      * appropriate error code.
      *
-     * @important init() must be called afterward to reinstate services and
+     * @attention init() must be called afterward to reinstate services and
      * GAP state. This API offers a way to repopulate the GATT database with new
      * services and characteristics.
      */

features/FEATURE_BLE/ble/BLEInstanceBase.h

@@ -46,7 +46,7 @@ class GattClient;
  * createBLEInstance(). The BLE API uses this singleton function to gain
  * access to a concrete implementation of this class defined in the vendor port.
  *
- * @important This class is part of the porting API and is not meant to be used
+ * @attention This class is part of the porting API and is not meant to be used
  * by end users of BLE API.
  *
  * @see BLE
@@ -237,7 +237,7 @@ class BLEInstanceBase
      * Process pending events present in the vendor subsystem; then, put the MCU
      * to sleep until an external source wakes it up.
      *
-     * @important This function is deprecated in the BLE class. It will be
+     * @attention This function is deprecated in the BLE class. It will be
      * removed from this interface once it is removed from BLE.
      *
      * @see BLE::waitForEvent() BLE::processEvents()
@@ -254,10 +254,10 @@ class BLEInstanceBase
 /**
  * Return the instance of the vendor implementation of BLEInstanceBase.
  *
- * @important Contrary to its name, this function does not return a new instance
+ * @attention Contrary to its name, this function does not return a new instance
  * at each call. It rather acts like an accessor to a singleton.
  *
- * @important The vendor library must provide an implementation for this function
+ * @attention The vendor library must provide an implementation for this function
  * library. Otherwise, there will be a linker error.
  */
 extern BLEInstanceBase *createBLEInstance(void);

features/FEATURE_BLE/ble/DiscoveredService.h

@@ -84,7 +84,7 @@ class DiscoveredService {
     /**
      * Construct a DiscoveredService instance.
      *
-     * @important This API is not meant to be used publicly. It is meant to be
+     * @attention This API is not meant to be used publicly. It is meant to be
      * used by internal APIs of Mbed BLE.
      */
     DiscoveredService() :
@@ -96,7 +96,7 @@ class DiscoveredService {
     /**
      * Set information about the discovered service.
      *
-     * @important This API is not meant to be used publicly. It is meant to be
+     * @attention This API is not meant to be used publicly. It is meant to be
      * used by internal APIs of Mbed BLE.
      *
      * @param[in] uuidIn The UUID of the discovered service.
@@ -118,7 +118,7 @@ class DiscoveredService {
     /**
      * Set the start and end handle of the discovered service.
      *
-     * @important This API is not meant to be used publicly. It is meant to be
+     * @attention This API is not meant to be used publicly. It is meant to be
      * used by internal APIs of Mbed BLE.
      *
      * @param[in] startHandleIn The start handle of the discovered service in
@@ -137,7 +137,7 @@ class DiscoveredService {
     /**
      * Set the long UUID of the discovered service.
      *
-     * @important This API is not meant to be used publicly. It is meant to be
+     * @attention This API is not meant to be used publicly. It is meant to be
      * used by internal APIs of Mbed BLE.
      *
      * @param[in] longUUID The bytes composing the long UUID of this discovered

features/FEATURE_BLE/ble/FunctionPointerWithContext.h

@@ -46,7 +46,7 @@
  * This class also offers a mechanism to chain other instances to it. When an
  * instance is called, all the instances being part of the chain are called.
  *
- * @important freestanding or member function adapted must accept a single
+ * @attention freestanding or member function adapted must accept a single
  * argument, and this argument is a pointer to ContextType. Adapted
  * primitives do not return anything.
  *
@@ -77,7 +77,7 @@ class FunctionPointerWithContext : public SafeBool<FunctionPointerWithContext<Co
      *
      * @param[in] object Pointer to the instance which is used to invoke @p
      * member.
-     * @param[in] Pointer to the member function to adapt.
+     * @param[in] member Pointer to the member function to adapt.
      */
     template<typename T>
     FunctionPointerWithContext(T *object, void (T::*member)(ContextType context)) :
@@ -136,7 +136,7 @@ class FunctionPointerWithContext : public SafeBool<FunctionPointerWithContext<Co
      * operator.
      *
      * @param[in] object Pointer to the instance is used to invoke @p member.
-     * @param[in] function Pointer to the member function to adapt.
+     * @param[in] member Pointer to the member function to adapt.
      */
     template<typename T>
     void attach(T *object, void (T::*member)(ContextType context))

features/FEATURE_BLE/ble/Gap.h

@@ -347,7 +347,7 @@ class Gap {
     /**
      * Enumeration of disconnection reasons.
      *
-     * @important There might be a mismatch between the disconnection reason
+     * @attention There might be a mismatch between the disconnection reason
      * passed to disconnect() and the disconnection event generated locally
      * because the disconnection reason passed to disconnect() is the
      * disconnection reason to be transmitted to the peer.
@@ -356,7 +356,7 @@ class Gap {
         /**
          * The connection timed out.
          *
-         * @important shall not be used as a reason in disconnect().
+         * @attention shall not be used as a reason in disconnect().
          */
         CONNECTION_TIMEOUT = 0x08,
 
@@ -379,7 +379,7 @@ class Gap {
          * Indicate that the local user or the internal
          * Bluetooth subsystem terminated the connection.
          *
-         * @important shall not be used as a reason in disconnect().
+         * @attention shall not be used as a reason in disconnect().
          */
         LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
 
@@ -548,7 +548,7 @@ class Gap {
      *
      * @note The BLE API does not express the broadcaster and scanner roles.
      *
-     * @important A device can fulfill different roles concurrently.
+     * @attention A device can fulfill different roles concurrently.
      */
     enum Role_t {
         /**
@@ -1147,7 +1147,7 @@ class Gap {
      * invoked with the @p deviceName parameter set to NULL.
      *
      * @param[out] deviceName Pointer to an empty buffer where the UTF-8
-     * <b>non NULL-terminated<b> string is placed.
+     * <b>non NULL-terminated</b> string is placed.
      *
      * @param[in,out] lengthP Length of the @p deviceName buffer. If the device
      * name is successfully copied, then the length of the device name
@@ -1192,7 +1192,7 @@ class Gap {
     /**
      * Get the value of the appearance characteristic in the GAP service.
      *
-     * @param[out] appearance The current device-appearance value.
+     * @param[out] appearanceP The current device-appearance value.
      *
      * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
      * from the underlying BLE stack.
@@ -1265,8 +1265,6 @@ class Gap {
      *
      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
      * copied into the supplied reference.
-     *
-     * @experimental
      */
     virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const
     {
@@ -1284,7 +1282,7 @@ class Gap {
      * populated with the addresses in the given whitelist.
      *
      * @note The whitelist must not contain addresses of type @ref
-     * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE. This
+     * BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE. This
      * results in a @ref BLE_ERROR_INVALID_PARAM because the remote peer might
      * change its private address at any time, and it is not possible to resolve
      * it.
@@ -1971,14 +1969,14 @@ class Gap {
     /**
      * Start the advertising procedure.
      *
-     * @param[in] Advertising parameters to use.
+     * @param[in] params Advertising parameters to use.
      *
      * @return BLE_ERROR_NONE if the advertising procedure successfully
      * started.
      *
      * @note Must be implemented in vendor port.
      */
-    virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
+    virtual ble_error_t startAdvertising(const GapAdvertisingParams &params) = 0;
 
 public:
     /**
@@ -2271,7 +2269,7 @@ class Gap {
     /**
      * Notify all registered connection event handlers of a connection event.
      *
-     * @important This function is meant to be called from the BLE stack specific
+     * @attention This function is meant to be called from the BLE stack specific
      * implementation when a connection event occurs.
      *
      * @param[in] handle Handle of the new connection.
@@ -2312,7 +2310,7 @@ class Gap {
     /**
      * Notify all registered disconnection event handlers of a disconnection event.
      *
-     * @important This function is meant to be called from the BLE stack specific
+     * @attention This function is meant to be called from the BLE stack specific
      * implementation when a disconnection event occurs.
      *
      * @param[in] handle Handle of the terminated connection.
@@ -2334,12 +2332,12 @@ class Gap {
      * Forward a received advertising packet to all registered event handlers
      * listening for scanned packet events.
      *
-     * @important This function is meant to be called from the BLE stack specific
+     * @attention This function is meant to be called from the BLE stack specific
      * implementation when a disconnection event occurs.
      *
      * @param[in] peerAddr Address of the peer that has emitted the packet.
      * @param[in] rssi Value of the RSSI measured for the received packet.
-     * @param[in] isScanReponse If true, then the packet is a response to a scan
+     * @param[in] isScanResponse If true, then the packet is a response to a scan
      * request.
      * @param[in] type Advertising type of the packet.
      * @param[in] advertisingDataLen Length of the advertisement data received.
@@ -2367,7 +2365,7 @@ class Gap {
      * Notify the occurrence of a timeout event to all registered timeout events
      * handler.
      *
-     * @important This function is meant to be called from the BLE stack specific
+     * @attention This function is meant to be called from the BLE stack specific
      * implementation when a disconnection event occurs.
      *
      * @param[in] source Source of the timout event.

features/FEATURE_BLE/ble/GapEvents.h

@@ -19,7 +19,7 @@
 
 #include "blecommon.h"
 
-/// @cond 0
+/// @cond INVALID_SECTIONS
 
 /*!
     \brief

features/FEATURE_BLE/ble/GattAttribute.h

@@ -166,7 +166,7 @@ class GattAttribute {
     /**
      * Get a pointer to the current length of the attribute value.
      *
-     * @important note Do not use this function.
+     * @attention note Do not use this function.
      *
      * @return A pointer to the current length of the attribute value.
      */
@@ -178,7 +178,7 @@ class GattAttribute {
     /**
      * Set the attribute handle.
      *
-     * @important The GattServer uses this function internally.
+     * @attention The GattServer uses this function internally.
      * Application code must not use it.
      *
      * @param[in] id The new attribute handle.