Documentation/doc-guide/kernel-doc.rst

1 .. title:: Kernel-doc comments
4 Writing kernel-doc comments
8 comments in the kernel-doc format to describe the functions, types
12 .. note:: The kernel-doc format is deceptively similar to javadoc,
13    gtk-doc or Doxygen, yet distinctively different, for historical
14    reasons. The kernel source contains tens of thousands of kernel-doc
17 .. note:: kernel-doc does not cover Rust code: please see
20 The kernel-doc structure is extracted from the comments, and proper
22 generated from them. The descriptions are filtered for special kernel-doc
25 .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
28 ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
30 to be used by modules should also have kernel-doc comments.
32 It is good practice to also provide kernel-doc formatted documentation
34 ``static``). We also recommend providing kernel-doc formatted
39 How to format kernel-doc comments
42 The opening comment mark ``/**`` is used for kernel-doc comments. The
43 ``kernel-doc`` tool will extract comments marked this way. The rest of
47 The function and type kernel-doc comments should be placed just before
50 overview kernel-doc comments may be placed anywhere at the top indentation
53 Running the ``kernel-doc`` tool with increased verbosity and without actual
57 	scripts/kernel-doc -v -none drivers/foo/bar.c
67 The general format of a function and function-like macro kernel-doc comment is::
120 be written in kernel-doc notation as::
177 The general format of a struct, union, and enum kernel-doc comment is::
288 on a line of their own, like all other kernel-doc comments::
322 The general format of a typedef kernel-doc comment is::
347 The following special patterns are recognized in the kernel-doc comment
351 .. attention:: The below are **only** recognized within kernel-doc comments,
368   meaning either by kernel-doc script or by reStructuredText.
397 defined in the kernel-doc comments from reStructuredText documents.
420 kernel-doc documentation blocks that are free-form comments instead of being
421 kernel-doc for functions, structures, unions, enums, or typedefs. This could be
425 This is done by using a ``DOC:`` section keyword with a section title.
430    * DOC: Theory of Operation
441 The title following ``DOC:`` acts as a heading within the source file, but also
446 Including kernel-doc comments
450 documents using a dedicated kernel-doc Sphinx directive extension.
452 The kernel-doc directive is of the format::
454   .. kernel-doc:: source
465   The *source-pattern* is useful when the kernel-doc comments have been placed
471     .. kernel-doc:: lib/bitmap.c
474     .. kernel-doc:: include/net/mac80211.h
484     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
494     .. kernel-doc:: lib/bitmap.c
497     .. kernel-doc:: lib/idr.c
505     .. kernel-doc:: lib/bitmap.c
511 doc: *title*
512   Include documentation for the ``DOC:`` paragraph identified by *title* in
520     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
521        :doc: High Definition Audio over HDMI and Display Port
523 Without options, the kernel-doc directive includes all documentation comments
526 The kernel-doc extension is included in the kernel source tree, at
528 ``scripts/kernel-doc`` script to extract the documentation comments from the
533 How to use kernel-doc to generate man pages
536 If you just want to use kernel-doc to generate man pages you can do this
539   $ scripts/kernel-doc -man \
546   $ scripts/kernel-doc -man \
550   $ scripts/kernel-doc -man \