kernel-doc Test¶

Wtihin this section you will find some LinuxDoc HowTo tests and examples for common use cases. The kernel-doc comments are taken from the source files source all-in-a-tumble.c and source all-in-a-tumble.h.

DOC sections ¶

For a very simple example we use this DOC section from source all-in-a-tumble.h:

/**
 * DOC: lorem ipsum
 *
 * Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor
 * incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
 * nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi
 * consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore
 * eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident,
 * sunt in culpa qui officia deserunt mollit anim id est laborum.
 */

To insert content with heading use:

.. kernel-doc::  ./all-in-a-tumble.h
   :doc: lorem ipsum
   :module: test

With the module name test the title can be linked with:

Here is a link to DOC: :ref:`test.lorem-ipsum`

Here is a link to DOC lorem ipsum …

DOC section with header

lorem ipsum¶

Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

option `:no-header:`¶

To insert just the content, without the header use option :no-header::

.. kernel-doc::  ./all-in-a-tumble.h
   :doc: lorem ipsum
   :no-header:

DOC section without header

Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

multiple DOC sections ¶

Its always recommended to separate different DOC sections in different comments. Nevertheless, a few tests are to be carried out here with it. The DOC section tests are based on this comment:

/**
 * DOC: Theory of Operation
 *
 * The whizbang foobar is a dilly of a gizmo.  It can do whatever you
 * want it to do, at any time.  It reads your mind.  Here's how it works.
 *
 * foo bar splat
 * -------------
 *
 * The only drawback to this gizmo is that it can sometimes damage hardware,
 * software, or its subject(s).
 *
 * DOC: multiple DOC sections
 *
 * It's not recommended to place more than one "DOC:" section in the same
 * comment block. To insert a new "DOC:" section, create a new comment block and
 * to create a sub-section use the reST markup for headings, see documentation
 * of function rst_mode()
 */

.. kernel-doc::  ./all-in-a-tumble.h
   :doc: Theory of Operation
   :no-header:

DOC section

The whizbang foobar is a dilly of a gizmo. It can do whatever you want it to do, at any time. It reads your mind. Here’s how it works.

foo bar splat¶

The only drawback to this gizmo is that it can sometimes damage hardware, software, or its subject(s).

.. kernel-doc::  ./all-in-a-tumble.h
   :doc: multiple DOC sections

DOC section

multiple DOC sections¶

It’s not recommended to place more than one “DOC:” section in the same comment block. To insert a new “DOC:” section, create a new comment block and to create a sub-section use the reST markup for headings, see documentation of function rst_mode()

option `:man-sect:`¶

In the option :export: example, we can add a :man-sect: 2 option, to generate man pages with the kernel-doc-man builder for all exported symbols. The usage is:

.. kernel-doc::  ./all-in-a-tumble.c
   :export:  ./all-in-a-tumble.h
   :module: test
   :man-sect: 2

In the conf.py file we set man_pages and kernel_doc_mansect:

kernel_doc_mansect = None
man_pages = [ ]

To place and gzip the manuals in dist/docs/man Folder see kernel-doc-man Builder.

You can include the man-page as a download item in your HTML like this (relative build path is needed):

:download:`user_function.2.gz   <../../dist/docs/man/user_function.2.gz>`

download directive

user_function.2.gz

Or just set a link to the man page file (relative HTML URL is needed)

hyperlink to: `user_function.2.gz <../man/user_function.2.gz>`_

link man folder /man

hyperlink to: user_function.2.gz

To view a (downloaded) man-page use:

$ man ~/Downloads/user_function.2.gz

exported symbols ¶

option `:export:`¶

In the source all-in-a-tumble.h header file we export:

EXPORT_SYMBOL(user_function)

int user_function(int a, ...)

The documentation of the exported symbols is in source all-in-a-tumble.c. To gather exports from source all-in-a-tumble.h and source all-in-a-tumble.c and parses comments from source all-in-a-tumble.c use kernel-doc options:

.. kernel-doc::  ./all-in-a-tumble.c
   :export:  ./all-in-a-tumble.h
   :module: test

exported 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

options `:export:, :exp-method:, :exp-ids:`¶

This test gathers function from source all-in-a-tumble.c whose function attributes mark them as exported:

/**
 * user_sum() - another function that can only be called in user context
 * @a: first argument
 * @b: second argument
 *
 * This function makes no sense, it's only a kernel-doc demonstration.
 *
 * Example:
 * x = user_sum(1, 2);
 *
 * Return:
 * Returns the sum of the @a and @b
 */
