kernel-doc.rst 17 KB

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