doc: update Kconfig options to use @option ALIAS
This updates Kconfig options in the Doxygen documentation to use the new
@option ALIAS. There are three categories of fixes:
* Use of `:option:` inside Doxygen headers, which is not valid (this is
rST syntax!).
* Kconfig options that were just written as plain text and were no
references were generated.
* Use of `@rst` blocks where the only reason for using them was to have
Kconfig options resolved.
Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
diff --git a/include/bluetooth/conn.h b/include/bluetooth/conn.h
index 44cb867..1edac60 100644
--- a/include/bluetooth/conn.h
+++ b/include/bluetooth/conn.h
@@ -343,7 +343,7 @@
/** @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 @option{CONFIG_BT_REMOTE_VERSION} is enabled.
*/
struct bt_conn_remote_info {
/** Connection Type */
@@ -382,7 +382,7 @@
* @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) @option{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
@@ -483,7 +483,7 @@
/** @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 @option{CONFIG_BT_CREATE_CONN_TIMEOUT}
* timeout.
*
* @note Unused in @ref bt_conn_create_auto_le
@@ -708,10 +708,10 @@
* 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 @option{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 @option{CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY} is enabled then the
* security level will always be level 3.
*
* @param conn Connection object.
@@ -798,7 +798,7 @@
* @ref bt_conn_create_le 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.
+ * @option{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.
@@ -817,7 +817,7 @@
* 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 @option{CONFIG_BT_MAX_CONN}.
*
* @param conn Connection object.
* @param reason HCI reason for the disconnection.
diff --git a/include/bluetooth/gatt.h b/include/bluetooth/gatt.h
index c02f52d..ceae746 100644
--- a/include/bluetooth/gatt.h
+++ b/include/bluetooth/gatt.h
@@ -306,11 +306,11 @@
* 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 @option{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 @option{CONFIG_BT_GATT_CACHING} and @option{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
diff --git a/include/fs/littlefs.h b/include/fs/littlefs.h
index a709a02..91e52e1 100644
--- a/include/fs/littlefs.h
+++ b/include/fs/littlefs.h
@@ -57,15 +57,15 @@
* values are consistent with littlefs requirements.
*
* @note If you use a non-default configuration for cache size, you
- * must also select :option:`CONFIG_FS_LITTLEFS_FC_MEM_POOL` to relax
+ * must also select @option{CONFIG_FS_LITTLEFS_FC_MEM_POOL} to relax
* the size constraints on per-file cache allocations.
*
* @param name the name for the structure. The defined object has
* file scope.
- * @param read_sz see :option:`CONFIG_FS_LITTLEFS_READ_SIZE`
- * @param prog_sz see :option:`CONFIG_FS_LITTLEFS_PROG_SIZE`
- * @param cache_sz see :option:`CONFIG_FS_LITTLEFS_CACHE_SIZE`
- * @param lookahead_sz see :option:`CONFIG_FS_LITTLEFS_LOOKAHEAD_SIZE`
+ * @param read_sz see @option{CONFIG_FS_LITTLEFS_READ_SIZE}
+ * @param prog_sz see @option{CONFIG_FS_LITTLEFS_PROG_SIZE}
+ * @param cache_sz see @option{CONFIG_FS_LITTLEFS_CACHE_SIZE}
+ * @param lookahead_sz see @option{CONFIG_FS_LITTLEFS_LOOKAHEAD_SIZE}
*/
#define FS_LITTLEFS_DECLARE_CUSTOM_CONFIG(name, read_sz, prog_sz, cache_sz, lookahead_sz) \
static uint8_t __aligned(4) name ## _read_buffer[cache_sz]; \
diff --git a/include/kernel.h b/include/kernel.h
index 2119547..835731e 100644
--- a/include/kernel.h
+++ b/include/kernel.h
@@ -670,7 +670,7 @@
* @param user_cb Pointer to the user callback function.
* @param user_data Pointer to user data.
*
- * @note CONFIG_THREAD_MONITOR must be set for this function
+ * @note @option{CONFIG_THREAD_MONITOR} must be set for this function
* to be effective.
* @note This API uses @ref k_spin_lock to protect the _kernel.threads
* list which means creation of new threads and terminations of existing
@@ -689,7 +689,7 @@
* @param user_cb Pointer to the user callback function.
* @param user_data Pointer to user data.
*
- * @note CONFIG_THREAD_MONITOR must be set for this function
+ * @note @option{CONFIG_THREAD_MONITOR} must be set for this function
* to be effective.
* @note This API uses @ref k_spin_lock only when accessing the _kernel.threads
* queue elements. It unlocks it during user callback function processing.
@@ -751,8 +751,8 @@
*
* @details
* Indicates that the thread being created should inherit all kernel object
- * permissions from the thread that created it. No effect if CONFIG_USERSPACE
- * is not enabled.
+ * permissions from the thread that created it. No effect if
+ * @option{CONFIG_USERSPACE} is not enabled.
*/
#define K_INHERIT_PERMS (BIT(3))
@@ -879,8 +879,8 @@
*
* Some hardware may prevent inspection of a stack buffer currently in use.
* If this API is called from supervisor mode, on the currently running thread,
- * on a platform which selects CONFIG_NO_UNUSED_STACK_INSPECTION, an error
- * will be generated.
+ * on a platform which selects @option{CONFIG_NO_UNUSED_STACK_INSPECTION}, an
+ * error will be generated.
*
* @param thread Thread to inspect stack information
* @param unused_ptr Output parameter, filled in with the unused stack space
@@ -964,9 +964,10 @@
*
* This function is unlikely to work as expected without kernel tuning.
* In particular, because the lower bound on the duration of a sleep is
- * the duration of a tick, CONFIG_SYS_CLOCK_TICKS_PER_SEC must be adjusted
- * to achieve the resolution desired. The implications of doing this must
- * be understood before attempting to use k_usleep(). Use with caution.
+ * the duration of a tick, @option{CONFIG_SYS_CLOCK_TICKS_PER_SEC} must be
+ * adjusted to achieve the resolution desired. The implications of doing
+ * this must be understood before attempting to use k_usleep(). Use with
+ * caution.
*
* @param us Number of microseconds to sleep.
*
@@ -1239,11 +1240,8 @@
* above this call, which is simply input to the priority selection
* logic.
*
- * @note
- * @rst
- * You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
- * configuration.
- * @endrst
+ * @note You should enable @option{CONFIG_SCHED_DEADLINE} in your project
+ * configuration.
*
* @param thread A thread on which to set the deadline
* @param deadline A time delta, in cycle units
@@ -1259,11 +1257,8 @@
* After this returns, the thread will no longer be schedulable on any
* CPUs. The thread must not be currently runnable.
*
- * @note
- * @rst
- * You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
- * configuration.
- * @endrst
+ * @note You should enable @option{CONFIG_SCHED_DEADLINE} in your project
+ * configuration.
*
* @param thread Thread to operate upon
* @return Zero on success, otherwise error code
@@ -1276,11 +1271,8 @@
* After this returns, the thread will be schedulable on any CPU. The
* thread must not be currently runnable.
*
- * @note
- * @rst
- * You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
- * configuration.
- * @endrst
+ * @note You should enable @option{CONFIG_SCHED_DEADLINE} in your project
+ * configuration.
*
* @param thread Thread to operate upon
* @return Zero on success, otherwise error code
@@ -1292,11 +1284,8 @@
*
* The thread must not be currently runnable.
*
- * @note
- * @rst
- * You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
- * configuration.
- * @endrst
+ * @note You should enable @option{CONFIG_SCHED_DEADLINE} in your project
+ * configuration.
*
* @param thread Thread to operate upon
* @param cpu CPU index
@@ -1309,11 +1298,8 @@
*
* The thread must not be currently runnable.
*
- * @note
- * @rst
- * You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
- * configuration.
- * @endrst
+ * @note You should enable @option{CONFIG_SCHED_DEADLINE} in your project
+ * configuration.
*
* @param thread Thread to operate upon
* @param cpu CPU index
@@ -1509,8 +1495,8 @@
/**
* @brief Set current thread name
*
- * Set the name of the thread to be used when THREAD_MONITOR is enabled for
- * tracing and debugging.
+ * Set the name of the thread to be used when @option{CONFIG_THREAD_MONITOR}
+ * is enabled for tracing and debugging.
*
* @param thread_id Thread to set name, or NULL to set the current thread
* @param value Name string
@@ -2050,7 +2036,7 @@
* @brief Get system uptime, in system ticks.
*
* This routine returns the elapsed time since the system booted, in
- * ticks (c.f. :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`), which is the
+ * ticks (c.f. @option{CONFIG_SYS_CLOCK_TICKS_PER_SEC}), which is the
* fundamental unit of resolution of kernel timekeeping.
*
* @return Current uptime in ticks.
@@ -2064,11 +2050,9 @@
* in milliseconds.
*
* @note
- * @rst
* While this function returns time in milliseconds, it does
* not mean it has millisecond resolution. The actual resolution depends on
- * :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` config option.
- * @endrst
+ * @option{CONFIG_SYS_CLOCK_TICKS_PER_SEC} config option.
*
* @return Current uptime in milliseconds.
*/
@@ -2081,8 +2065,8 @@
* @brief Enable clock always on in tickless kernel
*
* Deprecated. This does nothing (it was always just a hint). This
- * functionality has been migrated to the SYSTEM_CLOCK_SLOPPY_IDLE
- * kconfig.
+ * functionality has been migrated to the
+ * @option{CONFIG_SYSTEM_CLOCK_SLOPPY_IDLE} config option.
*
* @retval prev_status Previous status of always on flag
*/
@@ -2100,8 +2084,8 @@
* @brief Disable clock always on in tickless kernel
*
* Deprecated. This does nothing (it was always just a hint). This
- * functionality has been migrated to the SYS_CLOCK_SLOPPY_IDLE
- * kconfig.
+ * functionality has been migrated to the
+ * @option{CONFIG_SYSTEM_CLOCK_SLOPPY_IDLE} config option.
*/
/* LCOV_EXCL_START */
__deprecated static inline void k_disable_sys_clock_always_on(void)
@@ -2124,11 +2108,9 @@
* interrupt blocking and 64-bit math.
*
* @note
- * @rst
* While this function returns time in milliseconds, it does
* not mean it has millisecond resolution. The actual resolution depends on
- * :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` config option
- * @endrst
+ * @option{CONFIG_SYS_CLOCK_TICKS_PER_SEC} config option
*
* @return The low 32 bits of the current uptime, in milliseconds.
*/
@@ -4764,7 +4746,7 @@
* If the pool is to be accessed outside the module where it is defined, it
* can be declared via
*
- * @note When CONFIG_MEM_POOL_HEAP_BACKEND is enabled, the k_mem_pool
+ * @note When @option{CONFIG_MEM_POOL_HEAP_BACKEND} is enabled, the k_mem_pool
* API is implemented on top of a k_heap, which is a more general
* purpose allocator which does not make the same promises about
* splitting or alignment detailed above. Blocks will be aligned only
diff --git a/include/net/mqtt.h b/include/net/mqtt.h
index 028800f..e4d2f05 100644
--- a/include/net/mqtt.h
+++ b/include/net/mqtt.h
@@ -571,10 +571,8 @@
* @note Default protocol revision used for connection request is 3.1.1. Please
* set client.protocol_version = MQTT_VERSION_3_1_0 to use protocol 3.1.0.
* @note
- * @rst
- * Please modify :option:`CONFIG_MQTT_KEEPALIVE` time to override
- * default of 1 minute.
- * @endrst
+ * Please modify @option{CONFIG_MQTT_KEEPALIVE} time to override default
+ * of 1 minute.
*/
int mqtt_connect(struct mqtt_client *client);
diff --git a/include/shell/shell.h b/include/shell/shell.h
index 2e264ed..1ea8201 100644
--- a/include/shell/shell.h
+++ b/include/shell/shell.h
@@ -904,11 +904,8 @@
*
* @param[in] shell Pointer to the shell instance.
- * @rst
- * It can be NULL when
- * the :option:`CONFIG_SHELL_BACKEND_DUMMY` option is
- * enabled.
- * @endrst
+ * It can be NULL when the
+ * @option{CONFIG_SHELL_BACKEND_DUMMY} option is enabled.
* @param[in] cmd Command to be executed.
*
* @returns Result of the execution
diff --git a/include/sys/notify.h b/include/sys/notify.h
index a51b098..fdca4d6 100644
--- a/include/sys/notify.h
+++ b/include/sys/notify.h
@@ -280,10 +280,8 @@
* reinitialized before it can be re-used.
*
* @note
- * @rst
- * This capability is available only when :option:`CONFIG_POLL` is
+ * This capability is available only when @option{CONFIG_POLL} is
* selected.
- * @endrst
*
* @param notify pointer to the notification configuration object.
*
