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 <marius.vlad@collabora.com>

diff --git a/doc/sphinx/doxygen.ini.in b/doc/sphinx/doxygen.ini.in
index d09ee7659a2104827b73a624104a2d943a0f2340..c80b0057455038fca955bd0bb3b7cec910c432c9 100644 (file)
--- 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 253baeb4f4214cdf447879381002d99c98930666..c38c952f87e59158e85b3661d4b4bd3df1d259ba 100644 (file)
--- 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