High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

Revision:
1183:1589830dbdb7
Parent:
1182:b70129080ddf
Child:
1185:a16103dfb50c
--- a/ble/Gap.h	Wed Apr 06 19:15:34 2016 +0100
+++ b/ble/Gap.h	Wed Apr 06 19:15:36 2016 +0100
@@ -40,23 +40,24 @@
     /**
      * Address-type for BLEProtocol addresses.
      *
-     * @note: deprecated. Use BLEProtocol::AddressType_t instead.
+     * @deprecated Use BLEProtocol::AddressType_t instead.
      */
     typedef BLEProtocol::AddressType_t AddressType_t;
 
     /**
      * Address-type for BLEProtocol addresses.
-     * @note: deprecated. Use BLEProtocol::AddressType_t instead.
+     *
+     * @deprecated Use BLEProtocol::AddressType_t instead.
      */
     typedef BLEProtocol::AddressType_t addr_type_t;
 
     /**
      * Address-type for BLEProtocol addresses.
-     * \deprecated: Use BLEProtocol::AddressType_t instead.
      *
-     * DEPRECATION ALERT: The following constants have been left in their
-     * deprecated state to transparenly support existing applications which may
-     * have used Gap::ADDR_TYPE_*.
+     * @deprecated Use BLEProtocol::AddressType_t instead. The following
+     *             constants have been left in their deprecated state to
+     *             transparenly support existing applications which may have
+     *             used Gap::ADDR_TYPE_*.
      */
     enum DeprecatedAddressType_t {
         ADDR_TYPE_PUBLIC                        = BLEProtocol::AddressType::PUBLIC,
@@ -65,11 +66,27 @@
         ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
     };
 
-    static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
-    typedef BLEProtocol::AddressBytes_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
-    typedef BLEProtocol::AddressBytes_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
+    /**
+     * Length (in octets) of the BLE MAC address.
+     */
+    static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN;
+    /**
+     * 48-bit address, LSB format.
+     *
+     * @deprecated Use BLEProtocol::AddressBytes_t instead.
+     */
+    typedef BLEProtocol::AddressBytes_t Address_t;
+    /**
+     * 48-bit address, LSB format.
+     *
+     * @deprecated Use BLEProtocol::AddressBytes_t instead.
+     */
+    typedef BLEProtocol::AddressBytes_t address_t;
 
 public:
+    /**
+     * Enumeration for timeout sources.
+     */
     enum TimeoutSource_t {
         TIMEOUT_SRC_ADVERTISING      = 0x00, /**< Advertising timeout. */
         TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
@@ -137,51 +154,94 @@
      * @experimental
      */
     struct Whitelist_t {
-        BLEProtocol::Address_t *addresses;
-        uint8_t                 size;
-        uint8_t                 capacity;
+        BLEProtocol::Address_t *addresses; /**< List of BLE addresses in the whitelist. */
+        uint8_t                 size;      /**< Total number of BLE addresses in this whitelist */
+        uint8_t                 capacity;  /**< Maximum number of BLE addresses that can be added to this whitelist. */
     };
 
 
-    /* Describes the current state of the device (more than one bit can be set). */
+    /**
+     * Describes the current state of the device (more than one bit can be set).
+     */
     struct GapState_t {
         unsigned advertising : 1; /**< Peripheral is currently advertising. */
         unsigned connected   : 1; /**< Peripheral is connected to a central. */
     };
 
-    typedef uint16_t Handle_t; /* Type for connection handle. */
+    /**
+     * Type for connection handle.
+     */
+    typedef uint16_t Handle_t;
 
+    /**
+     * Structure containing GAP connection parameters. When in peripheral role
+     * the connection parameters are suggestions. The choice of the connection
+     * parameters is eventually up to the central.
+     */
     typedef struct {
-        uint16_t minConnectionInterval;        /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
-        uint16_t maxConnectionInterval;        /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
-        uint16_t slaveLatency;                 /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
-        uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
+        uint16_t minConnectionInterval;        /**< Minimum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
+        uint16_t maxConnectionInterval;        /**< Maximum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
+        uint16_t slaveLatency;                 /**< Slave Latency in number of connection events, see BLE_GAP_CP_LIMITS.*/
+        uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see BLE_GAP_CP_LIMITS.*/
     } ConnectionParams_t;
 
+    /**
+     * Enumeration for the possible GAP roles of a BLE device.
+     */
     enum Role_t {
         PERIPHERAL  = 0x1, /**< Peripheral Role. */
         CENTRAL     = 0x2, /**< Central Role.    */
     };
 
+    /**
+     * Structure containing data and metadata of a scanned advertising packet.
+     */
     struct AdvertisementCallbackParams_t {
-        BLEProtocol::AddressBytes_t              peerAddr;
-        int8_t                                   rssi;
-        bool                                     isScanResponse;
-        GapAdvertisingParams::AdvertisingType_t  type;
-        uint8_t                                  advertisingDataLen;
-        const uint8_t                           *advertisingData;
+        BLEProtocol::AddressBytes_t              peerAddr;           /**< The peer's BLE address. */
+        int8_t                                   rssi;               /**< The advertisement packet RSSI value. */
+        bool                                     isScanResponse;     /**< Whether this packet is the response to a scan request. */
+        GapAdvertisingParams::AdvertisingType_t  type;               /**< The type of advertisement. */
+        uint8_t                                  advertisingDataLen; /**< Length of the advertisement data. */
+        const uint8_t                           *advertisingData;    /**< Pointer to the advertisement packet's data. */
     };
+
+    /**
+     * Type for the handlers of advertisement callback events. Refer to
+     * Gap::startScan().
+     */
     typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
 
+    /**
+     * Encapsulates the parameters of a connection. This information is passed
+     * to the registered handler of connection events. Refer to Gap::onConnection().
+     */
     struct ConnectionCallbackParams_t {
-        Handle_t                    handle;
-        Role_t                      role;
-        BLEProtocol::AddressType_t  peerAddrType;
-        BLEProtocol::AddressBytes_t peerAddr;
-        BLEProtocol::AddressType_t  ownAddrType;
-        BLEProtocol::AddressBytes_t ownAddr;
-        const ConnectionParams_t   *connectionParams;
+        Handle_t                    handle;           /**< The ID for this connection */
+        Role_t                      role;             /**< This device's role in the connection */
+        BLEProtocol::AddressType_t  peerAddrType;     /**< The peer's BLE address type */
+        BLEProtocol::AddressBytes_t peerAddr;         /**< The peer's BLE address */
+        BLEProtocol::AddressType_t  ownAddrType;      /**< This device's BLE address type */
+        BLEProtocol::AddressBytes_t ownAddr;          /**< This devices's BLE address */
+        const ConnectionParams_t   *connectionParams; /**< The currently configured connection parameters */
 
+        /**
+         * Constructor for ConnectionCallbackParams_t.
+         *
+         * @param[in] handleIn
+         *              Value for ConnectionCallbackParams_t::handle
+         * @param[in] roleIn
+         *              Value for ConnectionCallbackParams_t::role
+         * @param[in] peerAddrTypeIn
+         *              Value for ConnectionCallbackParams_t::peerAddrType
+         * @param[in] peerAddrIn
+         *              Value for ConnectionCallbackParams_t::peerAddr
+         * @param[in] ownAddrTypeIn
+         *              Value for ConnectionCallbackParams_t::ownAddrType
+         * @param[in] ownAddrIn
+         *              Value for ConnectionCallbackParams_t::ownAddr
+         * @param[in] connectionParamsIn
+         *              Value for ConnectionCallbackParams_t::connectionParams
+         */
         ConnectionCallbackParams_t(Handle_t                    handleIn,
                                    Role_t                      roleIn,
                                    BLEProtocol::AddressType_t  peerAddrTypeIn,
@@ -201,10 +261,22 @@
         }
     };
 
+    /**
+     * Structure that encapsulates information about a disconnection event.
+     * Refer to Gap::onDisconnection().
+     */
     struct DisconnectionCallbackParams_t {
-        Handle_t              handle;
-        DisconnectionReason_t reason;
+        Handle_t              handle; /**< The ID of the connection that caused the disconnection event */
+        DisconnectionReason_t reason; /**< The reason of the disconnection event */
 
+        /**
+         * Constructor for DisconnectionCallbackParams_t.
+         *
+         * @param[in] handleIn
+         *              Value for DisconnectionCallbackParams_t::handle.
+         * @param[in] reasonIn
+         *              Value for DisconnectionCallbackParams_t::reason.
+         */
         DisconnectionCallbackParams_t(Handle_t              handleIn,
                                       DisconnectionReason_t reasonIn) :
             handle(handleIn),
@@ -213,22 +285,63 @@
     };
 
     static const uint16_t UNIT_1_25_MS  = 1250; /**< Number of microseconds in 1.25 milliseconds. */
+    /**
+     * Helper function to convert from units of milliseconds to GAP duration
+     * units.
+     *
+     * @param[in] durationInMillis
+     *              The duration in milliseconds.
+     *
+     * @return The duration in GAP duration units.
+     */
     static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
         return (durationInMillis * 1000) / UNIT_1_25_MS;
     }
 
