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.

C sources

source of all-in-a-tumble.[ch]
- source all-in-a-tumble.h
- source all-in-a-tumble.c
rendered all-in-a-tumble.[ch]
- all-in-a-tumble.h
- all-in-a-tumble.c

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::  /src/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::  /src/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::  /src/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::  /src/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::  /src/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>`

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>`_

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_GPL_FUTURE(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::  /src/all-in-a-tumble.c
   :export:  /src/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::  /src/all-in-a-tumble.c
   :export:  /src/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 for all documented definitions, not exported. This test gathers 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, from where only the not exported definitions are used in the reST output:

.. kernel-doc::  /src/all-in-a-tumble.c
   :internal:  all-in-a-tumble.h
   :module: test_internal

The example also shows, that mixing different values for

:exp-method: –> [macro|attribute] and
:exp-ids: –> [EXPORT_SYMBOL|API_EXPORTED]

in one source file is not well supported:

internal 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

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.

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

Return¶

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.

enum rarely_enum¶

enum rarely_enum¶: enum to test parsing rarely code styles

Definition¶

enum rarely_enum {
    F1,
    F2
};

Constants¶

F1: f1
F2: f2

struct rarely_struct¶

struct rarely_struct¶: struct to test parsing rarely code styles

Definition¶

struct rarely_struct {
    struct foo foofoo;
    struct bar barbar;
}

Members¶

foofoo: lorem
barbar: ipsum

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
 *
 * Return:
 *
 * 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::  /src/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

Return¶

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.

kernel-doc Test¶

DOC sections¶

lorem ipsum¶

option :no-header:¶

multiple DOC sections¶

foo bar splat¶

multiple DOC sections¶

option :man-sect:¶

exported symbols¶

option :export:¶

user_function¶

Description¶

Example¶

Return¶

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

user_sum¶

Description¶

Example¶

Return¶

option :internal:¶

user_sum¶

Description¶

Example¶

Return¶

internal_function¶

Context¶

Return¶

sys_tgkill¶

Return¶

enum rarely_enum¶

Definition¶

Constants¶

struct rarely_struct¶

Definition¶

Members¶

SYSCALL macro¶

sys_tgkill¶

Return¶

option `:no-header:`¶

option `:man-sect:`¶

option `:export:`¶

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

option `:internal:`¶