kernel-doc in reST documents¶

To integrate kernel-doc comments into a reST document (e.g. in a book), there exists a reST-directive named kernel-doc . The directive comes with options to fine grain control which parts should be placed into the reST document. With no options given, the complete kernel-doc comments from a source file will be inserted. So, the first and very simple example is:

My Lib
======

.. kernel-doc:: ../src/mylib.h

With this small example (a file doc/mylib.rst) the kernel-doc comments from the src/mylib.h will be inserted direct under the chapter “My Lib”. The “DOC:” sections, the function and the type descriptions will be inserted in the order they appear in the source file. Mostly you want to select more fine grained, read on to see how.

kernel-doc options ¶

Here is a short overview of the directives options:

.. kernel-doc:: <src-filename>
    :doc: <section title>
    :no-header:
    :export:
    :internal:
    :exp-method: <method>
    :exp-ids:    <identifier [, identifiers [, ...]]>
    :symbols:    <function [, union, struct [, ...]]>
    :module:     <namespace>
    :man-sect:   <man sect-no>
    :snippets:   <snippet [, snippets [, ...]]>
    :language:   <snippet-lang>
    :linenos:
    :debug:

The argument <src-filename> is required and points to the source file. The pathname is relative to the pathname of the kernel-doc directive. Absolute pathnames are relative to srctree, which can be set in the environment or using kernel_doc_srctree in the sphinx conf.py (if unset, defaults to CWD). The options have the following meaning, but be aware that not all combinations of these options make sense:

:doc: <section title> (DOC sections)

Include content of the DOC: section titled <section title>. Spaces are allowed in <section title>; do not quote the <section title>.

The next option make only sense in conjunction with option doc:

:no-header: (option :no-header:): Do not output DOC: section’s title. Useful, if the surrounding context already has a heading, and the DOC: section title is only used as an identifier. Take in mind, that this option will not suppress any native reST heading markup in the comment.

:export: [<src-fname-pattern> [, ...]] (option :export:)

Include documentation of all function, struct or whatever definitions in <src-filename> and exported using one of the export symbols (macro) either in <src-filename> or in any of the files specified by <src-fname-pattern>.

The <src-fname-pattern> (glob) is useful when the kernel-doc comments have been placed in header files, while EXPORT_SYMBOL are next to the function definitions.

:internal: [<src-fname-pattern> [, ...]] (option :internal:)

Include documentation of all documented definitions, not exported by one of the export symbols (macro) either in <src-filename> or in any of the files specified by <src-fname-pattern>.

:exp-method: <method>

Change the way exported symbols are specified in source code. Default value macro if not provided, can be set globally by kernel_doc_exp_method in the sphinx conf.py.

The <method> must one of the following value:

macro: Exported symbols are specified by macros (whose names are controlled by exp-ids option) invoked in the source the following way: THIS_IS_AN_EXPORTED_SYMBOL(symbol)
attribute: Exported symbols are specified definition using a specific attribute (controlled by exp-ids option) either in their declaration or definition: THIS_IS_AN_EXPORTED_SYMBOL int symbol(void* some_arg) {...}

:exp-ids: <identifier [, identifiers [, ...]]>

Use the specified list of identifiers instead of default value: EXPORT_SYMBOL, EXPORT_SYMBOL_GPL & EXPORT_SYMBOL_GPL_FUTURE. Default value can be overriden globally by sphinx conf.py option kernel_doc_exp_ids.

:known-attrs: <attr [, attrs [, ...]]>

Specified a list of function attributes that are known and must be hidden when displaying function prototype.

When :exp-method: is set to attribute the list in :exp-ids: is considered as known and added implicitly to this list of known attributes. The default list is empty and can be adjusted by the sphinx configuration option kernel_doc_known_attrs.

:symbols: <name [, names [, ...]]> (Insert function’s documentation, structs, unions, enums and typedefs)

Include documentation for each named definition. For backward compatibility there exists an alias functions.

:module: <namespace>

The option :module: <namespace> sets a module-name and is used in .. c:namespace-push: [ref]. The module-name (aka namespace) is used as a prefix in the cross links. For a detailed example have a look at section Insert function’s documentation.

:man-sect: <sect-no>

Section number of the manual pages (see “$ man man-pages””). Optional set kernel_doc_mansect option in sphinx conf.py. The man-pages are build by the kernel-doc-man builder. Read on here: man pages from kernel-doc comments

:snippets: <name [, names [, ...]]>