API_EXPORTED
int user_sum(int a, int b)
{
        return a + b;
}

and that are present in source all-in-a-tumble.h:

int user_sum(int a, int b);

To insert the documentation use:

.. kernel-doc::  ./all-in-a-tumble.c
   :export:  ./all-in-a-tumble.h
   :exp-method: attribute
   :exp-ids: API_EXPORTED
   :module: test.fnattrs

The exp-method and exp-ids could be respectively omitted if kernel_doc_exp_method and kernel_doc_exp_ids are set in the sphinx configuration.

exported symbols

user_sum¶

int user_sum(int a, int b)¶

another function that can only be called in user context

Parameters:

a (int) – first argument
b (int) – second argument

Description¶

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

Example¶

x = user_sum(1, 2);

Return¶

Returns the sum of the a and b

option `:internal:`¶

Include documentation of all documented definitions, not exported. This test gathers exports from test_internals.h and test_internals.c and parses comments from test_internals.c, from where only the not exported definitions are used in the reST output.

Attention

The both examples below also demonstrate that it is not good to mix the export methods (:exp-method: [macro|attribute]) in one source test_internals.[hc]. Only one methode can be used by the :internal: option to identfy a symbol to be exported.

From :test_internals.h:

EXP_SYMB(foo)

int foo(int a, ...)

From test_internals.c:

/**
 * foo() - 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 = foo(42);
 *
 * Return:
 * Returns first argument
 */
int foo(int a, ...)
{
        return a;
}

From test_internals.c:

/**
 * bar() - 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 = bar(42);
 *
 * Return:
 * Returns first argument
 */
API_EXP int bar(int a, ...)
{
        return a;
}

From test_internals.h:

int bar(int a, int b);

.. kernel-doc::  ./test_internals.c
   :internal:  ./test_internals.h
   :module: test_internals_A
   :exp-method: macro
   :exp-ids: EXP_SYMB
   :known-attrs: API_EXP

Its not good to mix exp-method, the know-attrs here is needed to avoid the Sphinx warning:

./test_internals.c:24: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name, got keyword: int [error at 11]
  API_EXP int bar(int a,  ...)
-----------^

internal symbols (when exp-method is macro)

bar¶

int bar(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 = bar(42);

Return¶

Returns first argument

internal_function¶

int internal_function(void)¶

the answer

Parameters:

void – no arguments

Context¶

!sanity()

Return¶

The answer to the ultimate question of life, the universe and everything.

.. kernel-doc::  ./test_internals.c
   :internal:  ./test_internals.h
   :module: test_internals_B
   :exp-method: attribute
   :exp-ids: API_EXP

internal symbols (when exp-method is attribute)

foo¶

int foo(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 = foo(42);

Return¶

Returns first argument

internal_function¶

int internal_function(void)¶

the answer

Parameters:

void – no arguments

Context¶

!sanity()

Return¶

The answer to the ultimate question of life, the universe and everything.

Missing exports ¶

In the next test, the :export: {file glob pattern} is used, but it does not match any file, or there are no exports in the matching files. Whatever, an empty list of exported symbols is treated as an error:

.. kernel-doc::  ./all-in-a-tumble.c
   :export:  ./match_files_without_exports*

missing exports

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-tests.rst:355: (ERROR/3) using option :export: but there are no exported symbols

.. kernel-doc::  ./all-in-a-tumble.c
   :export:  ./match_files_without_exports*

SYSCALL macro ¶

In the Kernel’s source is a macro: SYSCALL_DEFINEn(). By example:

/**
 *  sys_tgkill - send signal to one specific thread
 *  @tgid: the thread group ID of the thread
 *  @pid: the PID of the thread
 *  @sig: signal to be sent
 *
 *  This syscall also checks the @tgid and returns -ESRCH even if the PID
 *  exists but it's not belonging to the target process anymore. This
 *  method solves the problem of threads exiting and PIDs getting reused.
 */
SYSCALL_DEFINE3(tgkill, pid_t, tgid, pid_t, pid, int, sig)
{
        ...
}

.. kernel-doc::  ./all-in-a-tumble.c
   :symbols:  sys_tgkill

missing exports

sys_tgkill¶

long sys_tgkill(pid_t tgid, pid_t pid, int sig)¶

send signal to one specific thread

Parameters:

tgid (pid_t) – the thread group ID of the thread
pid (pid_t) – the PID of the thread
sig (int) – signal to be sent

Description¶

This syscall also checks the tgid and returns -ESRCH even if the PID exists but it’s not belonging to the target process anymore. This method solves the problem of threads exiting and PIDs getting reused.