+    /**
+     * Type for the registered callbacks added to the timeout event callchain.
+     * Refer to Gap::onTimeout().
+     */
     typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
+    /**
+     * Type for the timeout event callchain. Refer to Gap::onTimeout().
+     */
     typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
 
+    /**
+     * Type for the registered callbacks added to the connection event
+     * callchain. Refer to Gap::onConnection().
+     */
     typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
+    /**
+     * Type for the connection event callchain. Refer to Gap::onConnection().
+     */
     typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
 
+    /**
+     * Type for the registered callbacks added to the disconnection event
+     * callchain. Refer to Gap::onDisconnetion().
+     */
     typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
+    /**
+     * Type for the disconnection event callchain. Refer to Gap::onDisconnection().
+     */
     typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
 
+    /**
+     * Type for the handlers of radio notification callback events. Refer to
+     * Gap::onRadioNotification().
+     */
     typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
 
+    /**
+     * Type for the handlers of shutdown callback events. Refer to
+     * Gap::onShutdown().
+     */
     typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t;
+    /**
+     * Type for the shutdown event callchain. Refer to Gap::onShutdown().
+     */
     typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t;
 
     /*
@@ -239,6 +352,11 @@
      * Set the BTLE MAC address and type. Please note that the address format is
      * least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t.
      *
+     * @param[in] type
+     *              The type of the BLE address to set.
+     * @param[in] address
+     *              The BLE address to set.
+     *
      * @return BLE_ERROR_NONE on success.
      */
     virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
@@ -252,6 +370,11 @@
     /**
      * Fetch the BTLE MAC address and type.
      *
+     * @param[out]  typeP
+     *                  The current BLE address type.
+     * @param[out]  address
+     *                  The current BLE address.
+     *
      * @return BLE_ERROR_NONE on success.
      */
     virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
@@ -263,28 +386,44 @@
     }
 
     /**
+     * Get the minimum advertising interval in milliseconds for connectable
+     * undirected and connectable directed event types supported by the
+     * underlying BLE stack.
+     *
      * @return Minimum Advertising interval in milliseconds for connectable
-     *      undirected and connectable directed event types.
+     *         undirected and connectable directed event types.
      */
     virtual uint16_t getMinAdvertisingInterval(void) const {
         return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
     }
 
     /**
+     * Get the minimum advertising interval in milliseconds for scannable
+     * undirected and non-connectable undirected even types supported by the
+     * underlying BLE stack.
+     *
      * @return Minimum Advertising interval in milliseconds for scannable
-     *      undirected and non-connectable undirected event types.
+     *         undirected and non-connectable undirected event types.
      */
     virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
         return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
     }
 
     /**
+     * Get the maximum advertising interval in milliseconds for all event types
+     * supported by the underlying BLE stack.
+     *
      * @return Maximum Advertising interval in milliseconds.
      */
     virtual uint16_t getMaxAdvertisingInterval(void) const {
         return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
     }
 
+    /**
+     * Stop advertising. The current advertising parameters remain in effect.
+     *
+     * @retval BLE_ERROR_NONE if successfully stopped advertising procedure.
+     */
     virtual ble_error_t stopAdvertising(void) {
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
     }