Inserts the source-code passage(s) marked with the snippet name. The snippet is inserted with a code-block:: directive.

The next options make only sense in conjunction with option snippets:

language <highlighter>: Set highlighting language of the snippet code-block.
linenos: Set line numbers in the snippet code-block.

:debug:

Inserts a code-block with the generated reST source. This might sometimes helpful to see how the kernel-doc parser transforms the kernel-doc markup to reST markup.

Insert function’s documentation ¶

In source all-in-a-tumble.c there is the following function definition which is documented by a kernel-doc syntax.

/**
 * user_function() - function that can only be called in user context
 * @a: some argument
 * @...: ellipsis operator
 *
 * This function makes no sense, it's only a kernel-doc demonstration.
 *
 * Example:
 * x = user_function(22);
 *
 * Return:
 * Returns first argument
 */
int
user_function(int a, ...)
{
        return a;
}

To include the documentation from C-functions into your reStructuredText document use the following markup:

.. kernel-doc:: ./all-in-a-tumble.c
   :symbols:  user_function
   :module:   foo

This will convert the kernel-doc syntax into the following reST markup:

.. c:namespace-push:: foo

.. _`foo.user_function`:

user_function
=============

.. c:function:: int user_function(int a,  ...)

    function that can only be called in user context

    :param a:
        some argument
    :type a: int

    :param ellipsis ellipsis:
        ellipsis operator

.. _`foo.user_function.description`:

Description
-----------

This function makes no sense, it's only a kernel-doc demonstration.

.. _`foo.user_function.example`:

Example
-------

.. code-block:: c

    x = user_function(22);

.. _`foo.user_function.return`:

Return
------

Returns first argument

.. c:namespace-pop::

In the next view lines you will see how the documentation will be rendered:

kernel-doc option :symbols:

user_function¶

int user_function(int a, ...)¶

function that can only be called in user context

Parameters:

a (int) – some argument
ellipsis (ellipsis) – ellipsis operator

Description¶

This function makes no sense, it’s only a kernel-doc demonstration.

Example¶

x = user_function(22);

Return¶

Returns first argument

In reST documents you can cross reference to the function or directly to one of the sections of this documentation:

* C constructs in Sphinx >= 3.1 :c:func:`foo.user_function`
* refer sections: :ref:`Example <foo.user_function.example>`,
  :ref:`Return <foo.user_function.return>` ...

cross referencing function’s documentation

C constructs in Sphinx >= 3.1 foo.user_function()
refer sections: Example, Return …

structs, unions, enums and typedefs ¶

The following example inserts the documentation of struct my_long_struct.

.. kernel-doc:: ./all-in-a-tumble.h
   :symbols:    my_long_struct
   :module:     example

Here in this documentation the examples from the source of all-in-a-tumble.[ch] are located in the example module (aka namespace). To Cross-referencing C constructs within this module you can use the Sphinx namespace or to point to a section you can use the anchors inserted by the .. kernel-doc:: directive.

* C constructs in Sphinx >= 3.1 :c:struct:`example.my_long_struct`
* refer sections: :ref:`Definition <example.my_long_struct.definition>`,
  :ref:`Members <example.my_long_struct.members>` ...

option :symbols: structs, unions, enums and typedefs

C constructs in Sphinx >= 3.1 example.my_long_struct
refer sections: Definition, Members …

Snippets ¶

The kernel-doc Parser supports a markup for Snippets. By example; In the the all-in-a-tumble examples we have a small source code example:

/* parse-SNIP: hello-world */
#include<stdio.h>
int main() {
    printf("Hello World\n");
    return 0;
}
/* parse-SNAP: */

To insert the code passage between SNIP & SNAP use:

.. kernel-doc::  ./all-in-a-tumble.c
   :snippets:  hello-world
   :language:  c
   :linenos:

And here is the rendered example:

#include<stdio.h>
int main() {
  printf("Hello World\n");
  return 0;
}

man pages (:man-sect:)¶

To get man pages from kernel-doc comments, add the :man-sect: option to your kernel-doc directives. E.g. to get man-pages of media’s remote control (file media/kapi/rc-core.rst) add :man-sect: 9 to all the kernel-doc includes.

Remote Controller devices
=========================

Remote Controller core
----------------------

.. kernel-doc:: include/media/rc-core.h
   :man-sect: 9

.. kernel-doc:: include/media/rc-map.h
   :man-sect: 9

LIRC
----

.. kernel-doc:: include/media/lirc_dev.h
   :man-sect: 9

