reST kernel-doc mode¶

To distinguish between the vintage markup and the new markup (with reST in), it is recommended to add the following comment at the top of your source code file.:

/* parse-markup: reST */

This forces the kernel-doc parser to switch into the reST mode, no matter in which context the parser runs (see Vintage kernel-doc mode).

reST section structure¶

Since a section title in reST mode needs a line break after the colon, the colon handling is less ugly (vintage mode quirks). E.g.:

prints out: hello world

is rendered as expected in one line. If non text follows the colon, a section is inserted. To avoid sectioning in any case, place a space in front of the column.:

lorem list :

* lorem
* ipsum

On the opposite, super-short sections from Vintage kernel-doc mode like:

Section name: lorem ipsum

are no longer supported, you have to enter at least one line break:

Section name:
lorem ipsum

There is an exception for special section names like “Description:”, “Context:” or “Return:”, which exists mainly for backward compatibility. Nevertheless, it is recommended to add a newline after the colon.

Beside these sectioning of the kernel-doc syntax, reST has it’s own chapter, section etc. markup (e.g. see Sections). Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, there is a common convention, which is used by the kernel-doc parser also:

# with over-line, for parts
* with over-line, for chapters
= for sections
- for subsections
^ for sub-subsections
" for paragraphs

Within kernel-doc comments you should use this sectioning with care. A kernel-doc section like the Return: section above is translated into a reST sub-section with the following markup.

Return
------

sum of a and b

As you see, a kernel-doc section is a reST subsection level. This means, you can only use the following sub-levels within a kernel-doc section.

^ for sub-subsections
" for paragraphs

In contrast to subsections like “Return:”, a “DOC:” section has no subsection, thats why reST sub-levels in “DOC:” sections start a the subsection level, tagged with a minus:

- for subsections
^ for sub-subsections
" for paragraphs

Need an detailed example of kernel-doc comment using subsections and more? Take a look here …

/**
 * rst_mode - dummy to demonstrate reST & kernel-doc markup in comments
 * @a: first argument
 * @b: second argument
 * Context: :c:func:`in_gizmo_mode`.
 *
 * Long description. This function has two integer arguments. The first is
 * ``parameter_a`` and the second is ``parameter_b``.
 *
 * As long as the reST / sphinx-doc toolchain uses `intersphinx
 * <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__ you can refer
 * definitions *outside* like :c:type:`struct media_device <media_device>`.  If
 * the description of ``media_device`` struct is found in any of the intersphinx
 * locations, a hyperref to this target is generated a build time.
 *
 * Example:
 *   int main() {
 *     printf("Hello World\n");
 *     return 0;
 *   }
 *
 * Return: Sum of ``parameter_a`` and the second is ``parameter_b``.
 *
 * highlighting:
 * The highlight pattern, are non regular reST markups. They are only available
 * within kernel-doc comments, helping C developers to write short and compact
 * documentation.
 *
 * - user_function() : function
 * - @a : name of a parameter
 * - &struct my_struct : name of a structure (including the word struct)
 * - &union my_union : name of a union
 * - &my_struct->a or &my_struct.b -  member of a struct or union.
 * - &enum my_enum : name of a enum
 * - &typedef my_typedef : name of a typedef
 * - %CONST : name of a constant.
 * - $ENVVAR : environmental variable
 *
 * The kernel-doc parser translates the pattern above to the corresponding reST
 * markups. You don't have to use the *highlight* pattern, if you prefer *pure*
 * reST, use the reST markup.
 *
 * - :c:func:`user_function` : function
 * - ``a`` : name of a parameter
 * - :c:type:`struct my_struct <my_struct>` : name of a structure (including the word struct)
 * - :c:type:`union my_union <my_union>` : name of a union
 * - :c:type:`my_struct->a <my_struct>` or :c:type:`my_struct.b <my_struct>` -  member of a struct or union.
 * - :c:type:`enum my_enum <my_enum>` : name of a enum
 * - :c:type:`typedef my_typedef <my_typedef>` : name of a typedef
 * - ``CONST`` : name of a constant.
 * - ``\$ENVVAR`` : environmental variable
 *
 * Since the prefixes ``$...``, ``&...`` and ``@...`` are used to markup the
 * highlight pattern, you have to escape them in other uses: \$lorem, \&lorem,
 * \%lorem and \@lorem. To esacpe from function highlighting, use lorem\().
 *
 * Parser Mode:
 * This is an example with activated reST additions, in this section you will
 * find some common inline markups.
 *
 * Within the *reST mode* the kernel-doc parser pass through all markups to the
 * reST toolchain, except the *vintage highlighting* but including any
 * whitespace. With this, the full reST markup is available in the comments.
 *
 * This is a link to the `Linux kernel source tree
 * <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`_.
 *
 * This description is only to show some reST inline markups like *emphasise*
 * and **emphasis strong**. The following is a demo of a reST list markup:
 *
 * Definition list:
 * :def1: lorem
 * :def2: ipsum
 *
 * Ordered List:
 * - item one
 * - item two
 * - item three with
 *   a linebreak
 *
 * Literal blocks:
 * The next example shows a literal block::
 *
 *     +------+          +------+
 *     |\     |\        /|     /|
 *     | +----+-+      +-+----+ |
 *     | |    | |      | |    | |
 *     +-+----+ |      | +----+-+
 *      \|     \|      |/     |/
 *       +------+      +------+
 *        foo()         bar()
 *
 * Highlighted code blocks:
 * The next example shows a code block, with highlighting C syntax in the
 * output.
 *
 * .. code-block:: c
 *
 *     // Hello World program
 *     #include<stdio.h>
 *     int main()
 *     {
 *        printf("Hello World");
 *     }
 *
 *
 * reST sectioning:
 *
 * colon markup: sectioning by colon markup in reST mode is less ugly. ;-)
 *
 * A kernel-doc section like *this* section is translated into a reST
 * *subsection*. This means, you can only use the following *sub-levels* within a
 * kernel-doc section.
 *
 * a subsubsection
 * ^^^^^^^^^^^^^^^
 *
 * lorem ipsum
 *
 * a paragraph
 * """""""""""
 *
 * lorem ipsum
 *
 */
