From ae2634103765fac4a8c8c6ce60e5817760834df1 Mon Sep 17 00:00:00 2001 From: Marius Vlad Date: Thu, 6 Jun 2019 23:10:49 +0300 Subject: [PATCH] doc/sphinx: Add doxygen aliases for easier rst embedding With these aliases we can use rST directives inside comment blocks. This adds also a doxygen command '\rststar' where ignores the asterisk -- typical to multi-line comment blocks. While at it, add a simple example on how to use them. Signed-off-by: Marius Vlad --- doc/sphinx/doxygen.ini.in | 5 ++++- include/libweston/libweston.h | 20 ++++++++++++-------- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/doc/sphinx/doxygen.ini.in b/doc/sphinx/doxygen.ini.in index d09ee765..c80b0057 100644 --- a/doc/sphinx/doxygen.ini.in +++ b/doc/sphinx/doxygen.ini.in @@ -238,7 +238,10 @@ TAB_SIZE = 8 # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. -ALIASES = +ALIASES = "rst=\verbatim embed:rst" +ALIASES += "endrst=\endverbatim" +ALIASES += "rststar=\verbatim embed:rst:leading-asterisk" +ALIASES += "endrststar=\endverbatim" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" diff --git a/include/libweston/libweston.h b/include/libweston/libweston.h index 253baeb4..c38c952f 100644 --- a/include/libweston/libweston.h +++ b/include/libweston/libweston.h @@ -955,15 +955,19 @@ enum weston_capability { * likely want to subclass this in order to handle backend specific * data. * - * NOTE: Alternate designs were proposed (Feb 2016) for using opaque - * structures[1] and for section+key/value getter/setters[2]. The rationale - * for selecting the transparent structure design is based on several - * assumptions[3] which may require re-evaluating the design choice if they - * fail to hold. + * \rststar + * .. note: * - * 1: https://lists.freedesktop.org/archives/wayland-devel/2016-February/026989.html - * 2: https://lists.freedesktop.org/archives/wayland-devel/2016-February/026929.html - * 3: https://lists.freedesktop.org/archives/wayland-devel/2016-February/027228.html + * Alternate designs were proposed (Feb 2016) for using opaque structures[1] + * and for section+key/value getter/setters[2]. The rationale for selecting + * the transparent structure design is based on several assumptions[3] which + * may require re-evaluating the design choice if they fail to hold. + * + * 1. https://lists.freedesktop.org/archives/wayland-devel/2016-February/026989.html + * 2. https://lists.freedesktop.org/archives/wayland-devel/2016-February/026929.html + * 3. https://lists.freedesktop.org/archives/wayland-devel/2016-February/027228.html + * + * \endrststar */ struct weston_backend_config { /** Major version for the backend-specific config struct