Bluetooth: doc: Fix detailed API description rendered into text boxes

Fix detailed API description rendered into text boxes.
API documentation with more that one paragraph must use the @brief tag
to be rendered correctly.
Fix indentation level of '*' in doxygen documentation.

Signed-off-by: Joakim Andersson <joakim.andersson@nordicsemi.no>
This commit is contained in:
Joakim Andersson 2020-04-28 19:47:46 +02:00 committed by Carles Cufí
commit 89d1bbc639
5 changed files with 111 additions and 103 deletions

View file

@ -262,9 +262,9 @@ int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk);
*/
int bt_id_delete(u8_t id);
/** Advertising API */
/** Description of different data types that can be encoded into
/** @brief Bluetooth data.
*
* Description of different data types that can be encoded into
* advertising data. Used to form arrays that are passed to the
* bt_le_adv_start() function.
*/
@ -307,14 +307,18 @@ enum {
/** Convenience value when no options are specified. */
BT_LE_ADV_OPT_NONE = 0,
/** Advertise as connectable. If not connectable then the type of
/** @brief Advertise as connectable.
*
* Advertise as connectable. If not connectable then the type of
* advertising is determined by providing scan response data.
* The advertiser address is determined by the type of advertising
* and/or enabling privacy :option:`CONFIG_BT_PRIVACY`.
*/
BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
/** Don't try to resume connectable advertising after a connection.
/** @brief Advertise one time.
*
* Don't try to resume connectable advertising after a connection.
* This option is only meaningful when used together with
* BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped
* when bt_le_adv_stop() is called or when an incoming (slave)
@ -326,7 +330,9 @@ enum {
*/
BT_LE_ADV_OPT_ONE_TIME = BIT(1),
/** Advertise using the identity address as the advertiser address.
/** @brief Advertise using identity address.
*
* Advertise using the identity address as the advertiser address.
* @warning This will compromise the privacy of the device, so care
* must be taken when using this option.
* @note The address used for advertising will not be the same as
@ -338,12 +344,16 @@ enum {
/** Advertise using GAP device name */
BT_LE_ADV_OPT_USE_NAME = BIT(3),
/** Use low duty directed advertising mode, otherwise high duty mode
/** @brief Low duty cycle directed advertising.
*
* Use low duty directed advertising mode, otherwise high duty mode
* will be used.
*/
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4),
/** Enable use of Resolvable Private Address (RPA) as the target address
/** @brief Directed advertising to privacy-enabled peer.
*
* Enable use of Resolvable Private Address (RPA) as the target address
* in directed advertisements when :option:`CONFIG_BT_PRIVACY` is not
* enabled.
* This is required if the remote device is privacy-enabled and
@ -355,8 +365,7 @@ enum {
*/
BT_LE_ADV_OPT_DIR_ADDR_RPA = BIT(5),
/** Use whitelist to filter devices that can request scan response
* data.
/** Use whitelist to filter devices that can request scan response data.
*/
BT_LE_ADV_OPT_FILTER_SCAN_REQ = BIT(6),
@ -368,7 +377,7 @@ enum {
*/
BT_LE_ADV_OPT_NOTIFY_SCAN_REQ = BIT(8),
/** Support scan response data.
/** @brief Support scan response data.
*
* When used together with @ref BT_LE_ADV_OPT_EXT_ADV then this option
* cannot be used together with the @ref BT_LE_ADV_OPT_CONNECTABLE
@ -378,7 +387,7 @@ enum {
*/
BT_LE_ADV_OPT_SCANNABLE = BIT(9),
/** Advertise with extended advertising.
/** @brief Advertise with extended advertising.
*
* This options enables extended advertising in the advertising set.
* In extended advertising the advertising set will send a small header
@ -396,7 +405,8 @@ enum {
*/
BT_LE_ADV_OPT_EXT_ADV = BIT(10),
/** Disable use of LE 2M PHY on the secondary advertising channel.
/** @brief Disable use of LE 2M PHY on the secondary advertising
* channel.
*
* Disabling the use of LE 2M PHY could be necessary if scanners don't
* support the LE 2M PHY.
@ -409,7 +419,7 @@ enum {
*/
BT_LE_ADV_OPT_NO_2M = BIT(11),
/** Advertise on the LE Coded PHY (Long Range).
/** @brief Advertise on the LE Coded PHY (Long Range).
*
* The advertiser will send both primary and secondary advertising
* on the LE Coded PHY. This gives the advertiser increased range with
@ -419,13 +429,13 @@ enum {
*/
BT_LE_ADV_OPT_CODED = BIT(12),
/** Advertise without a device address (identity or RPA).
/** @brief Advertise without a device address (identity or RPA).
*
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
*/
BT_LE_ADV_OPT_ANONYMOUS = BIT(13),
/** Advertise with transmit power.
/** @brief Advertise with transmit power.
*
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
*/
@ -434,7 +444,7 @@ enum {
/** LE Advertising Parameters. */
struct bt_le_adv_param {
/** Local identity.
/** @brief Local identity.
*
* @note When extended advertising :option:`CONFIG_BT_EXT_ADV` is not
* enabled or not supported by the controller it is not possible
@ -446,13 +456,15 @@ struct bt_le_adv_param {
*/
u8_t id;
/** Advertising Set Identifier, valid range 0x00 - 0x0f.
/** @brief Advertising Set Identifier, valid range 0x00 - 0x0f.
*
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
**/
u8_t sid;
/** Maximum advertising events the advertiser can skip before it must
/** @brief Secondary channel maximum skip count.
*
* Maximum advertising events the advertiser can skip before it must
* send advertising data on the secondary advertising channel.
*
* @note Requires @ref BT_LE_ADV_OPT_EXT_ADV
@ -468,7 +480,7 @@ struct bt_le_adv_param {
/** Maximum Advertising Interval (N * 0.625) */
u32_t interval_max;
/** Directed advertising to peer
/** @brief Directed advertising to peer
*
* When this parameter is set the advertiser will send directed
* advertising to the remote device.
@ -483,7 +495,7 @@ struct bt_le_adv_param {
const bt_addr_le_t *peer;
};
/** Helper to declare advertising parameters inline
/** @brief Helper to declare advertising parameters inline
*
* @param _options Advertising Options
* @param _int_min Minimum advertising interval
@ -599,7 +611,7 @@ int bt_le_ext_adv_create(const struct bt_le_adv_param *param,
struct bt_le_ext_adv **adv);
struct bt_le_ext_adv_start_param {
/** Advertiser timeout (N * 10 ms).
/** @brief Advertiser timeout (N * 10 ms).
*
* Application will be notified by the advertiser sent callback.
* Set to zero for no timeout.
@ -612,7 +624,7 @@ struct bt_le_ext_adv_start_param {
* must be less than :option:`CONFIG_BT_RPA_TIMEOUT`.
*/
u16_t timeout;
/** Number of advertising events.
/** @brief Number of advertising events.
*
* Application will be notified by the advertiser sent callback.
* Set to zero for no limit.
@ -620,7 +632,7 @@ struct bt_le_ext_adv_start_param {
u8_t num_events;
};
/** Start advertising with the given advertising set
/** @brief Start advertising with the given advertising set
*
* If the advertiser is limited by either the timeout or number of advertising
* events the application will be notified by the advertiser sent callback once
@ -635,7 +647,7 @@ struct bt_le_ext_adv_start_param {
int bt_le_ext_adv_start(struct bt_le_ext_adv *adv,
struct bt_le_ext_adv_start_param *param);
/** Stop advertising with the given advertising set
/** @brief Stop advertising with the given advertising set
*
* Stop advertising with a specific advertising set. When using this function
* the advertising sent callback will not be called.
@ -646,7 +658,7 @@ int bt_le_ext_adv_start(struct bt_le_ext_adv *adv,
*/
int bt_le_ext_adv_stop(struct bt_le_ext_adv *adv);
/** Set an advertising set's advertising or scan response data.
/** @brief Set an advertising set's advertising or scan response data.
*
* Set advertisement data or scan response data. If the advertising set is
* currently advertising then the advertising data will be updated in
@ -692,7 +704,7 @@ int bt_le_ext_adv_set_data(struct bt_le_ext_adv *adv,
int bt_le_ext_adv_update_param(struct bt_le_ext_adv *adv,
const struct bt_le_adv_param *param);
/** Delete advertising set.
/** @brief Delete advertising set.
*
* Delete advertising set. This will free up the advertising set and make it
* possible to create a new advertising set.
@ -759,7 +771,7 @@ enum {
/** Enable scan on coded PHY (Long Range).*/
BT_LE_SCAN_OPT_CODED = BIT(2),
/** Disable scan on 1M phy.
/** @brief Disable scan on 1M phy.
*
* @note Requires @ref BT_LE_SCAN_OPT_CODED.
*/
@ -798,20 +810,20 @@ struct bt_le_scan_param {
/** Scan window (N * 0.625 ms) */
u16_t window;
/** Scan timeout (N * 10 ms)
/** @brief Scan timeout (N * 10 ms)
*
* Application will be notified by the scan timeout callback.
* Set zero to disable timeout.
*/
u16_t timeout;
/** Scan interval LE Coded PHY (N * 0.625 MS)
/** @brief Scan interval LE Coded PHY (N * 0.625 MS)
*
* Set zero to use same as LE 1M PHY scan interval.
*/
u16_t interval_coded;
/** Scan window LE Coded PHY (N * 0.625 MS)
/** @brief Scan window LE Coded PHY (N * 0.625 MS)
*
* Set zero to use same as LE 1M PHY scan window.
*/
@ -820,14 +832,14 @@ struct bt_le_scan_param {
/** LE advertisement packet information */
struct bt_le_scan_recv_info {
/** Advertiser LE address and type.
/** @brief Advertiser LE address and type.
*
* If advertiser is anonymous then this address will be
* @ref BT_ADDR_LE_ANY.
*/
const bt_addr_le_t *addr;
/* Advertising Set Identifier. */
/** Advertising Set Identifier. */
u8_t sid;
/** Strength of advertiser signal. */
@ -842,10 +854,10 @@ struct bt_le_scan_recv_info {
/** Advertising packet properties. */
u16_t adv_props;
/* Primary advertising channel PHY. */
/** Primary advertising channel PHY. */
u8_t primary_phy;
/* Secondary advertising channel PHY. */
/** Secondary advertising channel PHY. */
u8_t secondary_phy;
};
@ -866,7 +878,7 @@ struct bt_le_scan_cb {
sys_snode_t node;
};
/** Helper to declare scan parameters inline
/** @brief Helper to declare scan parameters inline
*
* @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
* BT_LE_SCAN_TYPE_PASSIVE.
@ -891,7 +903,7 @@ struct bt_le_scan_cb {
BT_GAP_SCAN_FAST_INTERVAL, \
BT_GAP_SCAN_FAST_WINDOW)
/** Helper macro to enable passive scanning to discover new devices.
/** @brief Helper macro to enable passive scanning to discover new devices.
*
* This macro should be used if information required for device identification
* (e.g., UUID) are known to be placed in Advertising Data.
@ -1295,14 +1307,14 @@ int bt_br_set_discoverable(bool enable);
*/
int bt_br_set_connectable(bool enable);
/** Clear pairing information.
*
* @param id Local identity (mostly just BT_ID_DEFAULT).
* @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
* devices.
*
* @return 0 on success or negative error value on failure.
*/
/** @brief Clear pairing information.
*
* @param id Local identity (mostly just BT_ID_DEFAULT).
* @param addr Remote address, NULL or BT_ADDR_LE_ANY to clear all remote
* devices.
*
* @return 0 on success or negative error value on failure.
*/
int bt_unpair(u8_t id, const bt_addr_le_t *addr);
/** Information about a bond with a remote device. */
@ -1311,12 +1323,12 @@ struct bt_bond_info {
bt_addr_le_t addr;
};
/** Iterate through all existing bonds.
*
* @param id Local identity (mostly just BT_ID_DEFAULT).
* @param func Function to call for each bond.
* @param user_data Data to pass to the callback function.
*/
/** @brief Iterate through all existing bonds.
*
* @param id Local identity (mostly just BT_ID_DEFAULT).
* @param func Function to call for each bond.
* @param user_data Data to pass to the callback function.
*/
void bt_foreach_bond(u8_t id, void (*func)(const struct bt_bond_info *info,
void *user_data),
void *user_data);

View file

@ -164,24 +164,19 @@ enum {
BT_CONN_ROLE_SLAVE,
};
/** @brief Connection Info Structure
*
* @param type Connection Type
* @param role Connection Role
* @param id Which local identity the connection was created with
* @param le LE Connection specific Info
* @param br BR/EDR Connection specific Info
*/
/** Connection Info Structure */
struct bt_conn_info {
/** Connection Type. */
u8_t type;
/** Connection Role. */
u8_t role;
/** Which local identity the connection was created with */
u8_t id;
/** Connection Type specific Info.*/
union {
/** LE Connection specific Info. */
struct bt_conn_le_info le;
/** BR/EDR Connection specific Info. */
struct bt_conn_br_info br;
};
};
@ -283,20 +278,20 @@ enum {
/** Convenience value when no options are specified. */
BT_LE_CONN_OPT_NONE = 0,
/** Enable LE Coded PHY.
/** @brief Enable LE Coded PHY.
*
* Enable scanning on the LE Coded PHY.
* Enable connection initiation on the LE Coded PHY.
*/
BT_LE_CONN_OPT_CODED = BIT(0),
/** Enable LE 2M PHY.
/** @brief Enable LE 2M PHY.
*
* Enable connection initiaton on the LE 2M PHY.
*/
BT_LE_CONN_OPT_2M = BIT(1),
/** Disable LE 1M PHY.
/** @brief Disable LE 1M PHY.
*
* Disable scanning on the LE 1M PHY.
* Disable connection initiation on the LE 1M PHY.
@ -317,19 +312,19 @@ struct bt_conn_le_create_param {
/** Scan window (N * 0.625 ms) */
u16_t window;
/** Scan interval LE Coded PHY (N * 0.625 MS)
/** @brief Scan interval LE Coded PHY (N * 0.625 MS)
*
* Set zero to use same as LE 1M PHY scan interval
*/
u16_t interval_coded;
/** Scan window LE Coded PHY (N * 0.625 MS)
/** @brief Scan window LE Coded PHY (N * 0.625 MS)
*
* Set zero to use same as LE 1M PHY scan window.
*/
u16_t window_coded;
/** Connection initiation timeout (N * 10 MS)
/** @brief Connection initiation timeout (N * 10 MS)
*
* Set zero to use the default :option:`CONFIG_BT_CREATE_CONN_TIMEOUT`
* timeout.
@ -731,7 +726,7 @@ struct bt_conn_cb {
*/
void bt_conn_cb_register(struct bt_conn_cb *cb);
/** Enable/disable bonding.
/** @brief Enable/disable bonding.
*
* Set/clear the Bonding flag in the Authentication Requirements of
* SMP Pairing Request/Response data.
@ -743,7 +738,7 @@ void bt_conn_cb_register(struct bt_conn_cb *cb);
*/
void bt_set_bondable(bool enable);
/** Allow/disallow remote OOB data to be used for pairing.
/** @brief Allow/disallow remote OOB data to be used for pairing.
*
* Set/clear the OOB data flag for SMP Pairing Request/Response data.
* The initial value of this flag depends on BT_OOB_DATA_PRESENT Kconfig

View file

@ -86,7 +86,7 @@ enum {
BT_GAP_LE_PHY_CODED = BIT(2),
};
/* Advertising PDU types */
/** Advertising PDU types */
enum {
/** Scannable and connectable advertising. */
BT_GAP_ADV_TYPE_ADV_IND = 0x00,
@ -102,7 +102,7 @@ enum {
BT_GAP_ADV_TYPE_EXT_ADV = 0x05,
};
/* Advertising PDU properties */
/** Advertising PDU properties */
enum {
/** Connectable advertising. */
BT_GAP_ADV_PROP_CONNECTABLE = BIT(0),
@ -118,7 +118,7 @@ enum {
/** Maximum advertising data length. */
#define BT_GAP_ADV_MAX_ADV_DATA_LEN 31
/** Maximum extendend advertising data length.
/** Maximum extended advertising data length.
*
* @note The maximum advertising data length that can be sent by an extended
* advertiser is defined by the controller.

View file

@ -39,33 +39,33 @@ enum {
/** Attribute write permission. */
BT_GATT_PERM_WRITE = BIT(1),
/** Attribute read permission with encryption.
/** @brief Attribute read permission with encryption.
*
* If set, requires encryption for read access.
*/
BT_GATT_PERM_READ_ENCRYPT = BIT(2),
/** Attribute write permission with encryption.
/** @brief Attribute write permission with encryption.
*
* If set, requires encryption for write access.
*/
BT_GATT_PERM_WRITE_ENCRYPT = BIT(3),
/** Attribute read permission with authentication.
/** @brief Attribute read permission with authentication.
*
* If set, requires encryption using authenticated link-key for read
* access.
*/
BT_GATT_PERM_READ_AUTHEN = BIT(4),
/** Attribute write permission with authentication.
/** @brief Attribute write permission with authentication.
*
* If set, requires encryption using authenticated link-key for write
* access.
*/
BT_GATT_PERM_WRITE_AUTHEN = BIT(5),
/** Attribute prepare write permission.
/** @brief Attribute prepare write permission.
*
* If set, allows prepare writes with use of BT_GATT_WRITE_FLAG_PREPARE
* passed to write callback.
@ -84,14 +84,14 @@ enum {
/** GATT attribute write flags */
enum {
/** Attribute prepare write flag
/** @brief Attribute prepare write flag
*
* If set, write callback should only check if the device is
* authorized but no data shall be written.
*/
BT_GATT_WRITE_FLAG_PREPARE = BIT(0),
/** Attribute write command flag
/** @brief Attribute write command flag
*
* If set, indicates that write operation is a command (Write without
* response) which doesn't generate any response.
@ -104,7 +104,7 @@ struct bt_gatt_attr {
/** Attribute UUID */
const struct bt_uuid *uuid;
/** Attribute read callback
/** @brief Attribute read callback
*
* The callback can also be used locally to read the contents of the
* attribute in which case no connection will be set.
@ -123,7 +123,7 @@ struct bt_gatt_attr {
void *buf, u16_t len,
u16_t offset);
/** Attribute write callback
/** @brief Attribute write callback
*
* The callback can also be used locally to read the contents of the
* attribute in which case no connection will be set.
@ -584,14 +584,14 @@ struct _bt_gatt_ccc {
/** Highest value of all connected peer's subscriptions */
u16_t value;
/** CCC attribute changed callback
/** @brief CCC attribute changed callback
*
* @param attr The attribute that's changed value
* @param value New value
*/
void (*cfg_changed)(const struct bt_gatt_attr *attr, u16_t value);
/** CCC attribute write validation callback
/** @brief CCC attribute write validation callback
*
* @param conn The connection that is requesting to write
* @param attr The attribute that's being written
@ -603,7 +603,7 @@ struct _bt_gatt_ccc {
ssize_t (*cfg_write)(struct bt_conn *conn,
const struct bt_gatt_attr *attr, u16_t value);
/** CCC attribute match handler
/** @brief CCC attribute match handler
*
* Indicate if it is OK to send a notification or indication
* to the subscriber.
@ -1053,12 +1053,12 @@ enum {
BT_GATT_DISCOVER_SECONDARY,
/** Discover Included Services. */
BT_GATT_DISCOVER_INCLUDE,
/** Discover Characteristic Values.
/** @brief Discover Characteristic Values.
*
* Discover Characteristic Value and its properties.
*/
BT_GATT_DISCOVER_CHARACTERISTIC,
/** Discover Descriptors.
/** @brief Discover Descriptors.
*
* Discover Attributes which are not services or characteristics.
*
@ -1067,7 +1067,7 @@ enum {
* as it may incur in extra round trips.
*/
BT_GATT_DISCOVER_DESCRIPTOR,
/** Discover Attributes.
/** @brief Discover Attributes.
*
* Discover Attributes of any type.
*
@ -1309,7 +1309,7 @@ typedef u8_t (*bt_gatt_notify_func_t)(struct bt_conn *conn,
/** Subscription flags */
enum {
/** Persistence flag
/** @brief Persistence flag
*
* If set, indicates that the subscription is not saved
* on the GATT server side. Therefore, upon disconnection,
@ -1320,7 +1320,7 @@ enum {
*/
BT_GATT_SUBSCRIBE_FLAG_VOLATILE,
/** No resubscribe flag
/** @brief No resubscribe flag
*
* By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the
* subscription will be automatically renewed when the client
@ -1334,7 +1334,7 @@ enum {
*/
BT_GATT_SUBSCRIBE_FLAG_NO_RESUB,
/** Write pending flag
/** @brief Write pending flag
*
* If set, indicates write operation is pending waiting remote end to
* respond.

View file

@ -31,7 +31,7 @@ extern "C" {
/** @def BT_L2CAP_BUF_SIZE
*
* Helper to calculate needed outgoing buffer size, useful e.g. for
* @brief Helper to calculate needed outgoing buffer size, useful e.g. for
* creating buffer pools.
*
* @param mtu Needed L2CAP MTU.
@ -75,7 +75,7 @@ typedef enum bt_l2cap_chan_status {
/** Channel output status */
BT_L2CAP_STATUS_OUT,
/** Channel shutdown status
/** @brief Channel shutdown status
*
* Once this status is notified it means the channel will no longer be
* able to transmit or receive data.
@ -177,7 +177,7 @@ struct bt_l2cap_br_chan {
/** @brief L2CAP Channel operations structure. */
struct bt_l2cap_chan_ops {
/** Channel connected callback
/** @brief Channel connected callback
*
* If this callback is provided it will be called whenever the
* connection completes.
@ -186,7 +186,7 @@ struct bt_l2cap_chan_ops {
*/
void (*connected)(struct bt_l2cap_chan *chan);
/** Channel disconnected callback
/** @brief Channel disconnected callback
*
* If this callback is provided it will be called whenever the
* channel is disconnected, including when a connection gets
@ -196,7 +196,7 @@ struct bt_l2cap_chan_ops {
*/
void (*disconnected)(struct bt_l2cap_chan *chan);
/** Channel encrypt_change callback
/** @brief Channel encrypt_change callback
*
* If this callback is provided it will be called whenever the
* security level changed (indirectly link encryption done) or
@ -213,7 +213,7 @@ struct bt_l2cap_chan_ops {
*/
void (*encrypt_change)(struct bt_l2cap_chan *chan, u8_t hci_status);
/** Channel alloc_buf callback
/** @brief Channel alloc_buf callback
*
* If this callback is provided the channel will use it to allocate
* buffers to store incoming data.
@ -224,7 +224,7 @@ struct bt_l2cap_chan_ops {
*/
struct net_buf *(*alloc_buf)(struct bt_l2cap_chan *chan);
/** Channel recv callback
/** @brief Channel recv callback
*
* @param chan The channel receiving data.
* @param buf Buffer containing incoming data.
@ -239,7 +239,7 @@ struct bt_l2cap_chan_ops {
*/
int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf);
/** Channel sent callback
/** @brief Channel sent callback
*
* If this callback is provided it will be called whenever a SDU has
* been completely sent.
@ -248,7 +248,7 @@ struct bt_l2cap_chan_ops {
*/
void (*sent)(struct bt_l2cap_chan *chan);
/** Channel status callback
/** @brief Channel status callback
*
* If this callback is provided it will be called whenever the
* channel status changes.
@ -266,8 +266,9 @@ struct bt_l2cap_chan_ops {
/** @brief L2CAP Server structure. */
struct bt_l2cap_server {
/** Server PSM. Possible values:
/** @brief Server PSM.
*
* Possible values:
* 0 A dynamic value will be auto-allocated when
* bt_l2cap_server_register() is called.
*
@ -283,7 +284,7 @@ struct bt_l2cap_server {
/** Required minimim security level */
bt_security_t sec_level;
/** Server accept callback
/** @brief Server accept callback
*
* This callback is called whenever a new incoming connection requires
* authorization.