diff options
Diffstat (limited to 'Documentation/doc-guide/kernel-doc.rst')
| -rw-r--r-- | Documentation/doc-guide/kernel-doc.rst | 63 |
1 files changed, 42 insertions, 21 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index fd89a6d56ea9..8d2c09fb36e4 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -54,13 +54,16 @@ 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 + tools/docs/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:: +The documentation format of ``.c`` files is also verified by the kernel build +when it is requested to perform extra gcc checks:: make W=n +However, the above command does not verify header files. These should be checked +separately using ``kernel-doc``. + Function documentation ---------------------- @@ -174,7 +177,8 @@ named ``Return`` (or ``Returns``). Structure, union, and enumeration documentation ----------------------------------------------- -The general format of a struct, union, and enum kernel-doc comment is:: +The general format of a ``struct``, ``union``, and ``enum`` kernel-doc +comment is:: /** * struct struct_name - Brief description. @@ -187,8 +191,8 @@ The general format of a struct, union, and enum kernel-doc comment is:: */ 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. +``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 @@ -201,7 +205,7 @@ 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 +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. @@ -273,11 +277,11 @@ It is possible to document nested structs and unions, like:: .. note:: - #) When documenting nested structs or unions, if the struct/union ``foo`` - is named, the member ``bar`` inside it should be documented as + #) 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:`` + #) When the nested ``struct``/``union`` is anonymous, the member ``bar`` in + it should be documented as ``@bar:`` In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -319,7 +323,7 @@ on a line of their own, like all other kernel-doc comments:: Typedef documentation --------------------- -The general format of a typedef kernel-doc comment is:: +The general format of a ``typedef`` kernel-doc comment is:: /** * typedef type_name - Brief description. @@ -341,6 +345,18 @@ Typedefs with function prototypes can also be documented:: */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); +Variables documentation +----------------------- + +The general format of a kernel-doc variable comment is:: + + /** + * var var_name - Brief description. + * + * Description of the var_name variable. + */ + extern int var_name; + Object-like macro documentation ------------------------------- @@ -349,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a left parenthesis ('(') for function-like macros or not followed by one for object-like macros. -Function-like macros are handled like functions by ``scripts/kernel-doc``. +Function-like macros are handled like functions by ``tools/docs/kernel-doc``. They may have a parameter list. Object-like macros have do not have a parameter list. @@ -432,8 +448,8 @@ Domain`_ references. 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. + ``struct`` 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 @@ -462,14 +478,18 @@ through the following syntax:: For further details, please refer to the `Sphinx C Domain`_ documentation. +.. note:: + Variables aren't automatically cross referenced. For those, you need to + explicitly add a C domain cross-reference. + 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. +kernel-doc for functions, structures, unions, enums, typedefs or variables. +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. @@ -537,7 +557,8 @@ identifiers: *[ function/type ...]* Include documentation for each *function* and *type* in *source*. If no *function* is specified, the documentation for all functions and types in the *source* will be included. - *type* can be a struct, union, enum, or typedef identifier. + *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var`` + identifier. Examples:: @@ -575,8 +596,8 @@ 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. +``tools/docs/kernel-doc`` script to extract the documentation comments from +the source. .. _kernel_doc: |