michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: update Kconfig options to use @option ALIAS

Browse source 
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>
This commit is contained in:
Fabio Utzig 2020-09-11 10:14:37 -03:00 • committed by Carles Cufí
commit 39fa56b834
7 changed files with 49 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

14
include/bluetooth/conn.h
View file

@ -343,7 +343,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 @option{CONFIG_BT_REMOTE_VERSION} is enabled.
*/
struct bt_conn_remote_info {
/** Connection Type */
@ -382,7 +382,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) @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 @@ 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 @option{CONFIG_BT_CREATE_CONN_TIMEOUT}
* timeout.
*
* @note Unused in @ref bt_conn_create_auto_le
@ -708,10 +708,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 @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 @@ struct bt_conn_cb {
* @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 @@ 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 @option{CONFIG_BT_MAX_CONN}.
*
* @param conn Connection object.
* @param reason HCI reason for the disconnection.

4
include/bluetooth/gatt.h
View file

@ -306,11 +306,11 @@ struct bt_gatt_cpf {
* 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

10
include/fs/littlefs.h
View file

@ -57,15 +57,15 @@ struct fs_littlefs {
* 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]; \

78
include/kernel.h
View file

@ -670,7 +670,7 @@ typedef void (*k_thread_user_cb_t)(const struct k_thread *thread,
* @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 @@ extern void k_thread_foreach(k_thread_user_cb_t user_cb, void *user_data);
* @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 @@ extern void k_thread_foreach_unlocked(
*
* @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 @@ static inline void k_thread_resource_pool_assign(struct k_thread *thread,
*
* 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 @@ static inline int32_t k_msleep(int32_t ms)
*
* 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 @@ __syscall void k_thread_priority_set(k_tid_t thread, int prio);
* 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 @@ __syscall void k_thread_deadline_set(k_tid_t thread, int deadline);
* 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 @@ int k_thread_cpu_mask_clear(k_tid_t thread);
* 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 @@ int k_thread_cpu_mask_enable_all(k_tid_t thread);
*
* 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 @@ int k_thread_cpu_mask_enable(k_tid_t thread, int 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
* @param cpu CPU index
@ -1509,8 +1495,8 @@ __syscall void *k_thread_custom_data_get(void);
/**
* @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 @@ static inline void *z_impl_k_timer_user_data_get(struct k_timer *timer)
* @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 @@ __syscall int64_t k_uptime_ticks(void);
* 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 @@ static inline int64_t k_uptime_get(void)
* @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 @@ __deprecated static inline int k_enable_sys_clock_always_on(void)
* @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 @@ __deprecated static inline void k_disable_sys_clock_always_on(void)
* 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 @@ void k_heap_free(struct k_heap *h, void *mem);
* 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

6
include/net/mqtt.h
View file

@ -571,10 +571,8 @@ int mqtt_client_set_proxy(struct mqtt_client *client,
* @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);

7
include/shell/shell.h
View file

@ -904,11 +904,8 @@ void shell_help(const struct shell *shell);
*
* @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

4
include/sys/notify.h
View file

@ -280,10 +280,8 @@ static inline void sys_notify_init_spinwait(struct sys_notify *notify)
* 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.
*