diff options
Diffstat (limited to 'Documentation/doc-guide/kernel-doc.rst')
| -rw-r--r-- | Documentation/doc-guide/kernel-doc.rst | 103 |
1 files changed, 82 insertions, 21 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index fff6604631ea..d6f7efefea42 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -1,3 +1,6 @@ +.. title:: Kernel-doc comments + +=========================== Writing kernel-doc comments =========================== @@ -11,6 +14,9 @@ when it is embedded in source files. reasons. The kernel source contains tens of thousands of kernel-doc comments. Please stick to the style described here. +.. note:: kernel-doc does not cover Rust code: please see + Documentation/rust/general-information.rst instead. + 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 @@ -145,9 +151,9 @@ named ``Return``. line breaks, so if you try to format some text nicely, as in:: * Return: - * 0 - OK - * -EINVAL - invalid argument - * -ENOMEM - out of memory + * %0 - OK + * %-EINVAL - invalid argument + * %-ENOMEM - out of memory this will all run together and produce:: @@ -157,8 +163,8 @@ named ``Return``. ReST list, e. g.:: * Return: - * * 0 - OK to runtime suspend the device - * * -EBUSY - Device should not be runtime suspended + * * %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 @@ -247,12 +253,12 @@ It is possible to document nested structs and unions, like:: struct { int memb1; int memb2; - } + }; struct { void *memb3; int memb4; - } - } + }; + }; union { struct { int memb1; @@ -335,6 +341,51 @@ Typedefs with function prototypes can also be documented:: */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); +Object-like macro documentation +------------------------------- + +Object-like macros are distinct from function-like macros. They are +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``. +They may have a parameter list. Object-like macros have do not have a +parameter list. + +The general format of an object-like macro kernel-doc comment is:: + + /** + * define object_name - Brief description. + * + * Description of the object. + */ + +Example:: + + /** + * define MAX_ERRNO - maximum errno value that is supported + * + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a normal + * pointer with the same return value. + */ + #define MAX_ERRNO 4095 + +Example:: + + /** + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ + * Initializes struct drm_plane_helper_funcs for VRAM handling + * + * This macro initializes struct drm_plane_helper_funcs to use the + * respective helper functions. + */ + #define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \ + .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \ + .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb + + Highlights and cross-references ------------------------------- @@ -387,22 +438,23 @@ Domain`_ references. 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`. +No additional syntax is needed to cross-reference the functions and types +defined in the kernel-doc comments from reStructuredText documents. +Just end function names with ``()`` and write ``struct``, ``union``, ``enum`` +or ``typedef`` before types. +For example:: -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 foo(). + See struct foo. + See union bar. + See enum baz. + See typedef meh. - See :c:type:`struct foo <foo>`. - See :c:type:`union bar <bar>`. - See :c:type:`enum baz <baz>`. - See :c:type:`typedef meh <meh>`. +However, if you want custom text in the cross-reference link, that can be done +through the following syntax:: -This will produce prettier links, and is in line with how kernel-doc does the -cross-references. + See :c:func:`my custom link text for function foo <foo>`. + See :c:type:`my custom link text for struct bar <bar>`. For further details, please refer to the `Sphinx C Domain`_ documentation. @@ -435,6 +487,7 @@ 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 ============================= @@ -489,6 +542,14 @@ identifiers: *[ function/type ...]* .. kernel-doc:: lib/idr.c :identifiers: +no-identifiers: *[ function/type ...]* + Exclude documentation for each *function* and *type* in *source*. + + Example:: + + .. kernel-doc:: lib/bitmap.c + :no-identifiers: bitmap_parselist + functions: *[ function/type ...]* This is an alias of the 'identifiers' directive and deprecated. |