From b7166032cc559b6f899c5ca4ca1d084ab2122a16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Tue, 4 Jun 2024 18:16:08 +0200 Subject: [PATCH] doc: misc fixes to C domain types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Breathe is not very strict about the types used to reference C domain objects (ex. referencing a struct using `:c:type:` would work, and vice versa) but other tooling might be. This commit fixes some of such incorrectly documented elements. Signed-off-by: Benjamin Cabé --- doc/develop/api/design_guidelines.rst | 6 +++--- doc/develop/languages/c/picolibc.rst | 2 +- doc/services/resource_management/index.rst | 4 ++-- doc/services/storage/flash_map/flash_map.rst | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/develop/api/design_guidelines.rst b/doc/develop/api/design_guidelines.rst index 169fcc9fae7..1dfeda4c45f 100644 --- a/doc/develop/api/design_guidelines.rst +++ b/doc/develop/api/design_guidelines.rst @@ -31,7 +31,7 @@ specifying the signature of a callback: An exception to providing ``user_data`` as the last parameter may be allowed when the callback itself was provided through a structure that will be embedded in another structure. An example of such a case is -:c:type:`gpio_callback`, normally defined within a data structure +:c:struct:`gpio_callback`, normally defined within a data structure specific to the code that also defines the callback function. In those cases further context can accessed by the callback indirectly by :c:macro:`CONTAINER_OF`. @@ -45,7 +45,7 @@ Examples void handle_timeout(struct k_timer *timer) { ... } - The assumption here, as with :c:type:`gpio_callback`, is that the + The assumption here, as with :c:struct:`gpio_callback`, is that the timer is embedded in a structure reachable from :c:macro:`CONTAINER_OF` that can provide additional context to the callback. @@ -62,7 +62,7 @@ Examples This provides more complete useful information, including which counter channel timed-out and the counter value at which the timeout occurred, as well as user context which may or may not be the - :c:type:`counter_alarm_cfg` used to register the callback, depending + :c:struct:`counter_alarm_cfg` used to register the callback, depending on user needs. Conditional Data and APIs diff --git a/doc/develop/languages/c/picolibc.rst b/doc/develop/languages/c/picolibc.rst index 5b34a29c94a..56ff7897324 100644 --- a/doc/develop/languages/c/picolibc.rst +++ b/doc/develop/languages/c/picolibc.rst @@ -133,7 +133,7 @@ Thread Local Storage Picolibc uses Thread Local Storage (TLS) (where supported) for data which is supposed to remain local to each thread, like -:c:var:`errno`. This means that TLS support is enabled when using +:c:macro:`errno`. This means that TLS support is enabled when using Picolibc. As all TLS variables are allocated out of the thread stack area, this can affect stack size requirements by a few bytes. diff --git a/doc/services/resource_management/index.rst b/doc/services/resource_management/index.rst index 3bdf3e19416..cf6c9db6737 100644 --- a/doc/services/resource_management/index.rst +++ b/doc/services/resource_management/index.rst @@ -80,8 +80,8 @@ state. case is asynchronous. The on-off client structure may be an appropriate solution for the generic API. Where drivers that can guarantee synchronous context-independent transitions a driver may - use :c:type:`onoff_sync_service` and its supporting API rather than - :c:type:`onoff_manager`, with only a small reduction in functionality + use :c:struct:`onoff_sync_service` and its supporting API rather than + :c:struct:`onoff_manager`, with only a small reduction in functionality (primarily no support for the monitor API). .. doxygengroup:: resource_mgmt_onoff_apis diff --git a/doc/services/storage/flash_map/flash_map.rst b/doc/services/storage/flash_map/flash_map.rst index f5ef355f434..801e75bd6bc 100644 --- a/doc/services/storage/flash_map/flash_map.rst +++ b/doc/services/storage/flash_map/flash_map.rst @@ -78,7 +78,7 @@ Numeric flash area ID is obtained by passing DTS node label to :c:macro:`FIXED_PARTITION_ID()`; for example to obtain ID number for ``slot0_partition``, user would invoke ``FIXED_PARTITION_ID(slot0_partition)``. -All :c:macro:`FIXED_PARTITION_` macros take DTS node labels as partition +All :code:`FIXED_PARTITION_*` macros take DTS node labels as partition identifiers. Users do not have to obtain a :c:struct:`flash_area` object pointer