Documentation/doc-guide/kernel-doc.rst

1 Writing kernel-doc comments
5 comments in the kernel-doc format to describe the functions, types
9 .. note:: The kernel-doc format is deceptively similar to javadoc,
10    gtk-doc or Doxygen, yet distinctively different, for historical
11    reasons. The kernel source contains tens of thousands of kernel-doc
14 The kernel-doc structure is extracted from the comments, and proper
16 generated from them. The descriptions are filtered for special kernel-doc
19 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
22 ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
24 to be used by modules should also have kernel-doc comments.
26 It is good practice to also provide kernel-doc formatted documentation
28 ``static``). We also recommend providing kernel-doc formatted
33 How to format kernel-doc comments
36 The opening comment mark ``/**`` is used for kernel-doc comments. The
37 ``kernel-doc`` tool will extract comments marked this way. The rest of
41 The function and type kernel-doc comments should be placed just before
44 overview kernel-doc comments may be placed anywhere at the top indentation
47 Running the ``kernel-doc`` tool with increased verbosity and without actual
51 	scripts/kernel-doc -v -none drivers/foo/bar.c
61 The general format of a function and function-like macro kernel-doc comment is::
114 be written in kernel-doc notation as::
171 The general format of a struct, union, and enum kernel-doc comment is::
282 on a line of their own, like all other kernel-doc comments::
316 The general format of a typedef kernel-doc comment is::
341 The following special patterns are recognized in the kernel-doc comment
345 .. attention:: The below are **only** recognized within kernel-doc comments,
362   meaning either by kernel-doc script or by reStructuredText.
391 defined in the kernel-doc comments from reStructuredText documents.
414 kernel-doc documentation blocks that are free-form comments instead of being
415 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
419 This is done by using a ``DOC:`` section keyword with a section title.
424    * DOC: Theory of Operation
435 The title following ``DOC:`` acts as a heading within the source file, but also
439 Including kernel-doc comments
443 documents using a dedicated kernel-doc Sphinx directive extension.
445 The kernel-doc directive is of the format::
447   .. kernel-doc:: source
458   The *source-pattern* is useful when the kernel-doc comments have been placed
464     .. kernel-doc:: lib/bitmap.c
467     .. kernel-doc:: include/net/mac80211.h
477     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
487     .. kernel-doc:: lib/bitmap.c
490     .. kernel-doc:: lib/idr.c
498     .. kernel-doc:: lib/bitmap.c
504 doc: *title*
505   Include documentation for the ``DOC:`` paragraph identified by *title* in
513     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
514        :doc: High Definition Audio over HDMI and Display Port
516 Without options, the kernel-doc directive includes all documentation comments
519 The kernel-doc extension is included in the kernel source tree, at
521 ``scripts/kernel-doc`` script to extract the documentation comments from the
526 How to use kernel-doc to generate man pages
529 If you just want to use kernel-doc to generate man pages you can do this
532   $ scripts/kernel-doc -man \
539   $ scripts/kernel-doc -man \
543   $ scripts/kernel-doc -man \