michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: doxygen: replace option alias with kconfig

Browse source 
Similar to Sphinx, @kconfig{} alias should be used in Doxygen docstring
in order to reference a Kconfig option. @option{} is still kept for
compatibility reasons.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
This commit is contained in:
Gerard Marull-Paretas 2021-06-28 17:13:40 +02:00 • committed by Anas Nashif
commit 72ab6b29bf
17 changed files with 111 additions and 108 deletions
Download patch file Download diff file Expand all files Collapse all files

28
include/bluetooth/bluetooth.h
View file

@ -130,7 +130,7 @@ typedef void (*bt_ready_cb_t)(int err);
* Enable Bluetooth. Must be the called before any calls that
* require communication with the local Bluetooth hardware.
*
* When @option{CONFIG_BT_SETTINGS} has been enabled and the application is not
* When @kconfig{CONFIG_BT_SETTINGS} has been enabled and the application is not
* managing identities of the stack itself then the application must call
* @ref settings_load() before the stack is fully enabled.
* See @ref bt_id_create() for more information.
@ -223,7 +223,7 @@ void bt_id_get(bt_addr_le_t *addrs, size_t *count);
* generate a random IRK for the identity and copy it back
* to the parameter upon return from this function (in case
* the parameter was non-NULL). If privacy
* @option{CONFIG_BT_PRIVACY} is not enabled this parameter must
* @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
* be NULL.
*
* @return Identity identifier (>= 0) in case of success, or a negative
@ -257,7 +257,7 @@ int bt_id_create(bt_addr_le_t *addr, uint8_t *irk);
* generate a random IRK for the identity and copy it back
* to the parameter upon return from this function (in case
* the parameter was non-NULL). If privacy
* @option{CONFIG_BT_PRIVACY} is not enabled this parameter must
* @kconfig{CONFIG_BT_PRIVACY} is not enabled this parameter must
* be NULL.
*
* @return Identity identifier (>= 0) in case of success, or a negative
@ -337,7 +337,7 @@ enum {
* 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}.
* and/or enabling privacy @kconfig{CONFIG_BT_PRIVACY}.
*/
BT_LE_ADV_OPT_CONNECTABLE = BIT(0),
@ -523,7 +523,7 @@ struct bt_le_adv_param {
/**
* @brief Local identity.
*
* @note When extended advertising @option{CONFIG_BT_EXT_ADV} is not
* @note When extended advertising @kconfig{CONFIG_BT_EXT_ADV} is not
* enabled or not supported by the controller it is not possible
* to scan and advertise simultaneously using two different
* random addresses.
@ -887,8 +887,8 @@ struct bt_le_ext_adv_start_param {
* this parameters must be set to a non-zero value less than or equal
* to the maximum of @ref BT_GAP_ADV_HIGH_DUTY_CYCLE_MAX_TIMEOUT.
*
* If privacy @option{CONFIG_BT_PRIVACY} is enabled then the timeout
* must be less than @option{CONFIG_BT_RPA_TIMEOUT}.
* If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled then the timeout
* must be less than @kconfig{CONFIG_BT_RPA_TIMEOUT}.
*/
uint16_t timeout;
/**
@ -1792,11 +1792,11 @@ struct bt_le_scan_cb {
* the specified callback.
*
* @note The LE scanner by default does not use the Identity Address of the
* local device when @option{CONFIG_BT_PRIVACY} is disabled. This is to
* local device when @kconfig{CONFIG_BT_PRIVACY} is disabled. This is to
* prevent the active scanner from disclosing the identity information
* when requesting additional information from advertisers.
* In order to enable directed advertiser reports then
* @option{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
* @kconfig{CONFIG_BT_SCAN_WITH_IDENTITY} must be enabled.
*
* @param param Scan parameters.
* @param cb Callback to notify scan results. May be NULL if callback
@ -1939,16 +1939,16 @@ struct bt_le_oob {
* This function allows to get local information that are useful for
* Out of Band pairing or connection creation.
*
* If privacy @option{CONFIG_BT_PRIVACY} is enabled this will result in
* If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
* generating new Resolvable Private Address (RPA) that is valid for
* @option{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used for
* @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used for
* advertising started by @ref bt_le_adv_start, active scanning and
* connection creation.
*
* @note If privacy is enabled the RPA cannot be refreshed in the following
* cases:
* - Creating a connection in progress, wait for the connected callback.
* In addition when extended advertising @option{CONFIG_BT_EXT_ADV} is
* In addition when extended advertising @kconfig{CONFIG_BT_EXT_ADV} is
* not enabled or not supported by the controller:
* - Advertiser is enabled using a Random Static Identity Address for a
* different local identity.
@ -1969,9 +1969,9 @@ int bt_le_oob_get_local(uint8_t id, struct bt_le_oob *oob);
* This function allows to get local information that are useful for
* Out of Band pairing or connection creation.
*
* If privacy @option{CONFIG_BT_PRIVACY} is enabled this will result in
* If privacy @kconfig{CONFIG_BT_PRIVACY} is enabled this will result in
* generating new Resolvable Private Address (RPA) that is valid for
* @option{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used by the
* @kconfig{CONFIG_BT_RPA_TIMEOUT} seconds. This address will be used by the
* advertising set.
*
* @note When generating OOB information for multiple advertising set all

16
include/bluetooth/conn.h
View file

@ -346,7 +346,7 @@ struct bt_conn_br_remote_info {
/** @brief Connection Remote Info Structure
*
* @note The version, manufacturer and subversion fields will only contain
* valid data if @option{CONFIG_BT_REMOTE_VERSION} is enabled.
* valid data if @kconfig{CONFIG_BT_REMOTE_VERSION} is enabled.
*/
struct bt_conn_remote_info {
/** Connection Type */
@ -411,7 +411,7 @@ int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info);
* @param remote_info Connection remote info object.
*
* @note In order to retrieve the remote version (version, manufacturer
* and subversion) @option{CONFIG_BT_REMOTE_VERSION} must be enabled
* and subversion) @kconfig{CONFIG_BT_REMOTE_VERSION} must be enabled
*
* @note The remote information is exchanged directly after the connection has
* been established. The application can be notified about when the remote
@ -438,7 +438,7 @@ int bt_conn_le_get_tx_power_level(struct bt_conn *conn,
*
* If the local device is in the peripheral role then updating the connection
* parameters will be delayed. This delay can be configured by through the
* @option{CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT} option.
* @kconfig{CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT} option.
*
* @param conn Connection object.
* @param param Updated connection parameters.
@ -539,7 +539,7 @@ struct bt_conn_le_create_param {
/** @brief Connection initiation timeout (N * 10 MS)
*
* Set zero to use the default @option{CONFIG_BT_CREATE_CONN_TIMEOUT}
* Set zero to use the default @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT}
* timeout.
*
* @note Unused in @ref bt_conn_le_create_auto
@ -693,10 +693,10 @@ typedef enum __packed {
* This function may return error if the pairing procedure has already been
* initiated by the local device or the peer device.
*
* @note When @option{CONFIG_BT_SMP_SC_ONLY} is enabled then the security
* @note When @kconfig{CONFIG_BT_SMP_SC_ONLY} is enabled then the security
* level will always be level 4.
*
* @note When @option{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the
* @note When @kconfig{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the
* security level will always be level 3.
*
* @param conn Connection object.
@ -782,7 +782,7 @@ struct bt_conn_cb {
* @ref bt_conn_le_create was canceled either by the user through
* @ref bt_conn_disconnect or by the timeout in the host through
* @ref bt_conn_le_create_param timeout parameter, which defaults to
* @option{CONFIG_BT_CREATE_CONN_TIMEOUT} seconds.
* @kconfig{CONFIG_BT_CREATE_CONN_TIMEOUT} seconds.
* - @p BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable
* advertiser started by @ref bt_le_adv_start failed to be connected
* within the timeout.
@ -801,7 +801,7 @@ struct bt_conn_cb {
* available.
* To avoid this issue it is recommended to either start connectable
* advertise or create a new connection using @ref k_work_submit or
* increase @option{CONFIG_BT_MAX_CONN}.
* increase @kconfig{CONFIG_BT_MAX_CONN}.
*
* @param conn Connection object.
* @param reason HCI reason for the disconnection.

8
include/bluetooth/gatt.h
View file

@ -345,11 +345,11 @@ void bt_gatt_cb_register(struct bt_gatt_cb *cb);
* macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC,
* BT_GATT_DESCRIPTOR, etc.
*
* When using @option{CONFIG_BT_SETTINGS} then all services that should have
* When using @kconfig{CONFIG_BT_SETTINGS} then all services that should have
* bond configuration loaded, i.e. CCC values, must be registered before
* calling @ref settings_load.
*
* When using @option{CONFIG_BT_GATT_CACHING} and @option{CONFIG_BT_SETTINGS}
* When using @kconfig{CONFIG_BT_GATT_CACHING} and @kconfig{CONFIG_BT_SETTINGS}
* then all services that should be included in the GATT Database Hash
* calculation should be added before calling @ref settings_load.
* All services registered after settings_load will trigger a new database hash
@ -978,7 +978,7 @@ struct bt_gatt_notify_params {
* When called from the System Workqueue context this API will not wait for
* resources for the callback but instead return an error.
* The number of pending callbacks can be increased with the
* @option{CONFIG_BT_CONN_TX_MAX} option.
* @kconfig{CONFIG_BT_CONN_TX_MAX} option.
*
* Alternatively it is possible to notify by UUID by setting it on the
* parameters, when using this method the attribute if provided is used as the
@ -1464,7 +1464,7 @@ int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params);
* When called from the System Workqueue context this API will not wait for
* resources for the callback but instead return an error.
* The number of pending callbacks can be increased with the
* @option{CONFIG_BT_CONN_TX_MAX} option.
* @kconfig{CONFIG_BT_CONN_TX_MAX} option.
*
* @note By using a callback it also disable the internal flow control

2
include/bluetooth/mesh/cfg.h
View file

@ -315,7 +315,7 @@ uint8_t bt_mesh_subnet_kr_phase_get(uint16_t net_idx, uint8_t *phase);
* but only acts on a single Subnet.
*
* GATT Proxy support must be enabled through
* @option{CONFIG_BT_MESH_GATT_PROXY}.
* @kconfig{CONFIG_BT_MESH_GATT_PROXY}.
*
* @param net_idx Network index.
* @param node_id New Node Identity state, must be either @ref

4
include/bluetooth/mesh/main.h
View file

@ -107,7 +107,7 @@ struct bt_mesh_prov {
/** Pointer to Public Key in big-endian for OOB public key type support.
*
* Remember to enable @option{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY}
* Remember to enable @kconfig{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY}
* when initializing this parameter.
*
* Must be used together with @ref bt_mesh_prov::private_key_be.
@ -115,7 +115,7 @@ struct bt_mesh_prov {
const uint8_t *public_key_be;
/** Pointer to Private Key in big-endian for OOB public key type support.
*
* Remember to enable @option{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY}
* Remember to enable @kconfig{CONFIG_BT_MESH_PROV_OOB_PUBLIC_KEY}
* when initializing this parameter.
*
* Must be used together with @ref bt_mesh_prov::public_key_be.