From 00c41ea893857ac33f33e4eab762afb89f951194 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Mon, 10 Jun 2019 11:13:33 -0700 Subject: [PATCH] doc: fix doxygen comments with embedded reST Doxygen comments can include doxygen-specific markup tags. If other markup tags are used (e.g., restructuredText) we need to indicate that in the doxygen comments (via @rststar/@endrststar tags). Signed-off-by: David B. Kinder --- include/kernel.h | 22 ++++++++++++++-------- include/net/mqtt.h | 7 +++++-- include/shell/shell.h | 5 ++++- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/include/kernel.h b/include/kernel.h index 957ba0fe140..bb40aa0291a 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -1626,10 +1626,13 @@ static inline void *z_impl_k_timer_user_data_get(struct k_timer *timer) * This routine returns the elapsed time since the system booted, * in milliseconds. * - * @note 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, and with the default - * setting of 100, system time is updated in increments of 10ms. + * @note + * @rststar + * 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, and with the + * default setting of 100, system time is updated in increments of 10ms. + * @endrststar * * @return Current uptime in milliseconds. */ @@ -1670,10 +1673,13 @@ void k_disable_sys_clock_always_on(void); * cannot hold a system uptime time larger than approximately 50 days, so the * caller must handle possible rollovers. * - * @note 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, and with the default - * setting of 100, system time is updated in increments of 10ms. + * @note + * @rststar + * 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, and with the + * default setting of 100, system time is updated in increments of 10ms. + * @endrststar * * @return Current uptime in milliseconds. */ diff --git a/include/net/mqtt.h b/include/net/mqtt.h index 65cc36db408..1757aa2216f 100644 --- a/include/net/mqtt.h +++ b/include/net/mqtt.h @@ -514,8 +514,11 @@ void mqtt_client_init(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 Please modify :option:`CONFIG_MQTT_KEEPALIVE` time to override default - * of 1 minute. + * @note + * @rststar + * Please modify :option:`CONFIG_MQTT_KEEPALIVE` time to override + * default of 1 minute. + * @endrststar */ int mqtt_connect(struct mqtt_client *client); diff --git a/include/shell/shell.h b/include/shell/shell.h index e7e19886e23..217299ece2e 100644 --- a/include/shell/shell.h +++ b/include/shell/shell.h @@ -851,9 +851,12 @@ void shell_help(const struct shell *shell); * This function must not be called from shell command context! * - * @param[in] shell Pointer to the shell instance. It can be NULL when + * @param[in] shell Pointer to the shell instance. + * @rststar + * It can be NULL when * the :option:`CONFIG_SHELL_BACKEND_DUMMY` option is * enabled. + * @endrststar * @param[in] cmd Command to be executed. * * @returns Result of the execution