If you don’t want to edit all your kernel-doc directives to get man page from, set a global man-sect in your conf.py, see sphinx configuration kernel_doc_mansect and about build look at: man pages from kernel-doc comments

Highlights and cross-references ¶

The following special patterns are recognized in the kernel-doc comment descriptive text and converted to proper reStructuredText markup and Sphinx’s C Domain references.

Attention

The below are only recognized within kernel-doc comments, not within normal reStructuredText documents.

funcname()

Function reference.

@parameter

Name of a function parameter. (No cross-referencing, just formatting.)

%CONST

Name of a constant. (No cross-referencing, just formatting.)

``literal``

A literal block that should be handled as-is. The output will use a monospaced font.

Useful if you need to use special characters that would otherwise have some meaning either by kernel-doc script of by reStructuredText.

This is particularly useful if you need to use things like %ph inside a function description.

$ENVVAR

Name of an environment variable. (No cross-referencing, just formatting.)

&struct name

Structure reference.

&enum name

Enum reference.

&typedef name

Typedef reference.

&struct_name->member or &struct_name.member

Structure or union member reference. The cross-reference will be to the struct or union definition, not the member directly.

&name

A generic type reference. Prefer using the full reference described above instead. This is mostly for legacy comments.

kernel-doc config ¶

Within the sphinx config file (conf.py or my_project.conf) you can set the following option.

kernel_doc_exp_method: linuxdoc.kernel_doc.DEFAULT_EXP_METHOD: Set parser’s default value for kernel-doc directive option :exp-method: (details see: exp-method)

kernel_doc_exp_ids: linuxdoc.kernel_doc.DEFAULT_EXP_IDS

Set parser’s default value for kernel-doc directive option :exp-ids:. (details see: exp-ids)

kernel_doc_known_attrs: [...]

Set parser’s default value for kernel-doc directive option :known-attrs: (details see: kernel-doc options)

kernel_doc_mansect: None

Global fallback for man section of kernel-doc directives. Set this value if you want to create man pages for those kernel-doc directives, which has not been set a :man-sect: value. The default is None, which means; do the opposite and create only man pages for those directives which has been set the :man-sect: option (None is what you mostly want).

kernel_doc_mode: reST

Set parser’s default kernel-doc mode [reST|kernel-doc]. Normally you wont set anything other than the default! See reST kernel-doc mode and Vintage kernel-doc mode.

kernel_doc_verbose_warn: True

If true, more warnings will be logged. E.g. a missing description of a function’s return value will be logged.

kernel_doc_raise_error: True

If True fatal errors (like missing function descriptions) raise an error. The default is True. This means that the build process break every time a serve error in the documentation build occur. Often it might be better the build continues and inserts Oops on serve errors. For this, set kernel_doc_raise_error to False. In the next example, the documentation of a non existing definition name no_longer_exists is required:

.. kernel-doc::  ./all-in-a-tumble.h
    :symbols:  no_longer_exist

Since this definition not exists (anymore), the following TODO entry with Oops is inserted (again; only when kernel_doc_raise_error is False).

parser error inserts a “.. todo::” directive with Oops in

Todo

Oops: Document generation inconsistency.

The template for this document tried to insert structured comment at this point, but an error occoured. This dummy section is inserted to allow generation to continue.:

/share/linuxdoc/docs/linuxdoc-howto/kernel-doc-directive.rst:441: (ERROR/3) selected section(s) not found:
    no_longer_exist

.. kernel-doc::  ./all-in-a-tumble.h
   :symbols:  no_longer_exist

kernel_doc_srctree: None

Set the pathname used as a base for absolute pathnames in kernel-doc directive. It can be overridden by the srctree environment variable.

kernel-doc in reST documents¶

kernel-doc options ¶

Insert function’s documentation ¶

user_function¶

Description¶

Example¶

Return¶

structs, unions, enums and typedefs ¶

Snippets ¶

man pages (:man-sect:)¶

Highlights and cross-references ¶

kernel-doc config ¶

Project Links

Navigation

Contents

kernel-doc in reST documents¶

kernel-doc options¶

Insert function’s documentation¶

user_function¶

Description¶

Example¶

Return¶

structs, unions, enums and typedefs¶

Snippets¶

man pages (:man-sect:)¶

Highlights and cross-references¶

kernel-doc config¶

kernel-doc options ¶

Insert function’s documentation ¶

structs, unions, enums and typedefs ¶

Snippets ¶

Highlights and cross-references ¶

kernel-doc config ¶