1Including kernel-doc comments 2============================= 3 4The Linux kernel source files may contain structured documentation comments, or 5kernel-doc comments to describe the functions and types and design of the 6code. The documentation comments may be included to any of the reStructuredText 7documents using a dedicated kernel-doc Sphinx directive extension. 8 9The kernel-doc directive is of the format:: 10 11 .. kernel-doc:: source 12 :option: 13 14The *source* is the path to a source file, relative to the kernel source 15tree. The following directive options are supported: 16 17export: *[source-pattern ...]* 18 Include documentation for all functions in *source* that have been exported 19 using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any 20 of the files specified by *source-pattern*. 21 22 The *source-pattern* is useful when the kernel-doc comments have been placed 23 in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to 24 the function definitions. 25 26 Examples:: 27 28 .. kernel-doc:: lib/bitmap.c 29 :export: 30 31 .. kernel-doc:: include/net/mac80211.h 32 :export: net/mac80211/*.c 33 34internal: *[source-pattern ...]* 35 Include documentation for all functions and types in *source* that have 36 **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either 37 in *source* or in any of the files specified by *source-pattern*. 38 39 Example:: 40 41 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 42 :internal: 43 44doc: *title* 45 Include documentation for the ``DOC:`` paragraph identified by *title* in 46 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* 47 is only used as an identifier for the paragraph, and is not included in the 48 output. Please make sure to have an appropriate heading in the enclosing 49 reStructuredText document. 50 51 Example:: 52 53 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 54 :doc: High Definition Audio over HDMI and Display Port 55 56functions: *function* *[...]* 57 Include documentation for each *function* in *source*. 58 59 Example:: 60 61 .. kernel-doc:: lib/bitmap.c 62 :functions: bitmap_parselist bitmap_parselist_user 63 64Without options, the kernel-doc directive includes all documentation comments 65from the source file. 66 67The kernel-doc extension is included in the kernel source tree, at 68``Documentation/sphinx/kernel-doc.py``. Internally, it uses the 69``scripts/kernel-doc`` script to extract the documentation comments from the 70source. 71 72.. _kernel_doc: 73 74Writing kernel-doc comments 75=========================== 76 77In order to provide embedded, "C" friendly, easy to maintain, but consistent and 78extractable overview, function and type documentation, the Linux kernel has 79adopted a consistent style for documentation comments. The format for this 80documentation is called the kernel-doc format, described below. This style 81embeds the documentation within the source files, using a few simple conventions 82for adding documentation paragraphs and documenting functions and their 83parameters, structures and unions and their members, enumerations, and typedefs. 84 85.. note:: The kernel-doc format is deceptively similar to gtk-doc or Doxygen, 86 yet distinctively different, for historical reasons. The kernel source 87 contains tens of thousands of kernel-doc comments. Please stick to the style 88 described here. 89 90The ``scripts/kernel-doc`` script is used by the Sphinx kernel-doc extension in 91the documentation build to extract this embedded documentation into the various 92HTML, PDF, and other format documents. 93 94In order to provide good documentation of kernel functions and data structures, 95please use the following conventions to format your kernel-doc comments in the 96Linux kernel source. 97 98How to format kernel-doc comments 99--------------------------------- 100 101The opening comment mark ``/**`` is reserved for kernel-doc comments. Only 102comments so marked will be considered by the ``kernel-doc`` tool. Use it only 103for comment blocks that contain kernel-doc formatted comments. The usual ``*/`` 104should be used as the closing comment marker. The lines in between should be 105prefixed by `` * `` (space star space). 106 107The function and type kernel-doc comments should be placed just before the 108function or type being described. The overview kernel-doc comments may be freely 109placed at the top indentation level. 110 111Example kernel-doc function comment:: 112 113 /** 114 * foobar() - Brief description of foobar. 115 * @arg: Description of argument of foobar. 116 * 117 * Longer description of foobar. 118 * 119 * Return: Description of return value of foobar. 120 */ 121 int foobar(int arg) 122 123The format is similar for documentation for structures, enums, paragraphs, 124etc. See the sections below for details. 125 126The kernel-doc structure is extracted from the comments, and proper `Sphinx C 127Domain`_ function and type descriptions with anchors are generated for them. The 128descriptions are filtered for special kernel-doc highlights and 129cross-references. See below for details. 130 131.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html 132 133Highlights and cross-references 134------------------------------- 135 136The following special patterns are recognized in the kernel-doc comment 137descriptive text and converted to proper reStructuredText markup and `Sphinx C 138Domain`_ references. 139 140.. attention:: The below are **only** recognized within kernel-doc comments, 141 **not** within normal reStructuredText documents. 142 143``funcname()`` 144 Function reference. 145 146``@parameter`` 147 Name of a function parameter. (No cross-referencing, just formatting.) 148 149``%CONST`` 150 Name of a constant. (No cross-referencing, just formatting.) 151 152``$ENVVAR`` 153 Name of an environment variable. (No cross-referencing, just formatting.) 154 155``&struct name`` 156 Structure reference. 157 158``&enum name`` 159 Enum reference. 160 161``&typedef name`` 162 Typedef reference. 163 164``&struct_name->member`` or ``&struct_name.member`` 165 Structure or union member reference. The cross-reference will be to the struct 166 or union definition, not the member directly. 167 168``&name`` 169 A generic type reference. Prefer using the full reference described above 170 instead. This is mostly for legacy comments. 171 172Cross-referencing from reStructuredText 173~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 174 175To cross-reference the functions and types defined in the kernel-doc comments 176from reStructuredText documents, please use the `Sphinx C Domain`_ 177references. For example:: 178 179 See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. 180 181While the type reference works with just the type name, without the 182struct/union/enum/typedef part in front, you may want to use:: 183 184 See :c:type:`struct foo <foo>`. 185 See :c:type:`union bar <bar>`. 186 See :c:type:`enum baz <baz>`. 187 See :c:type:`typedef meh <meh>`. 188 189This will produce prettier links, and is in line with how kernel-doc does the 190cross-references. 191 192For further details, please refer to the `Sphinx C Domain`_ documentation. 193 194Function documentation 195---------------------- 196 197The general format of a function and function-like macro kernel-doc comment is:: 198 199 /** 200 * function_name() - Brief description of function. 201 * @arg1: Describe the first argument. 202 * @arg2: Describe the second argument. 203 * One can provide multiple line descriptions 204 * for arguments. 205 * 206 * A longer description, with more discussion of the function function_name() 207 * that might be useful to those using or modifying it. Begins with an 208 * empty comment line, and may include additional embedded empty 209 * comment lines. 210 * 211 * The longer description may have multiple paragraphs. 212 * 213 * Return: Describe the return value of foobar. 214 * 215 * The return value description can also have multiple paragraphs, and should 216 * be placed at the end of the comment block. 217 */ 218 219The brief description following the function name may span multiple lines, and 220ends with an ``@argument:`` description, a blank comment line, or the end of the 221comment block. 222 223The kernel-doc function comments describe each parameter to the function, in 224order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions 225must begin on the very next line following the opening brief function 226description line, with no intervening blank comment lines. The ``@argument:`` 227descriptions may span multiple lines. The continuation lines may contain 228indentation. If a function parameter is ``...`` (varargs), it should be listed 229in kernel-doc notation as: ``@...:``. 230 231The return value, if any, should be described in a dedicated section at the end 232of the comment starting with "Return:". 233 234Structure, union, and enumeration documentation 235----------------------------------------------- 236 237The general format of a struct, union, and enum kernel-doc comment is:: 238 239 /** 240 * struct struct_name - Brief description. 241 * @member_name: Description of member member_name. 242 * 243 * Description of the structure. 244 */ 245 246Below, "struct" is used to mean structs, unions and enums, and "member" is used 247to mean struct and union members as well as enumerations in an enum. 248 249The brief description following the structure name may span multiple lines, and 250ends with a ``@member:`` description, a blank comment line, or the end of the 251comment block. 252 253The kernel-doc data structure comments describe each member of the structure, in 254order, with the ``@member:`` descriptions. The ``@member:`` descriptions must 255begin on the very next line following the opening brief function description 256line, with no intervening blank comment lines. The ``@member:`` descriptions may 257span multiple lines. The continuation lines may contain indentation. 258 259In-line member documentation comments 260~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 261 262The structure members may also be documented in-line within the definition. 263There are two styles, single-line comments where both the opening ``/**`` and 264closing ``*/`` are on the same line, and multi-line comments where they are each 265on a line of their own, like all other kernel-doc comments:: 266 267 /** 268 * struct foo - Brief description. 269 * @foo: The Foo member. 270 */ 271 struct foo { 272 int foo; 273 /** 274 * @bar: The Bar member. 275 */ 276 int bar; 277 /** 278 * @baz: The Baz member. 279 * 280 * Here, the member description may contain several paragraphs. 281 */ 282 int baz; 283 /** @foobar: Single line description. */ 284 int foobar; 285 } 286 287Private members 288~~~~~~~~~~~~~~~ 289 290Inside a struct description, you can use the "private:" and "public:" comment 291tags. Structure fields that are inside a "private:" area are not listed in the 292generated output documentation. The "private:" and "public:" tags must begin 293immediately following a ``/*`` comment marker. They may optionally include 294comments between the ``:`` and the ending ``*/`` marker. 295 296Example:: 297 298 /** 299 * struct my_struct - short description 300 * @a: first member 301 * @b: second member 302 * 303 * Longer description 304 */ 305 struct my_struct { 306 int a; 307 int b; 308 /* private: internal use only */ 309 int c; 310 }; 311 312 313Typedef documentation 314--------------------- 315 316The general format of a typedef kernel-doc comment is:: 317 318 /** 319 * typedef type_name - Brief description. 320 * 321 * Description of the type. 322 */ 323 324Overview documentation comments 325------------------------------- 326 327To facilitate having source code and comments close together, you can include 328kernel-doc documentation blocks that are free-form comments instead of being 329kernel-doc for functions, structures, unions, enums, or typedefs. This could be 330used for something like a theory of operation for a driver or library code, for 331example. 332 333This is done by using a ``DOC:`` section keyword with a section title. 334 335The general format of an overview or high-level documentation comment is:: 336 337 /** 338 * DOC: Theory of Operation 339 * 340 * The whizbang foobar is a dilly of a gizmo. It can do whatever you 341 * want it to do, at any time. It reads your mind. Here's how it works. 342 * 343 * foo bar splat 344 * 345 * The only drawback to this gizmo is that is can sometimes damage 346 * hardware, software, or its subject(s). 347 */ 348 349The title following ``DOC:`` acts as a heading within the source file, but also 350as an identifier for extracting the documentation comment. Thus, the title must 351be unique within the file. 352 353Recommendations 354--------------- 355 356We definitely need kernel-doc formatted documentation for functions that are 357exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL``. 358 359We also look to provide kernel-doc formatted documentation for functions 360externally visible to other kernel files (not marked "static"). 361 362We also recommend providing kernel-doc formatted documentation for private (file 363"static") routines, for consistency of kernel source code layout. But this is 364lower priority and at the discretion of the MAINTAINER of that kernel source 365file. 366 367Data structures visible in kernel include files should also be documented using 368kernel-doc formatted comments. 369