@@ -301,17 +440,18 @@
     /**
      * Create a connection (GAP Link Establishment).
      *
-     * @param peerAddr
-     *          48-bit address, LSB format.
-     * @param peerAddrType
-     *          Address type of the peer.
-     * @param connectionParams
-     *         Connection parameters.
-     * @param scanParams
-     *          Paramters to be used while scanning for the peer.
+     * @param[in] peerAddr
+     *              48-bit address, LSB format.
+     * @param[in] peerAddrType
+     *              Address type of the peer.
+     * @param[in] connectionParams
+     *              Connection parameters.
+     * @param[in] scanParams
+     *              Paramters to be used while scanning for the peer.
+     *
      * @return  BLE_ERROR_NONE if connection establishment procedure is started
-     *     successfully. The connectionCallChain (if set) will be invoked upon
-     *     a connection event.
+     *          successfully. The connectionCallChain (if set) will be invoked upon
+     *          a connection event.
      */
     virtual ble_error_t connect(const BLEProtocol::AddressBytes_t  peerAddr,
                                 BLEProtocol::AddressType_t         peerAddrType,
@@ -329,11 +469,12 @@
     /**
      * Create a connection (GAP Link Establishment).
      *
-     * \deprecated: This funtion overloads Gap::connect(const BLEProtocol::Address_t  peerAddr,
-                                                        BLEProtocol::AddressType_t    peerAddrType,
-                                                        const ConnectionParams_t     *connectionParams,
-                                                        const GapScanningParams      *scanParams)
-     *      to maintain backward compatibility for change from Gap::AddressType_t to BLEProtocol::AddressType_t
+     * @deprecated  This funtion overloads Gap::connect(const BLEProtocol::Address_t  peerAddr,
+     *                                                  BLEProtocol::AddressType_t    peerAddrType,
+     *                                                  const ConnectionParams_t     *connectionParams,
+     *                                                  const GapScanningParams      *scanParams)
+     *              to maintain backward compatibility for change from Gap::AddressType_t to
+     *              BLEProtocol::AddressType_t.
      */
     ble_error_t connect(const BLEProtocol::AddressBytes_t  peerAddr,
                         DeprecatedAddressType_t            peerAddrType,
@@ -348,8 +489,12 @@
      * be communicated to the application with an invocation of the
      * disconnectionCallback.
      *
-     * @param  reason
-     *           The reason for disconnection; to be sent back to the peer.
+     * @param[in] reason
+     *              The reason for disconnection; to be sent back to the peer.
+     * @param[in] connectionHandle
+     *              The handle of the connection to disconnect from.
+     *
+     * @return  BLE_ERROR_NONE if disconnection was successful.
      */
     virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
         /* avoid compiler warnings about unused variables */
@@ -364,13 +509,15 @@
      * be communicated to the application with an invocation of the
      * disconnectionCallback.
      *
-     * @param  reason
-     *           The reason for disconnection; to be sent back to the peer.
+     * @param[in] reason
+     *              The reason for disconnection; to be sent back to the peer.
+     *
+     * @return  BLE_ERROR_NONE if disconnection was successful.
      *
-     * @note: This version of disconnect() doesn't take a connection handle. It
-     * works reliably only for stacks that are limited to a single
-     * connection. This API should be considered *deprecated* in favour of the
-     * alternative, which takes a connection handle. It will be dropped in the future.
+     * @deprecated This version of disconnect() doesn't take a connection handle. It
+     *             works reliably only for stacks that are limited to a single
+     *             connection. Use instead Gap::disconnect(Handle_t connectionHandle,
+     *             DisconnectionReason_t reason) instead.
      */
     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
         /* Avoid compiler warnings about unused variables. */
@@ -389,7 +536,7 @@
      *               for this is owned by the caller.
      *
      * @return BLE_ERROR_NONE if the parameters were successfully filled into
-     * the given structure pointed to by params.
+     *         the given structure pointed to by params.
      */
     virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
         /* Avoid compiler warnings about unused variables. */
@@ -405,6 +552,9 @@
      *
      * @param[in] params
      *               The structure containing the desired parameters.
+     *
+     * @return BLE_ERROR_NONE if the preferred connection params were set
+     *         correctly.
      */
     virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
         /* Avoid compiler warnings about unused variables. */
@@ -414,16 +564,18 @@
     }
 
     /**
-     * Update connection parameters.
-     * In the central role this will initiate a Link Layer connection parameter update procedure.
-     * In the peripheral role, this will send the corresponding L2CAP request and wait for
-     * the central to perform the procedure.
+     * Update connection parameters. In the central role this will initiate a
+     * Link Layer connection parameter update procedure. In the peripheral role,
+     * this will send the corresponding L2CAP request and wait for the central
+     * to perform the procedure.
      *
      * @param[in] handle
      *              Connection Handle.
      * @param[in] params
      *              Pointer to desired connection parameters. If NULL is provided on a peripheral role,
      *              the parameters in the PPCP characteristic of the GAP service will be used instead.
+     *
+     * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
      */
     virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
         /* avoid compiler warnings about unused variables */
@@ -435,8 +587,11 @@
 
     /**
      * Set the device name characteristic in the GAP service.
+     *
      * @param[in] deviceName
      *              The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
+     *
+     * @return BLE_ERROR_NONE if the device name was set correctly.
      */
     virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
         /* Avoid compiler warnings about unused variables. */
@@ -447,21 +602,25 @@
 
     /**
      * Get the value of the device name characteristic in the GAP service.
+     *
      * @param[out]    deviceName
      *                  Pointer to an empty buffer where the UTF-8 *non NULL-
      *                  terminated* string will be placed. Set this
      *                  value to NULL in order to obtain the deviceName-length
      *                  from the 'length' parameter.
      *
-     * @param[in/out] lengthP
+     * @param[in,out] lengthP
      *                  (on input) Length of the buffer pointed to by deviceName;
      *                  (on output) the complete device name length (without the
      *                     null terminator).
      *
+     * @return BLE_ERROR_NONE if the device name was fetched correctly from the
+     *         underlying BLE stack.
+     *
      * @note If the device name is longer than the size of the supplied buffer,
-     *     length will return the complete device name length, and not the
-     *     number of bytes actually returned in deviceName. The application may
-     *     use this information to retry with a suitable buffer size.
+     *       length will return the complete device name length, and not the
+     *       number of bytes actually returned in deviceName. The application may
+     *       use this information to retry with a suitable buffer size.
      */
     virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
         /* avoid compiler warnings about unused variables */
@@ -473,8 +632,11 @@
 
     /**
      * Set the appearance characteristic in the GAP service.
+     *
      * @param[in] appearance
      *              The new value for the device-appearance.
+     *
+     * @return BLE_ERROR_NONE if the new appearance was set correctly.
      */
     virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
         /* Avoid compiler warnings about unused variables. */
@@ -485,8 +647,12 @@
 
     /**
      * Get the appearance characteristic in the GAP service.
+     *
      * @param[out] appearance
-     *               The new value for the device-appearance.
+     *               The current device-appearance value.
+     *
+     * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
+     *         from the underlying BLE stack.
      */
     virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
         /* Avoid compiler warnings about unused variables. */
@@ -497,7 +663,12 @@
 
     /**
      * Set the radio's transmit power.
-     * @param[in] txPower Radio transmit power in dBm.
+     *
+     * @param[in] txPower
+     *              Radio's transmit power in dBm.
+     *
+     * @return BLE_ERROR_NONE if the new radio's transmit power was set
+     *         correctly.
      */
     virtual ble_error_t setTxPower(int8_t txPower) {
         /* Avoid compiler warnings about unused variables. */
@@ -523,8 +694,14 @@
     }
 
     /**
+     * Get the maximum size of the whitelist.
+     *
      * @return Maximum size of the whitelist.
      *
+     * @note If using mbed OS the size of the whitelist can be configured by
+     *       setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta
+     *       config file.
+     *
      * @experimental
      */
     virtual uint8_t getMaxWhitelistSize(void) const
@@ -536,7 +713,7 @@
      * Get the internal whitelist to be used by the Link Layer when scanning,
      * advertising or initiating a connection depending on the filter policies.
      *
-     * @param[in/out]   whitelist
+     * @param[in,out]   whitelist
      *                  (on input) whitelist.capacity contains the maximum number
      *                  of addresses to be returned.
      *                  (on output) The populated whitelist with copies of the
@@ -674,6 +851,15 @@
 
 protected:
     /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
+
+    /**
+     * Start scanning procedure in the underlying BLE stack.
+     *
+     * @param[in] scanningParams
+     *              The GAP scanning parameters.
+     *
+     * @return BLE_ERROR_NONE if the scan procedure started successfully.
+     */
     virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
         (void)scanningParams;
         return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -684,8 +870,10 @@
      */
 public:
     /**
-     * Returns the current GAP state of the device using a bitmask that
+     * Get the current GAP state of the device using a bitmask that
      * describes whether the device is advertising or connected.
+     *
+     * @return The current GAP state of the device.
      */
     GapState_t getState(void) const {
         return state;
@@ -693,12 +881,17 @@
 
     /**
      * Set the GAP advertising mode to use for this device.
+     *
+     * @param[in] advType
+     *              The new type of the advertising packets.
      */
     void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
         _advParams.setAdvertisingType(advType);
     }
 
     /**
+     * Set the advertising interval.
+     *
      * @param[in] interval
      *              Advertising interval in units of milliseconds. Advertising
      *              is disabled if interval is 0. If interval is smaller than
@@ -709,15 +902,15 @@
      *              This field must be set to 0 if connectionMode is equal
      *              to ADV_CONNECTABLE_DIRECTED.
      *
-     * @note: Decreasing this value will allow central devices to detect a
-     * peripheral faster, at the expense of more power being used by the radio
-     * due to the higher data transmit rate.
+     * @note  Decreasing this value will allow central devices to detect a
+     *        peripheral faster, at the expense of more power being used by the radio
+     *        due to the higher data transmit rate.
      *
-     * @Note: [WARNING] This API previously used 0.625ms as the unit for its
-     * 'interval' argument. That required an explicit conversion from
-     * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
-     * no longer required as the new units are milliseconds. Any application
-     * code depending on the old semantics needs to be updated accordingly.
+     * @note  [WARNING] This API previously used 0.625ms as the unit for its
+     *        @p interval argument. That required an explicit conversion from
+     *        milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
+     *        no longer required as the new units are milliseconds. Any application
+     *        code depending on the old semantics needs to be updated accordingly.
      */
     void setAdvertisingInterval(uint16_t interval) {
         if (interval == 0) {
@@ -729,6 +922,9 @@
     }
 
     /**
+     * Set the advertising timeout. The length of time to advertise for before
+     * a timeout event is generated.
+     *
      * @param[in] timeout
      *              Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
      *              and 16383). Use 0 to disable the advertising timeout.
@@ -739,14 +935,12 @@
 
     /**
      * Start advertising.
+     *
+     * @return BLE_ERROR_NONE if the device started advertising successfully.
      */
     ble_error_t startAdvertising(void) {
-        ble_error_t rc;
         setAdvertisingData(); /* Update the underlying stack. */
-        if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
-            state.advertising = 1;
-        }
-        return rc;
+        return startAdvertising(_advParams);
     }
 
     /**
@@ -769,6 +963,9 @@
      *              The flags to be added. Please refer to
      *              GapAdvertisingData::Flags for valid flags. Multiple
      *              flags may be specified in combination.
+     *
+     * @return BLE_ERROR_NONE if the data was successfully added to the
+     *         advertising payload.
      */
     ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
         ble_error_t rc;
@@ -785,8 +982,11 @@
      * as an additional 31 bytes if the advertising payload is too
      * small.
      *
-     * @param  app
-     *         The appearance of the peripheral.
+     * @param[in]  app
+     *              The appearance of the peripheral.
+     *
+     * @return BLE_ERROR_NONE if the data was successfully added to the
+     *         advertising payload.
      */
     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
         setAppearance(app);
@@ -805,8 +1005,11 @@
      * as an additional 31 bytes if the advertising payload is too
      * small.
      *
-     * @param  power
-     *         The max transmit power to be used by the controller (in dBm).
+     * @param[in]  power
+     *              The max transmit power to be used by the controller (in dBm).
+     *
+     * @return BLE_ERROR_NONE if the data was successfully added to the
+     *         advertising payload.
      */
     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
         ble_error_t rc;
@@ -823,9 +1026,12 @@
      * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
      * advertising payload is too small.
      *
-     * @param  type The type describing the variable length data.
-     * @param  data Data bytes.
-     * @param  len  Length of data.
+     * @param[in]  type
+     *              The type describing the variable length data.
+     * @param[in]  data
+     *              Data bytes.
+     * @param[in]  len
+     *              Length of data.
      *
      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
      *         matching AD type; otherwise, an appropriate error.
@@ -854,11 +1060,14 @@
      * Update a particular ADV field in the advertising payload (based on
      * matching type).
      *
-     * @param[in] type  The ADV type field describing the variable length data.
-     * @param[in] data  Data bytes.
-     * @param[in] len   Length of data.
+     * @param[in] type
+     *              The ADV type field describing the variable length data.
+     * @param[in] data
+     *              Data bytes.
+     * @param[in] len
+     *              Length of data.
      *
-     * @note: If advertisements are enabled, then the update will take effect immediately.
+     * @note  If advertisements are enabled, then the update will take effect immediately.
      *
      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
      *         matching AD type; otherwise, an appropriate error.
@@ -879,7 +1088,15 @@
     /**
      * Set up a particular, user-constructed advertisement payload for the
      * underlying stack. It would be uncommon for this API to be used directly;
-     * there are other APIs to build an advertisement payload (see above).
+     * there are other APIs to build an advertisement payload (refer to
+     * Gap::accumulateAdvertisingPayload()).
+     *
+     * @param[in]   payload
+     *                  A reference to a user constructed advertisement
+     *                  payload.
+     *
+     * @return BLE_ERROR_NONE if the advertisement payload was successfully
+     *         set.
      */
     ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
         _advPayload = payload;
@@ -887,8 +1104,11 @@
     }
 
     /**
-     * @return  Read back advertising data. Useful for storing and
-     *          restoring payload.
+     * Get a reference to the advertising payload.
+     *
+     * @return  Read back advertising data.
+     *
+     * @note Useful for storing and restoring payload.
      */
     const GapAdvertisingData &getAdvertisingPayload(void) const {
         return _advPayload;
@@ -898,9 +1118,15 @@
      * Accumulate a variable length byte-stream as an AD structure in the
      * scanResponse payload.
      *
-     * @param[in] type The type describing the variable length data.
-     * @param[in] data Data bytes.
-     * @param[in] len  Length of data.
+     * @param[in] type
+     *              The type describing the variable length data.
+     * @param[in] data
+     *              Data bytes.
+     * @param[in] len
+     *              Length of data.
+     *
+     * @return BLE_ERROR_NONE if the data was successfully added to the scan
+     *         response payload.
      */
     ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         ble_error_t rc;
@@ -913,10 +1139,10 @@
 
     /**
      * Reset any scan response prepared from prior calls to
-     * accumulateScanResponse().
+     * Gap::accumulateScanResponse().
      *
-     * Note: This should be followed by a call to setAdvertisingPayload() or
-     * startAdvertising() before the update takes effect.
+     * @note This should be followed by a call to Gap::setAdvertisingPayload() or
+     *       Gap::startAdvertising() before the update takes effect.
      */
     void clearScanResponse(void) {
         _scanResponse.clear();
@@ -925,6 +1151,7 @@
 
     /**
      * Set up parameters for GAP scanning (observer mode).
+     *
      * @param[in] interval
      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      * @param[in] window
@@ -935,17 +1162,19 @@
      *              Set to True if active-scanning is required. This is used to fetch the
      *              scan response from a peer if possible.
      *
-     * The scanning window divided by the interval determines the duty cycle for
-     * scanning. For example, if the interval is 100ms and the window is 10ms,
-     * then the controller will scan for 10 percent of the time. It is possible
-     * to have the interval and window set to the same value. In this case,
-     * scanning is continuous, with a change of scanning frequency once every
-     * interval.
+     * @return BLE_ERROR_NONE if the scan parameters were correctly set.
      *
-     * Once the scanning parameters have been configured, scanning can be
-     * enabled by using startScan().
+     * @note The scanning window divided by the interval determines the duty cycle for
+     *       scanning. For example, if the interval is 100ms and the window is 10ms,
+     *       then the controller will scan for 10 percent of the time. It is possible
+     *       to have the interval and window set to the same value. In this case,
+     *       scanning is continuous, with a change of scanning frequency once every
+     *       interval.
      *
-     * @Note: The scan interval and window are recommendations to the BLE stack.
+     * @note Once the scanning parameters have been configured, scanning can be
+     *       enabled by using startScan().
+     *
+     * @note  The scan interval and window are recommendations to the BLE stack.
      */
     ble_error_t setScanParams(uint16_t interval       = GapScanningParams::SCAN_INTERVAL_MAX,
                               uint16_t window         = GapScanningParams::SCAN_WINDOW_MAX,
@@ -964,18 +1193,21 @@
 
     /**
      * Set up the scanInterval parameter for GAP scanning (observer mode).
+     *
      * @param[in] interval
      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      *
-     * The scanning window divided by the interval determines the duty cycle for
-     * scanning. For example, if the interval is 100ms and the window is 10ms,
-     * then the controller will scan for 10 percent of the time. It is possible
-     * to have the interval and window set to the same value. In this case,
-     * scanning is continuous, with a change of scanning frequency once every
-     * interval.
+     * @return BLE_ERROR_NONE if the scan interval was correctly set.
      *
-     * Once the scanning parameters have been configured, scanning can be
-     * enabled by using startScan().
+     * @note The scanning window divided by the interval determines the duty cycle for
+     *       scanning. For example, if the interval is 100ms and the window is 10ms,
+     *       then the controller will scan for 10 percent of the time. It is possible
+     *       to have the interval and window set to the same value. In this case,
+     *       scanning is continuous, with a change of scanning frequency once every
+     *       interval.
+     *
+     * @note Once the scanning parameters have been configured, scanning can be
+     *       enabled by using startScan().
      */
     ble_error_t setScanInterval(uint16_t interval) {
         return _scanningParams.setInterval(interval);
@@ -983,21 +1215,24 @@
 
     /**
      * Set up the scanWindow parameter for GAP scanning (observer mode).
+     *
      * @param[in] window
      *              Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
      *
-     * The scanning window divided by the interval determines the duty cycle for
-     * scanning. For example, if the interval is 100ms and the window is 10ms,
-     * then the controller will scan for 10 percent of the time. It is possible
-     * to have the interval and window set to the same value. In this case,
-     * scanning is continuous, with a change of scanning frequency once every
-     * interval.
+     * @return BLE_ERROR_NONE if the scan window was correctly set.
      *
-     * Once the scanning parameters have been configured, scanning can be
-     * enabled by using startScan().
+     * @note The scanning window divided by the interval determines the duty cycle for
+     *       scanning. For example, if the interval is 100ms and the window is 10ms,
+     *       then the controller will scan for 10 percent of the time. It is possible
+     *       to have the interval and window set to the same value. In this case,
+     *       scanning is continuous, with a change of scanning frequency once every
+     *       interval.
      *
-     * If scanning is already active, the updated value of scanWindow will be
-     * propagated to the underlying BLE stack.
+     * @note Once the scanning parameters have been configured, scanning can be
+     *       enabled by using startScan().
+     *
+     * @note If scanning is already active, the updated value of scanWindow will be
+     *       propagated to the underlying BLE stack.
      */
     ble_error_t setScanWindow(uint16_t window) {
         ble_error_t rc;
@@ -1015,14 +1250,17 @@
 
     /**
      * Set up parameters for GAP scanning (observer mode).
+     *
      * @param[in] timeout
      *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
      *
-     * Once the scanning parameters have been configured, scanning can be
-     * enabled by using startScan().
+     * @return BLE_ERROR_NONE if the scan timeout was correctly set.
      *
-     * If scanning is already active, the updated value of scanTimeout will be
-     * propagated to the underlying BLE stack.
+     * @note Once the scanning parameters have been configured, scanning can be
+     *       enabled by using startScan().
+     *
+     * @note If scanning is already active, the updated value of scanTimeout will be
+     *       propagated to the underlying BLE stack.
      */
     ble_error_t setScanTimeout(uint16_t timeout) {
         ble_error_t rc;
@@ -1039,16 +1277,19 @@
     }
 
     /**
-     * Set up parameters for GAP scanning (observer mode).
+     * Modify the active scanning parameter for GAP scanning (observer mode).
+     * This is used to fetch the scan response from a peer if possible.
+     *
      * @param[in] activeScanning
-     *              Set to True if active-scanning is required. This is used to fetch the
-     *              scan response from a peer if possible.
+     *              Set to True if active-scanning is required.
      *
-     * Once the scanning parameters have been configured, scanning can be
-     * enabled by using startScan().
+     * @return BLE_ERROR_NONE if active scanning was successfully set.
      *
-     * If scanning is already in progress, then active-scanning will be enabled
-     * for the underlying BLE stack.
+     * @note Once the scanning parameters have been configured, scanning can be
+     *       enabled by using startScan().
+     *
+     * @note If scanning is already in progress, then active-scanning will be enabled
+     *       for the underlying BLE stack.
      */
     ble_error_t setActiveScanning(bool activeScanning) {
         _scanningParams.setActiveScanning(activeScanning);
@@ -1069,6 +1310,9 @@
      *              The application-specific callback to be invoked upon
      *              receiving every advertisement report. This can be passed in
      *              as NULL, in which case scanning may not be enabled at all.
+     *
+     * @return BLE_ERROR_NONE if the device successfully started the scan
+     *         procedure.
      */
     ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
         ble_error_t err = BLE_ERROR_NONE;
@@ -1083,7 +1327,19 @@
     }
 
     /**
-     * Same as above, but this takes an (object, method) pair for a callback.
+     * Same as Gap::startScan(), but allows the possibility to add an object
+     * reference and member function as handler for advertisement event
+     * callbacks.
+     *
+     * @param[in] object
+     *              Pointer to the object of a class defining the member callback
+     *              function (@p callbackMember).
+     * @param[in] callbackMember
+     *              The member callback (within the context of an object) to be
+     *              invoked.
+     *
+     * @return BLE_ERROR_NONE if the device successfully started the scan
+     *         procedure.
      */
     template<typename T>
     ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
@@ -1120,21 +1376,58 @@
     }
 
 private:
+    /**
+     * Helper function used to set the advertising data in the underlying BLE stack.
+     *
+     * @return BLE_ERROR_NONE if the advertising data was successfully set.
+     */
     ble_error_t setAdvertisingData(void) {
         return setAdvertisingData(_advPayload, _scanResponse);
     }
 
 private:
+    /**
+     * Functionality that is BLE stack-dependent and must be implemented by the
+     * ported. This is a helper function to set the advertising data in the
+     * BLE stack.
+     *
+     * @param[in] advData
+     *              The new advertising data.
+     * @param[in] scanResponse
+     *              The new scan response data.
+     *
+     * @return BLE_ERROR_NONE if the advertising data was set successfully.
+     */
     virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
+
+    /**
+     * Functionality that is BLE stack-dependent and must be implemented by the
+     * ported. This is a helper function to start the advertising procedure in
+     * the underlying BLE stack.
+     *
+     * @param[in]
+     *              The advertising parameters.
+     *
+     * @return BLE_ERROR_NONE if the advertising procedure was successfully
+     *         started.
+     */
     virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
 
 public:
     /**
-     * Accessors to read back currently active advertising params.
+     * Accessor to read back currently active advertising parameters.
+     *
+     * @return A reference to the current advertising parameters.
      */
     GapAdvertisingParams &getAdvertisingParams(void) {
         return _advParams;
     }
+
+    /**
+     * A const alternative to Gap::getAdvertisingParams().
+     *
+     * @return A const reference to the current advertising parameters.
+     */
     const GapAdvertisingParams &getAdvertisingParams(void) const {
         return _advParams;
     }
@@ -1144,6 +1437,9 @@
      * the underlying stack. It would be uncommon for this API to be used
      * directly; there are other APIs to tweak advertisement parameters
      * individually.
+     *
+     * @param[in]   newParams
+     *                  The new advertising parameters.
      */
     void setAdvertisingParams(const GapAdvertisingParams &newParams) {
         _advParams = newParams;
@@ -1154,17 +1450,24 @@
     /**
      * Set up a callback for timeout events. Refer to TimeoutSource_t for
      * possible event types.
-     * @note It is possible to unregister callbacks using onTimeout().detach(callback)
+     *
+     * @param[in] callback
+     *              Event handler being registered.
+     *
+     * @note It is possible to unregister callbacks using onTimeout().detach(callback).
      */
     void onTimeout(TimeoutEventCallback_t callback) {
         timeoutCallbackChain.add(callback);
     }
 
     /**
-     * @brief provide access to the callchain of timeout event callbacks
-     * It is possible to register callbacks using onTimeout().add(callback);
-     * It is possible to unregister callbacks using onTimeout().detach(callback)
-     * @return The timeout event callbacks chain
+     * @brief Provide access to the callchain of timeout event callbacks.
+     *
+     * @note It is possible to register callbacks using onTimeout().add(callback).
+     *
+     * @note It is possible to unregister callbacks using onTimeout().detach(callback).
+     *
+     * @return A reference to the timeout event callbacks chain.
      */
     TimeoutEventCallbackChain_t& onTimeout() {
         return timeoutCallbackChain;
@@ -1172,18 +1475,41 @@
 
     /**
      * Append to a chain of callbacks to be invoked upon GAP connection.
+     *
+     * @param[in] callback
+     *              Event handler being registered.
+     *
      * @note It is possible to unregister callbacks using onConnection().detach(callback)
      */
-    void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
-
-    template<typename T>
-    void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
+    void onConnection(ConnectionEventCallback_t callback) {
+        connectionCallChain.add(callback);
+    }
 
     /**
-     * @brief provide access to the callchain of connection event callbacks
-     * It is possible to register callbacks using onConnection().add(callback);
-     * It is possible to unregister callbacks using onConnection().detach(callback)
-     * @return The connection event callbacks chain
+     * Same as Gap::onConnection(), but allows the possibility to add an object
+     * reference and member function as handler for connection event
+     * callbacks.
+     *
+     * @param[in] tptr
+     *              Pointer to the object of a class defining the member callback
+     *              function (@p mptr).
+     * @param[in] mptr
+     *              The member callback (within the context of an object) to be
+     *              invoked.
+     */
+    template<typename T>
+    void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {
+        connectionCallChain.add(tptr, mptr);
+    }
+
+    /**
+     * @brief Provide access to the callchain of connection event callbacks.
+     *
+     * @return A reference to the connection event callbacks chain.
+     *
+     * @note It is possible to register callbacks using onConnection().add(callback).
+     *
+     * @note It is possible to unregister callbacks using onConnection().detach(callback).
      */
     ConnectionEventCallbackChain_t& onConnection() {
         return connectionCallChain;
@@ -1191,18 +1517,41 @@
 
     /**
      * Append to a chain of callbacks to be invoked upon GAP disconnection.
-     * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
+     *
+     * @param[in] callback
+                    Event handler being registered.
+     *
+     * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
      */
-    void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
-
-    template<typename T>
-    void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
+    void onDisconnection(DisconnectionEventCallback_t callback) {
+        disconnectionCallChain.add(callback);
+    }
 
     /**
-     * @brief provide access to the callchain of disconnection event callbacks
-     * It is possible to register callbacks using onDisconnection().add(callback);
-     * It is possible to unregister callbacks using onDisconnection().detach(callback)
-     * @return The disconnection event callbacks chain
+     * Same as Gap::onDisconnection(), but allows the possibility to add an object
+     * reference and member function as handler for disconnection event
+     * callbacks.
+     *
+     * @param[in] tptr
+     *              Pointer to the object of a class defining the member callback
+     *              function (@p mptr).
+     * @param[in] mptr
+     *              The member callback (within the context of an object) to be
+     *              invoked.
+     */
+    template<typename T>
+    void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {
+        disconnectionCallChain.add(tptr, mptr);
+    }
+
+    /**
+     * @brief Provide access to the callchain of disconnection event callbacks.
+     *
+     * @return A reference to the disconnection event callback chain.
+     *
+     * @note It is possible to register callbacks using onDisconnection().add(callback).
+     *
+     * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
      */
     DisconnectionEventCallbackChain_t& onDisconnection() {
         return disconnectionCallChain;
@@ -1222,22 +1571,26 @@
      * devices, to manage peak current drawn during periods when the radio is on,
      * or to trigger sensor data collection for transmission in the Radio Event.
      *
-     * @param callback
-     *          The application handler to be invoked in response to a radio
-     *          ACTIVE/INACTIVE event.
-     *
-     * Or in the other version:
-     *
-     * @param tptr
-     *          Pointer to the object of a class defining the member callback
-     *          function (mptr).
-     * @param mptr
-     *          The member callback (within the context of an object) to be
-     *          invoked in response to a radio ACTIVE/INACTIVE event.
+     * @param[in] callback
+     *              The application handler to be invoked in response to a radio
+     *              ACTIVE/INACTIVE event.
      */
     void onRadioNotification(void (*callback)(bool param)) {
         radioNotificationCallback.attach(callback);
     }
+
+    /**
+     * Same as Gap::onRadioNotification(), but allows the posibility to
+     * register an object reference and member function as handler for radio
+     * notification events.
+     *
+     * @param[in] tptr
+     *              Pointer to the object of a class defining the member callback
+     *              function (@p mptr).
+     * @param[in] mptr
+     *              The member callback (within the context of an object) to be
+     *              invoked in response to a radio ACTIVE/INACTIVE event.
+     */
     template <typename T>
     void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
         radioNotificationCallback.attach(tptr, mptr);
@@ -1248,28 +1601,48 @@
      * Gap instance is about to shutdown (possibly as a result of a call
      * to BLE::shutdown()).
      *
-     * @Note: It is possible to chain together multiple onShutdown callbacks
+     * @param[in] callback
+     *              The handler that is being registered to be notified of
+     *              shutdown events.
+     *
+     * @note  It is possible to chain together multiple onShutdown callbacks
      * (potentially from different modules of an application) to be notified
      * before the Gap instance is shutdown.
      *
-     * @Note: It is also possible to set up a callback into a member function of
+     * @note  It is also possible to set up a callback into a member function of
      * some object.
      *
-     * @Note It is possible to unregister a callback using onShutdown().detach(callback)
+     * @note It is possible to unregister a callback using onShutdown().detach(callback)
      */
     void onShutdown(const GapShutdownCallback_t& callback) {
         shutdownCallChain.add(callback);
     }
+
+    /**
+     * Same as Gap::onShutdown(), but allows the posibility to
+     * register an object reference and member function as handler for shutdown
+     * events.
+     *
+     * @param[in] objPtr
+     *              Pointer to the object of a class defining the member callback
+     *              function (@p memberPtr).
+     * @param[in] memberPtr
+     *              The member callback (within the context of an object) to be
+     *              invoked in response to a shutdown event.
+     */
     template <typename T>
     void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
         shutdownCallChain.add(objPtr, memberPtr);
     }
 
     /**
-     * @brief provide access to the callchain of shutdown event callbacks
-     * It is possible to register callbacks using onShutdown().add(callback);
-     * It is possible to unregister callbacks using onShutdown().detach(callback)
-     * @return The shutdown event callbacks chain
+     * @brief Provide access to the callchain of shutdown event callbacks.
+     *
+     * @return A reference to the shutdown event callback chain.
+     *
+     * @note It is possible to register callbacks using onShutdown().add(callback).
+     *
+     * @note It is possible to unregister callbacks using onShutdown().detach(callback).
      */
     GapShutdownCallbackChain_t& onShutdown() {
         return shutdownCallChain;
@@ -1288,7 +1661,7 @@
      *
      * @return BLE_ERROR_NONE on success.
      *
-     * @note: Currently a call to reset() does not reset the advertising and
+     * @note  Currently a call to reset() does not reset the advertising and
      * scan parameters to default values.
      */
     virtual ble_error_t reset(void) {
@@ -1319,6 +1692,9 @@
     }
 
 protected:
+    /**
+     * Construct a Gap instance.
+     */
     Gap() :
         _advParams(),
         _advPayload(),
@@ -1338,6 +1714,26 @@
 
     /* Entry points for the underlying stack to report events back to the user. */
 public:
+    /**
+     * Helper function that notifies all registered handlers of an occurrence
+     * of a connection event. This function is meant to be called from the
+     * BLE stack specific implementation when a connection event occurs.
+     *
+     * @param[in] handle
+     *              The ID of the connection that generated the event.
+     * @param[in] role
+     *              The role of this BLE device in the connection.
+     * @param[in] peerAddrType
+     *              The peer's BLE address type.
+     * @param[in] peerAddr
+     *              The peer's BLE address.
+     * @param[in] ownAddrType
+     *              This device's BLE address type.
+     * @param[in] ownAddr
+     *              This device's BLE address.
+     * @param[in] connectionParams
+     *              The parameters configured for this connection.
+     */
     void processConnectionEvent(Handle_t                           handle,
                                 Role_t                             role,
                                 BLEProtocol::AddressType_t         peerAddrType,
@@ -1354,6 +1750,16 @@
         connectionCallChain.call(&callbackParams);
     }
 
+    /**
+     * Helper function that notifies all registered handlers of an occurrence
+     * of a disconnection event. This function is meant to be called from the
+     * BLE stack specific implementation when a disconnection event occurs.
+     *
+     * @param[in] handle
+     *              The ID of the connection that generated the event.
+     * @param[in] reason
+     *              The reason for disconnection.
+     */
     void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
         /* Update Gap state */
         --connectionCount;
@@ -1365,6 +1771,24 @@
         disconnectionCallChain.call(&callbackParams);
     }
 
+    /**
+     * Helper function that notifies the registered handler of a scanned
+     * advertisement packet. This function is meant to be called from the
+     * BLE stack specific implementation when a such event occurs.
+     *
+     * @param[in] peerAddr
+     *              The peer's BLE address.
+     * @param[in] rssi
+     *              The advertisement packet RSSI value.
+     * @param[in] isScanReponse
+     *              Whether this packet is the response to a scan request.
+     * @param[in] type
+     *              The type of advertisement.
+     * @param[in] advertisingDataLen
+     *              Length of the advertisement data.
+     * @param[in] advertisingData
+     *              Pointer to the advertisement packet's data.
+     */
     void processAdvertisementReport(const BLEProtocol::AddressBytes_t        peerAddr,
                                     int8_t                                   rssi,
                                     bool                                     isScanResponse,
@@ -1381,6 +1805,14 @@
         onAdvertisementReport.call(&params);
     }
 
+    /**
+     * Helper function that notifies all registered handlers of an occurrence
+     * of a timeout event. This function is meant to be called from the
+     * BLE stack specific implementation when a timeout event occurs.
+     *
+     * @param[in] source
+     *              The source of the timout event.
+     */
     void processTimeoutEvent(TimeoutSource_t source) {
         if (source == TIMEOUT_SRC_ADVERTISING) {
             /* Update gap state if the source is an advertising timeout */
@@ -1392,26 +1824,68 @@
     }
 
 protected:
+    /**
+     * Currently set advertising parameters.
+     */
     GapAdvertisingParams             _advParams;
+    /**
+     * Currently set advertising data.
+     */
     GapAdvertisingData               _advPayload;
+    /**
+     * Currently set scanning parameters.
+     */
     GapScanningParams                _scanningParams;
+    /**
+     * Currently set scan response data.
+     */
     GapAdvertisingData               _scanResponse;
 
     /**
      * Total number of open connections.
      */
     uint8_t                          connectionCount;
+    /**
+     * The current GAP state.
+     */
     GapState_t                       state;
+    /**
+     * Whether active scanning is set. This is used to fetch the scan response
+     * from a peer if possible.
+     */
     bool                             scanningActive;
 
 protected:
+    /**
+     * Callchain containing all registered callback handlers for timeout
+     * events.
+     */
     TimeoutEventCallbackChain_t       timeoutCallbackChain;
+    /**
+     * The registered callback handler for radio notification events.
+     */
     RadioNotificationEventCallback_t  radioNotificationCallback;
+    /**
+     * The registered callback handler for scanned advertisement packet
+     * notifications.
+     */
     AdvertisementReportCallback_t     onAdvertisementReport;
+    /**
+     * Callchain containing all registered callback handlers for connection
+     * events.
+     */
     ConnectionEventCallbackChain_t    connectionCallChain;
+    /**
+     * Callchain containing all registered callback handlers for disconnection
+     * events.
+     */
     DisconnectionEventCallbackChain_t disconnectionCallChain;
 
 private:
+    /**
+     * Callchain containing all registered callback handlers for shutdown
+     * events.
+     */
     GapShutdownCallbackChain_t shutdownCallChain;
 
 private: