rendered `all-in-a-tumble.[ch]`¶

Below you find the rendered reST markup, generated from kernel-doc comments of the example files all-in-a-tumble.h and all-in-a-tumble.c. This content will be produced by the kernel-doc parser and inserted in the document by using the following directives:

.. kernel-doc::  /src/all-in-a-tumble.c
   :module: example

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

The option :module: is optional, to find out why we use this option here, see kernel-doc options.

all-in-a-tumble.h ¶

About Examples ¶

The files source all-in-a-tumble.c and source all-in-a-tumble.h are including all examples of the LinuxDoc HowTo documentation. These files are also used as a test of the kernel-doc parser, to see how kernel-doc content will be rendered and where the parser might fail.

And … The content itself is nonsense / don’t look to close ;-)

trace_block_touch_buffer ¶

void trace_block_touch_buffer(struct buffer_head *bh)¶

mark a buffer accessed

Parameters:

bh (struct buffer_head*) – buffer_head being touched

Description¶

Called from touch_buffer().

trace_block_dirty_buffer ¶

void trace_block_dirty_buffer(struct buffer_head *bh)¶

mark a buffer dirty

Parameters:

bh (struct buffer_head*) – buffer_head being dirtied

Description¶

Called from mark_buffer_dirty().

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).

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()

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.

struct my_long_struct ¶

struct my_long_struct¶: short description with my_struct->a and my_struct->b

Definition¶

struct my_long_struct {
    int foo;
    int bar;
    int baz;
    union {
        int foobar;
    } ;
    struct {
        int barbar;
    } bar2;
}

Members¶

foo

The Foo member.

bar

The Bar member.

baz

The Baz member.

Here, the member description may contain several paragraphs.

{unnamed_union}

anonymous

foobar

Single line description.

bar2

Description for struct bar2 inside my_long_struct

bar2.barbar

Description for barbar inside my_long_struct.bar2

Description¶

Longer description

union my_union ¶

union my_union¶: short description

Definition¶

union my_union {
    int a;
    int b;
}

Members¶

a: first member
b: second member

Description¶

Longer description

enum my_enum ¶

enum my_enum¶: log level

Definition¶

enum my_enum {
    QUIET,
    INFO,
    WARN,
    DEBUG
};

Constants¶

QUIET: logs nothing
INFO: logs info messages
WARN: logs warn and info messages
DEBUG: logs debug, warn and info messages

typedef my_typedef ¶

type my_typedef¶: useless typdef of int

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¶

lorem ipsum

vintage ¶

int vintage(int parameter_a, char parameter_b)¶

short description of this function

Parameters:

parameter_a (int) – first argument
parameter_b (char) – second argument

Context¶

in_gizmo_mode().

Description¶

This is a test of a typical markup from *vintage* kernel-doc. Don’t look to close here, it is only for testing some kernel-doc parser stuff.

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

Example¶

user_function(22);

Return¶

Sum of parameter_a and parameter_b.

highlighting¶

vintage() : function
parameter_a : name of a parameter
$ENVVAR : environmental variable
struct my_struct : name of a structure (up to two words including ``struct``)
CONST : name of a constant.

Parser Mode¶

*vintage* kernel-doc mode

Within the *vintage kernel-doc mode* ignores any whitespace or inline markup.

Inline markup like *emphasis* or **emphasis strong**
Literals and/or block indent:

a + b

In kernel-doc *vintage* mode, there are no special block or inline markups available. Markups like the one above result in ambiguous reST markup which could produce error messages in the subsequently sphinx-build process. Unexpected outputs are mostly the result.

This is a link https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/ to the Linux kernel source tree

colon markup¶

sectioning by colon markup in vintage mode is partial ugly. ;-)

struct nfp_flower_priv ¶

struct nfp_flower_priv¶: Flower APP per-vNIC priv data

Definition¶

struct nfp_flower_priv {
    struct nfp_net *nn;
    u32 mask_id_seed;
    u64 flower_version;
    struct nfp_fl_mask_id mask_ids;
    DECLARE_HASHTABLE(mask_table, NFP_FLOWER_MASK_HASH_BITS);
    DECLARE_HASHTABLE(flow_table, NFP_FLOWER_HASH_BITS);
}

Members¶

nn: Pointer to vNIC
mask_id_seed: Seed used for mask hash table
flower_version: HW version of flower
mask_ids: List of free mask ids
mask_table: Hash table used to store masks
flow_table: Hash table used to store flower rules

enum foo ¶

enum foo¶: foo

Definition¶

enum foo {
    F1,
    F2
};

Constants¶

F1: f1
F2: f2

struct something ¶

struct something¶: Lorem ipsum dolor sit amet.

Definition¶

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

Members¶

foofoo: lorem
barbar: ipsum

struct lineevent_state ¶

struct lineevent_state¶: contains the state of a userspace event

Definition¶

struct lineevent_state {
    struct gpio_device *gdev;
    const char *label;
    struct gpio_desc *desc;
    u32 eflags;
    int irq;
    wait_queue_head_t wait;
    DECLARE_KFIFO(events, struct gpioevent_data, 16);
    DECLARE_KFIFO_PTR(foobar, struct lirc_scancode);
    struct mutex read_lock;
}

Members¶

gdev: the GPIO device the event pertains to
label: consumer label used to tag descriptors
desc: the GPIO descriptor held by this event
eflags: the event flags this line was requested with
irq: the interrupt that trigger in response to events on this GPIO
wait: wait queue that handles blocking reads of events
events: KFIFO for the GPIO events (testing DECLARE_KFIFO)
foobar: testing DECLARE_KFIFO_PTR
read_lock: mutex lock to protect reads from colliding with adding new events to the FIFO

all-in-a-tumble.c ¶

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

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

rendered all-in-a-tumble.[ch]¶

Description¶

Description¶

foo bar splat¶

Definition¶

Members¶

Description¶

Definition¶

Members¶

Description¶

Definition¶

Constants¶

Description¶

Example¶

Return¶

highlighting¶

Parser Mode¶

Definition list¶

Ordered List¶

Literal blocks¶

Highlighted code blocks¶

reST sectioning¶

a subsubsection¶

a paragraph¶

Context¶

Description¶

Example¶

Return¶

highlighting¶

Parser Mode¶

colon markup¶

Definition¶

Members¶

Definition¶

Constants¶

Definition¶

Members¶

Definition¶

Members¶

Description¶

Example¶

Return¶

Description¶

Example¶

Return¶

Context¶

Return¶

Return¶

Definition¶

Constants¶

Definition¶

Members¶

rendered `all-in-a-tumble.[ch]`¶