^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) Writing kernel-doc comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) The Linux kernel source files may contain structured documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) comments in the kernel-doc format to describe the functions, types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) and design of the code. It is easier to keep documentation up-to-date
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) when it is embedded in source files.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) .. note:: The kernel-doc format is deceptively similar to javadoc,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) gtk-doc or Doxygen, yet distinctively different, for historical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) reasons. The kernel source contains tens of thousands of kernel-doc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) comments. Please stick to the style described here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) The kernel-doc structure is extracted from the comments, and proper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) `Sphinx C Domain`_ function and type descriptions with anchors are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) generated from them. The descriptions are filtered for special kernel-doc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) highlights and cross-references. See below for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) .. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) Every function that is exported to loadable modules using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) comment. Functions and data structures in header files which are intended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) to be used by modules should also have kernel-doc comments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) It is good practice to also provide kernel-doc formatted documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) for functions externally visible to other kernel files (not marked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) ``static``). We also recommend providing kernel-doc formatted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) documentation for private (file ``static``) routines, for consistency of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) kernel source code layout. This is lower priority and at the discretion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) of the maintainer of that kernel source file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) How to format kernel-doc comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) ---------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) The opening comment mark ``/**`` is used for kernel-doc comments. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) ``kernel-doc`` tool will extract comments marked this way. The rest of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) the comment is formatted like a normal multi-line comment with a column
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) of asterisks on the left side, closing with ``*/`` on a line by itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) The function and type kernel-doc comments should be placed just before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) the function or type being described in order to maximise the chance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) that somebody changing the code will also change the documentation. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) overview kernel-doc comments may be placed anywhere at the top indentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) level.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Running the ``kernel-doc`` tool with increased verbosity and without actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) output generation may be used to verify proper formatting of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) documentation comments. For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) scripts/kernel-doc -v -none drivers/foo/bar.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) The documentation format is verified by the kernel build when it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) requested to perform extra gcc checks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) make W=n
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Function documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) The general format of a function and function-like macro kernel-doc comment is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) * function_name() - Brief description of function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) * @arg1: Describe the first argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) * @arg2: Describe the second argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) * One can provide multiple line descriptions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) * for arguments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) * A longer description, with more discussion of the function function_name()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) * that might be useful to those using or modifying it. Begins with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) * empty comment line, and may include additional embedded empty
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) * comment lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) * The longer description may have multiple paragraphs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) * Context: Describes whether the function can sleep, what locks it takes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) * releases, or expects to be held. It can extend over multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) * lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) * Return: Describe the return value of function_name.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) * The return value description can also have multiple paragraphs, and should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) * be placed at the end of the comment block.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) The brief description following the function name may span multiple lines, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) ends with an argument description, a blank comment line, or the end of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) comment block.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Function parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) ~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Each function argument should be described in order, immediately following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) the short function description. Do not leave a blank line between the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) function description and the arguments, nor between the arguments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Each ``@argument:`` description may span multiple lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) If the ``@argument`` description has multiple lines, the continuation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) of the description should start at the same column as the previous line::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) * @argument: some long description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) * that continues on next lines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) or::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) * @argument:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) * some long description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) * that continues on next lines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) If a function has a variable number of arguments, its description should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) be written in kernel-doc notation as::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) * @...: description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) Function context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) ~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The context in which a function can be called should be described in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) section named ``Context``. This should include whether the function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) sleeps or can be called from interrupt context, as well as what locks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) it takes, releases and expects to be held by its caller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) * Context: Any context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) * Context: Any context. Takes and releases the RCU lock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) * Context: Any context. Expects <lock> to be held by caller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) * Context: Process context. May sleep if @gfp flags permit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) * Context: Process context. Takes and releases <mutex>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) * Context: Softirq or process context. Takes and releases <lock>, BH-safe.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) * Context: Interrupt context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Return values
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) ~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) The return value, if any, should be described in a dedicated section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) named ``Return``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) #) The multi-line descriptive text you provide does *not* recognize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) line breaks, so if you try to format some text nicely, as in::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) * Return:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) * 0 - OK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) * -EINVAL - invalid argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) * -ENOMEM - out of memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) this will all run together and produce::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) So, in order to produce the desired line breaks, you need to use a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) ReST list, e. g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) * Return:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) * * 0 - OK to runtime suspend the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) * * -EBUSY - Device should not be runtime suspended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) #) If the descriptive text you provide has lines that begin with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) some phrase followed by a colon, each of those phrases will be taken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) as a new section heading, which probably won't produce the desired
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) effect.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Structure, union, and enumeration documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) -----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) The general format of a struct, union, and enum kernel-doc comment is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) * struct struct_name - Brief description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) * @member1: Description of member1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) * @member2: Description of member2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) * One can provide multiple line descriptions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) * for members.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) * Description of the structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) You can replace the ``struct`` in the above example with ``union`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ``enum`` to describe unions or enums. ``member`` is used to mean struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) and union member names as well as enumerations in an enum.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) The brief description following the structure name may span multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) lines, and ends with a member description, a blank comment line, or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) end of the comment block.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) Members
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) Members of structs, unions and enums should be documented the same way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) as function parameters; they immediately succeed the short description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) and may be multi-line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Inside a struct or union description, you can use the ``private:`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) ``public:`` comment tags. Structure fields that are inside a ``private:``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) area are not listed in the generated output documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) The ``private:`` and ``public:`` tags must begin immediately following a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) ``/*`` comment marker. They may optionally include comments between the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) ``:`` and the ending ``*/`` marker.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) * struct my_struct - short description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) * @a: first member
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) * @b: second member
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) * @d: fourth member
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) * Longer description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) struct my_struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) int a;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) int b;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) /* private: internal use only */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) int c;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) /* public: the next one is public */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) int d;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) Nested structs/unions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) It is possible to document nested structs and unions, like::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) * struct nested_foobar - a struct with nested unions and structs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) * @memb1: first member of anonymous union/anonymous struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) * @memb2: second member of anonymous union/anonymous struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) * @memb3: third member of anonymous union/anonymous struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) * @memb4: fourth member of anonymous union/anonymous struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) * @bar: non-anonymous union
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) * @bar.st1: struct st1 inside @bar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) * @bar.st2: struct st2 inside @bar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) * @bar.st1.memb1: first member of struct st1 on union bar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) * @bar.st1.memb2: second member of struct st1 on union bar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) * @bar.st2.memb1: first member of struct st2 on union bar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) * @bar.st2.memb2: second member of struct st2 on union bar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) struct nested_foobar {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) /* Anonymous union/struct*/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) int memb1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) int memb2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) void *memb3;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) int memb4;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) int memb1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) int memb2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) } st1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) void *memb1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) int memb2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) } st2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) } bar;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) #) When documenting nested structs or unions, if the struct/union ``foo``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) is named, the member ``bar`` inside it should be documented as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) ``@foo.bar:``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) #) When the nested struct/union is anonymous, the member ``bar`` in it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) should be documented as ``@bar:``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) In-line member documentation comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) The structure members may also be documented in-line within the definition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) There are two styles, single-line comments where both the opening ``/**`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) closing ``*/`` are on the same line, and multi-line comments where they are each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) on a line of their own, like all other kernel-doc comments::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) * struct foo - Brief description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) * @foo: The Foo member.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) struct foo {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) int foo;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) * @bar: The Bar member.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) int bar;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) * @baz: The Baz member.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) * Here, the member description may contain several paragraphs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) int baz;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) /** @foobar: Single line description. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) int foobar;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) /** @bar2: Description for struct @bar2 inside @foo */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) struct {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) * @bar2.barbar: Description for @barbar inside @foo.bar2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) int barbar;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) } bar2;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) Typedef documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) The general format of a typedef kernel-doc comment is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) * typedef type_name - Brief description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) * Description of the type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) Typedefs with function prototypes can also be documented::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) * typedef type_name - Brief description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) * @arg1: description of arg1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) * @arg2: description of arg2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) * Description of the type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) * Context: Locking context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) * Return: Meaning of the return value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) Highlights and cross-references
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) The following special patterns are recognized in the kernel-doc comment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) descriptive text and converted to proper reStructuredText markup and `Sphinx C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) Domain`_ references.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) .. attention:: The below are **only** recognized within kernel-doc comments,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) **not** within normal reStructuredText documents.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) ``funcname()``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) Function reference.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) ``@parameter``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) Name of a function parameter. (No cross-referencing, just formatting.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) ``%CONST``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) Name of a constant. (No cross-referencing, just formatting.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) ````literal````
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) A literal block that should be handled as-is. The output will use a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) ``monospaced font``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) Useful if you need to use special characters that would otherwise have some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) meaning either by kernel-doc script or by reStructuredText.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) This is particularly useful if you need to use things like ``%ph`` inside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) a function description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) ``$ENVVAR``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) Name of an environment variable. (No cross-referencing, just formatting.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) ``&struct name``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) Structure reference.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) ``&enum name``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) Enum reference.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) ``&typedef name``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) Typedef reference.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) ``&struct_name->member`` or ``&struct_name.member``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) Structure or union member reference. The cross-reference will be to the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) or union definition, not the member directly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) ``&name``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) A generic type reference. Prefer using the full reference described above
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) instead. This is mostly for legacy comments.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) Cross-referencing from reStructuredText
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) No additional syntax is needed to cross-reference the functions and types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) defined in the kernel-doc comments from reStructuredText documents.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) or ``typedef`` before types.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) For example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) See foo().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) See struct foo.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) See union bar.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) See enum baz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) See typedef meh.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) However, if you want custom text in the cross-reference link, that can be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) through the following syntax::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) See :c:func:`my custom link text for function foo <foo>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) See :c:type:`my custom link text for struct bar <bar>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) For further details, please refer to the `Sphinx C Domain`_ documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) Overview documentation comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) To facilitate having source code and comments close together, you can include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) kernel-doc documentation blocks that are free-form comments instead of being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) kernel-doc for functions, structures, unions, enums, or typedefs. This could be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) used for something like a theory of operation for a driver or library code, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) This is done by using a ``DOC:`` section keyword with a section title.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) The general format of an overview or high-level documentation comment is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) /**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) * DOC: Theory of Operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) * The whizbang foobar is a dilly of a gizmo. It can do whatever you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) * want it to do, at any time. It reads your mind. Here's how it works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) * foo bar splat
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) * The only drawback to this gizmo is that is can sometimes damage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) * hardware, software, or its subject(s).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) The title following ``DOC:`` acts as a heading within the source file, but also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) as an identifier for extracting the documentation comment. Thus, the title must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) be unique within the file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) Including kernel-doc comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) The documentation comments may be included in any of the reStructuredText
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) documents using a dedicated kernel-doc Sphinx directive extension.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) The kernel-doc directive is of the format::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) .. kernel-doc:: source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) :option:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) The *source* is the path to a source file, relative to the kernel source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) tree. The following directive options are supported:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) export: *[source-pattern ...]*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) Include documentation for all functions in *source* that have been exported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) of the files specified by *source-pattern*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) The *source-pattern* is useful when the kernel-doc comments have been placed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) the function definitions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) .. kernel-doc:: lib/bitmap.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) :export:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) .. kernel-doc:: include/net/mac80211.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) :export: net/mac80211/*.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) internal: *[source-pattern ...]*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) Include documentation for all functions and types in *source* that have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) in *source* or in any of the files specified by *source-pattern*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) :internal:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) identifiers: *[ function/type ...]*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) Include documentation for each *function* and *type* in *source*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) If no *function* is specified, the documentation for all functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) and types in the *source* will be included.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) .. kernel-doc:: lib/bitmap.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) :identifiers: bitmap_parselist bitmap_parselist_user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) .. kernel-doc:: lib/idr.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) :identifiers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) no-identifiers: *[ function/type ...]*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) Exclude documentation for each *function* and *type* in *source*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) .. kernel-doc:: lib/bitmap.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) :no-identifiers: bitmap_parselist
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) functions: *[ function/type ...]*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) This is an alias of the 'identifiers' directive and deprecated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) doc: *title*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) Include documentation for the ``DOC:`` paragraph identified by *title* in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) is only used as an identifier for the paragraph, and is not included in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) output. Please make sure to have an appropriate heading in the enclosing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) reStructuredText document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) :doc: High Definition Audio over HDMI and Display Port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) Without options, the kernel-doc directive includes all documentation comments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) from the source file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) The kernel-doc extension is included in the kernel source tree, at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) ``scripts/kernel-doc`` script to extract the documentation comments from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) source.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) .. _kernel_doc:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) How to use kernel-doc to generate man pages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) -------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) If you just want to use kernel-doc to generate man pages you can do this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) from the kernel git tree::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) $ scripts/kernel-doc -man \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) $(git grep -l '/\*\*' -- :^Documentation :^tools) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) | scripts/split-man.pl /tmp/man
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) Some older versions of git do not support some of the variants of syntax for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) path exclusion. One of the following commands may work for those versions::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) $ scripts/kernel-doc -man \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) | scripts/split-man.pl /tmp/man
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) $ scripts/kernel-doc -man \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) | scripts/split-man.pl /tmp/man
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags