diff options
Diffstat (limited to 'Documentation/doc-guide/kernel-doc.rst')
| -rw-r--r-- | Documentation/doc-guide/kernel-doc.rst | 48 |
1 files changed, 32 insertions, 16 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index fff6604631ea..1dcbd7332476 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 @@ -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; @@ -387,22 +393,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 +442,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 +497,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. |