Skip to content
Permalink
Browse files

doc: use @rst/@endrst for ReST in headers

Folks found the use of @rststar/@endrststar non-intuitive (wanted to use
@rststart).  The "star" was there indicating the doxygen comment lines
had a leading asterisk that needed to be stripped, but since our
commenting convention is to use the leading asterisk on continuation
lines, the leading asterisk is always there.  So, change the doxygen
alias to the more expected @rst/@endrst.

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
  • Loading branch information...
dbkinder authored and nashif committed Jun 25, 2019
1 parent e573970 commit 8de9cc7079100701fc6feed38444ad3fa27701a2
Showing with 76 additions and 80 deletions.
  1. +2 −6 doc/zephyr.doxyfile.in
  2. +14 −14 include/kernel.h
  3. +2 −2 include/net/mqtt.h
  4. +46 −46 include/net/socket.h
  5. +10 −10 include/net/socket_select.h
  6. +2 −2 include/shell/shell.h
@@ -220,12 +220,8 @@ TAB_SIZE = 8
# "Side Effects:". You can put \n's in the value part of an alias to insert
# newlines.

ALIASES = "rst=\verbatim embed:rst" \
"endrst=\endverbatim" \
"rststar=\verbatim embed:rst:leading-asterisk" \
"endrststar=\endverbatim" \
"r=\verbatim embed:rst:leading-asterisk" \
"er=\endverbatim"
ALIASES = "rst=\verbatim embed:rst:leading-asterisk" \
"endrst=\endverbatim"

ALIASES += "req=\xrefitem req \"Requirement\" \"Requirements\" "

@@ -1045,10 +1045,10 @@ __syscall void k_thread_priority_set(k_tid_t thread, int prio);
* logic.
*
* @note
* @rststar
* @rst
* You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
* configuration.
* @endrststar
* @endrst
*
* @param thread A thread on which to set the deadline
* @param deadline A time delta, in cycle units
@@ -1066,10 +1066,10 @@ __syscall void k_thread_deadline_set(k_tid_t thread, int deadline);
* CPUs. The thread must not be currently runnable.
*
* @note
* @rststar
* @rst
* You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
* configuration.
* @endrststar
* @endrst
*
* @param thread Thread to operate upon
* @return Zero on success, otherwise error code
@@ -1083,10 +1083,10 @@ int k_thread_cpu_mask_clear(k_tid_t thread);
* thread must not be currently runnable.
*
* @note
* @rststar
* @rst
* You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
* configuration.
* @endrststar
* @endrst
*
* @param thread Thread to operate upon
* @return Zero on success, otherwise error code
@@ -1099,10 +1099,10 @@ int k_thread_cpu_mask_enable_all(k_tid_t thread);
* The thread must not be currently runnable.
*
* @note
* @rststar
* @rst
* You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
* configuration.
* @endrststar
* @endrst
*
* @param thread Thread to operate upon
* @param cpu CPU index
@@ -1116,10 +1116,10 @@ int k_thread_cpu_mask_enable(k_tid_t thread, int cpu);
* The thread must not be currently runnable.
*
* @note
* @rststar
* @rst
* You should enable :option:`CONFIG_SCHED_DEADLINE` in your project
* configuration.
* @endrststar
* @endrst
*
* @param thread Thread to operate upon
* @param cpu CPU index
@@ -1658,12 +1658,12 @@ static inline void *z_impl_k_timer_user_data_get(struct k_timer *timer)
* in milliseconds.
*
* @note
* @rststar
* @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, and with the
* default setting of 100, system time is updated in increments of 10ms.
* @endrststar
* @endrst
*
* @return Current uptime in milliseconds.
*/
@@ -1705,12 +1705,12 @@ void k_disable_sys_clock_always_on(void);
* caller must handle possible rollovers.
*
* @note
* @rststar
* @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, and with the
* default setting of 100, system time is updated in increments of 10ms.
* @endrststar
* @endrst
*
* @return Current uptime in milliseconds.
*/
@@ -515,10 +515,10 @@ 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
* @rststar
* @rst
* Please modify :option:`CONFIG_MQTT_KEEPALIVE` time to override
* default of 1 minute.
* @endrststar
* @endrst
*/
int mqtt_connect(struct mqtt_client *client);

0 comments on commit 8de9cc7

Please sign in to comment.
You can’t perform that action at this time.