int rst_mode(int a, char *b)
{
  return a + b;
}

reST markup in kernel-doc comments

rst_mode¶

int rst_mode(int a, char *b)¶

dummy to demonstrate reST & kernel-doc markup in comments

Parameters:

a (int) – first argument
b (char*) – second argument Context: in_gizmo_mode().

Description¶

Long description. This function has two integer arguments. The first is parameter_a and the second is parameter_b.

As long as the reST / sphinx-doc toolchain uses intersphinx you can refer definitions outside like struct media_device. If the description of media_device struct is found in any of the intersphinx locations, a hyperref to this target is generated a build time.

Example¶

int main() {
  printf("Hello World\n");
  return 0;
}

Return¶

Sum of parameter_a and the second is parameter_b.

highlighting¶

The highlight pattern, are non regular reST markups. They are only available within kernel-doc comments, helping C developers to write short and compact documentation.

user_function() : function
a : name of a parameter
struct my_struct : name of a structure (including the word struct)
union my_union : name of a union
my_struct->a or my_struct.b - member of a struct or union.
enum my_enum : name of a enum
typedef my_typedef : name of a typedef
CONST : name of a constant.
$ENVVAR : environmental variable

The kernel-doc parser translates the pattern above to the corresponding reST markups. You don’t have to use the highlight pattern, if you prefer pure reST, use the reST markup.

user_function() : function
a : name of a parameter
struct my_struct : name of a structure (including the word struct)
union my_union : name of a union
my_struct->a or my_struct.b - member of a struct or union.
enum my_enum : name of a enum
typedef my_typedef : name of a typedef
CONST : name of a constant.
$ENVVAR : environmental variable

Since the prefixes $..., &... and @... are used to markup the highlight pattern, you have to escape them in other uses: $lorem, &lorem, %lorem and @lorem. To esacpe from function highlighting, use lorem().

Parser Mode¶

This is an example with activated reST additions, in this section you will find some common inline markups.

Within the reST mode the kernel-doc parser pass through all markups to the reST toolchain, except the vintage highlighting but including any whitespace. With this, the full reST markup is available in the comments.

This is a link to the Linux kernel source tree.

This description is only to show some reST inline markups like emphasise and emphasis strong. The following is a demo of a reST list markup:

Definition list¶

def1:: lorem
def2:: ipsum

Ordered List¶

item one
item two
item three with a linebreak

Literal blocks¶

The next example shows a literal block:

+------+          +------+
|\     |\        /|     /|
| +----+-+      +-+----+ |
| |    | |      | |    | |
+-+----+ |      | +----+-+
 \|     \|      |/     |/
  +------+      +------+
   foo()         bar()

Highlighted code blocks¶

The next example shows a code block, with highlighting C syntax in the output.

// Hello World program
#include<stdio.h>
int main()
{
   printf("Hello World");
}

reST sectioning¶

colon markup: sectioning by colon markup in reST mode is less ugly. ;-)

A kernel-doc section like this section is translated into a reST subsection. This means, you can only use the following sub-levels within a kernel-doc section.

a subsubsection¶

lorem ipsum

a paragraph¶