diff options
Diffstat (limited to '')
| -rw-r--r-- | Documentation/doc-guide/kernel-doc.rst | 520 |
1 files changed, 520 insertions, 0 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst new file mode 100644 index 000000000..8db53cdc2 --- /dev/null +++ b/Documentation/doc-guide/kernel-doc.rst @@ -0,0 +1,520 @@ +Writing kernel-doc comments +=========================== + +The Linux kernel source files may contain structured documentation +comments in the kernel-doc format to describe the functions, types +and design of the code. It is easier to keep documentation up-to-date +when it is embedded in source files. + +.. note:: The kernel-doc format is deceptively similar to javadoc, + gtk-doc or Doxygen, yet distinctively different, for historical + reasons. The kernel source contains tens of thousands of kernel-doc + comments. Please stick to the style described here. + +The kernel-doc structure is extracted from the comments, and proper +`Sphinx C Domain`_ function and type descriptions with anchors are +generated from them. The descriptions are filtered for special kernel-doc +highlights and cross-references. See below for details. + +.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html + +Every function that is exported to loadable modules using +``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc +comment. Functions and data structures in header files which are intended +to be used by modules should also have kernel-doc comments. + +It is good practice to also provide kernel-doc formatted documentation +for functions externally visible to other kernel files (not marked +``static``). We also recommend providing kernel-doc formatted +documentation for private (file ``static``) routines, for consistency of +kernel source code layout. This is lower priority and at the discretion +of the maintainer of that kernel source file. + +How to format kernel-doc comments +--------------------------------- + +The opening comment mark ``/**`` is used for kernel-doc comments. The +``kernel-doc`` tool will extract comments marked this way. The rest of +the comment is formatted like a normal multi-line comment with a column +of asterisks on the left side, closing with ``*/`` on a line by itself. + +The function and type kernel-doc comments should be placed just before +the function or type being described in order to maximise the chance +that somebody changing the code will also change the documentation. The +overview kernel-doc comments may be placed anywhere at the top indentation +level. + +Running the ``kernel-doc`` tool with increased verbosity and without actual +output generation may be used to verify proper formatting of the +documentation comments. For example:: + + scripts/kernel-doc -v -none drivers/foo/bar.c + +The documentation format is verified by the kernel build when it is +requested to perform extra gcc checks:: + + make W=n + +Function documentation +---------------------- + +The general format of a function and function-like macro kernel-doc comment is:: + + /** + * function_name() - Brief description of function. + * @arg1: Describe the first argument. + * @arg2: Describe the second argument. + * One can provide multiple line descriptions + * for arguments. + * + * A longer description, with more discussion of the function function_name() + * that might be useful to those using or modifying it. Begins with an + * empty comment line, and may include additional embedded empty + * comment lines. + * + * The longer description may have multiple paragraphs. + * + * Context: Describes whether the function can sleep, what locks it takes, + * releases, or expects to be held. It can extend over multiple + * lines. + * Return: Describe the return value of foobar. + * + * The return value description can also have multiple paragraphs, and should + * be placed at the end of the comment block. + */ + +The brief description following the function name may span multiple lines, and +ends with an argument description, a blank comment line, or the end of the +comment block. + +Function parameters +~~~~~~~~~~~~~~~~~~~ + +Each function argument should be described in order, immediately following +the short function description. Do not leave a blank line between the +function description and the arguments, nor between the arguments. + +Each ``@argument:`` description may span multiple lines. + +.. note:: + + If the ``@argument`` description has multiple lines, the continuation + of the description should start at the same column as the previous line:: + + * @argument: some long description + * that continues on next lines + + or:: + + * @argument: + * some long description + * that continues on next lines + +If a function has a variable number of arguments, its description should +be written in kernel-doc notation as:: + + * @...: description + +Function context +~~~~~~~~~~~~~~~~ + +The context in which a function can be called should be described in a +section named ``Context``. This should include whether the function +sleeps or can be called from interrupt context, as well as what locks +it takes, releases and expects to be held by its caller. + +Examples:: + + * Context: Any context. + * Context: Any context. Takes and releases the RCU lock. + * Context: Any context. Expects <lock> to be held by caller. + * Context: Process context. May sleep if @gfp flags permit. + * Context: Process context. Takes and releases <mutex>. + * Context: Softirq or process context. Takes and releases <lock>, BH-safe. + * Context: Interrupt context. + +Return values +~~~~~~~~~~~~~ + +The return value, if any, should be described in a dedicated section +named ``Return``. + +.. note:: + + #) The multi-line descriptive text you provide does *not* recognize + line breaks, so if you try to format some text nicely, as in:: + + * Return: + * 0 - OK + * -EINVAL - invalid argument + * -ENOMEM - out of memory + + this will all run together and produce:: + + Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory + + So, in order to produce the desired line breaks, you need to use a + ReST list, e. g.:: + + * Return: + * * 0 - OK to runtime suspend the device + * * -EBUSY - Device should not be runtime suspended + + #) If the descriptive text you provide has lines that begin with + some phrase followed by a colon, each of those phrases will be taken + as a new section heading, which probably won't produce the desired + effect. + +Structure, union, and enumeration documentation +----------------------------------------------- + +The general format of a struct, union, and enum kernel-doc comment is:: + + /** + * struct struct_name - Brief description. + * @member1: Description of member1. + * @member2: Description of member2. + * One can provide multiple line descriptions + * for members. + * + * Description of the structure. + */ + +You can replace the ``struct`` in the above example with ``union`` or +``enum`` to describe unions or enums. ``member`` is used to mean struct +and union member names as well as enumerations in an enum. + +The brief description following the structure name may span multiple +lines, and ends with a member description, a blank comment line, or the +end of the comment block. + +Members +~~~~~~~ + +Members of structs, unions and enums should be documented the same way +as function parameters; they immediately succeed the short description +and may be multi-line. + +Inside a struct or union description, you can use the ``private:`` and +``public:`` comment tags. Structure fields that are inside a ``private:`` +area are not listed in the generated output documentation. + +The ``private:`` and ``public:`` tags must begin immediately following a +``/*`` comment marker. They may optionally include comments between the +``:`` and the ending ``*/`` marker. + +Example:: + + /** + * struct my_struct - short description + * @a: first member + * @b: second member + * @d: fourth member + * + * Longer description + */ + struct my_struct { + int a; + int b; + /* private: internal use only */ + int c; + /* public: the next one is public */ + int d; + }; + +Nested structs/unions +~~~~~~~~~~~~~~~~~~~~~ + +It is possible to document nested structs and unions, like:: + + /** + * struct nested_foobar - a struct with nested unions and structs + * @memb1: first member of anonymous union/anonymous struct + * @memb2: second member of anonymous union/anonymous struct + * @memb3: third member of anonymous union/anonymous struct + * @memb4: fourth member of anonymous union/anonymous struct + * @bar: non-anonymous union + * @bar.st1: struct st1 inside @bar + * @bar.st2: struct st2 inside @bar + * @bar.st1.memb1: first member of struct st1 on union bar + * @bar.st1.memb2: second member of struct st1 on union bar + * @bar.st2.memb1: first member of struct st2 on union bar + * @bar.st2.memb2: second member of struct st2 on union bar + */ + struct nested_foobar { + /* Anonymous union/struct*/ + union { + struct { + int memb1; + int memb2; + } + struct { + void *memb3; + int memb4; + } + } + union { + struct { + int memb1; + int memb2; + } st1; + struct { + void *memb1; + int memb2; + } st2; + } bar; + }; + +.. note:: + + #) When documenting nested structs or unions, if the struct/union ``foo`` + is named, the member ``bar`` inside it should be documented as + ``@foo.bar:`` + #) When the nested struct/union is anonymous, the member ``bar`` in it + should be documented as ``@bar:`` + +In-line member documentation comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The structure members may also be documented in-line within the definition. +There are two styles, single-line comments where both the opening ``/**`` and +closing ``*/`` are on the same line, and multi-line comments where they are each +on a line of their own, like all other kernel-doc comments:: + + /** + * struct foo - Brief description. + * @foo: The Foo member. + */ + struct foo { + int foo; + /** + * @bar: The Bar member. + */ + int bar; + /** + * @baz: The Baz member. + * + * Here, the member description may contain several paragraphs. + */ + int baz; + union { + /** @foobar: Single line description. */ + int foobar; + }; + /** @bar2: Description for struct @bar2 inside @foo */ + struct { + /** + * @bar2.barbar: Description for @barbar inside @foo.bar2 + */ + int barbar; + } bar2; + }; + +Typedef documentation +--------------------- + +The general format of a typedef kernel-doc comment is:: + + /** + * typedef type_name - Brief description. + * + * Description of the type. + */ + +Typedefs with function prototypes can also be documented:: + + /** + * typedef type_name - Brief description. + * @arg1: description of arg1 + * @arg2: description of arg2 + * + * Description of the type. + * + * Context: Locking context. + * Return: Meaning of the return value. + */ + typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); + +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 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. + +Cross-referencing from reStructuredText +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To cross-reference the functions and types defined in the kernel-doc comments +from reStructuredText documents, please use the `Sphinx C Domain`_ +references. For example:: + + See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. + +While the type reference works with just the type name, without the +struct/union/enum/typedef part in front, you may want to use:: + + See :c:type:`struct foo <foo>`. + See :c:type:`union bar <bar>`. + See :c:type:`enum baz <baz>`. + See :c:type:`typedef meh <meh>`. + +This will produce prettier links, and is in line with how kernel-doc does the +cross-references. + +For further details, please refer to the `Sphinx C Domain`_ documentation. + +Overview documentation comments +------------------------------- + +To facilitate having source code and comments close together, you can include +kernel-doc documentation blocks that are free-form comments instead of being +kernel-doc for functions, structures, unions, enums, or typedefs. This could be +used for something like a theory of operation for a driver or library code, for +example. + +This is done by using a ``DOC:`` section keyword with a section title. + +The general format of an overview or high-level documentation comment is:: + + /** + * 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 is can sometimes damage + * hardware, software, or its subject(s). + */ + +The title following ``DOC:`` acts as a heading within the source file, but also +as an identifier for extracting the documentation comment. Thus, the title must +be unique within the file. + +Including kernel-doc comments +============================= + +The documentation comments may be included in any of the reStructuredText +documents using a dedicated kernel-doc Sphinx directive extension. + +The kernel-doc directive is of the format:: + + .. kernel-doc:: source + :option: + +The *source* is the path to a source file, relative to the kernel source +tree. The following directive options are supported: + +export: *[source-pattern ...]* + Include documentation for all functions in *source* that have been exported + using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any + of the files specified by *source-pattern*. + + The *source-pattern* is useful when the kernel-doc comments have been placed + in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to + the function definitions. + + Examples:: + + .. kernel-doc:: lib/bitmap.c + :export: + + .. kernel-doc:: include/net/mac80211.h + :export: net/mac80211/*.c + +internal: *[source-pattern ...]* + Include documentation for all functions and types in *source* that have + **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either + in *source* or in any of the files specified by *source-pattern*. + + Example:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :internal: + +doc: *title* + Include documentation for the ``DOC:`` paragraph identified by *title* in + *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* + is only used as an identifier for the paragraph, and is not included in the + output. Please make sure to have an appropriate heading in the enclosing + reStructuredText document. + + Example:: + + .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c + :doc: High Definition Audio over HDMI and Display Port + +functions: *[ function ...]* + Include documentation for each *function* in *source*. + If no *function* if specified, the documentaion for all functions + and types in the *source* will be included. + + Examples:: + + .. kernel-doc:: lib/bitmap.c + :functions: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :functions: + +Without options, the kernel-doc directive includes all documentation comments +from the source file. + +The kernel-doc extension is included in the kernel source tree, at +``Documentation/sphinx/kerneldoc.py``. Internally, it uses the +``scripts/kernel-doc`` script to extract the documentation comments from the +source. + +.. _kernel_doc: + +How to use kernel-doc to generate man pages +------------------------------------------- + +If you just want to use kernel-doc to generate man pages you can do this +from the kernel git tree:: + + $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man |