sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/doc-guide/kernel-docmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/pt_BR/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/doc-guide/kernel-docmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hWriting kernel-doc commentsh]hWriting kernel-doc comments}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhB/var/lib/git/docbuild/linux/Documentation/doc-guide/kernel-doc.rsthKubh paragraph)}(hThe Linux kernel source files may contain structured documentation comments in the kernel-doc format to describe the functions, types and design of the code. It is easier to keep documentation up-to-date when it is embedded in source files.h]hThe Linux kernel source files may contain structured documentation comments in the kernel-doc format to describe the functions, types and design of the code. It is easier to keep documentation up-to-date when it is embedded in source files.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhnote)}(hThe kernel-doc format is deceptively similar to javadoc, gtk-doc or Doxygen, yet distinctively different, for historical reasons. The kernel source contains tens of thousands of kernel-doc comments. Please stick to the style described here.h]h)}(hThe kernel-doc format is deceptively similar to javadoc, gtk-doc or Doxygen, yet distinctively different, for historical reasons. The kernel source contains tens of thousands of kernel-doc comments. Please stick to the style described here.h]hThe kernel-doc format is deceptively similar to javadoc, gtk-doc or Doxygen, yet distinctively different, for historical reasons. The kernel source contains tens of thousands of kernel-doc comments. Please stick to the style described here.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hckernel-doc does not cover Rust code: please see Documentation/rust/general-information.rst instead.h]h)}(hckernel-doc does not cover Rust code: please see Documentation/rust/general-information.rst instead.h]hckernel-doc does not cover Rust code: please see Documentation/rust/general-information.rst instead.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hXThe kernel-doc structure is extracted from the comments, and proper `Sphinx C Domain`_ function and type descriptions with anchors are generated from them. The descriptions are filtered for special kernel-doc highlights and cross-references. See below for details.h](hDThe kernel-doc structure is extracted from the comments, and proper }(hj hhhNhNubh reference)}(h`Sphinx C Domain`_h]hSphinx C Domain}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameSphinx C Domainrefuri0http://www.sphinx-doc.org/en/stable/domains.htmluh1jhj resolvedKubh function and type descriptions with anchors are generated from them. The descriptions are filtered for special kernel-doc highlights and cross-references. See below for details.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhtarget)}(hE.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.htmlh]h}(h]sphinx-c-domainah ]h"]sphinx c domainah$]h&]j'j(uh1j4hKhhhhhhʌ referencedKubh)}(hXEvery function that is exported to loadable modules using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` should have a kernel-doc comment. Functions and data structures in header files which are intended to be used by modules should also have kernel-doc comments.h](h:Every function that is exported to loadable modules using }(hjChhhNhNubhliteral)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjCubh or }(hjChhhNhNubjL)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjCubh should have a kernel-doc comment. Functions and data structures in header files which are intended to be used by modules should also have kernel-doc comments.}(hjChhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXIt is good practice to also provide kernel-doc formatted documentation for functions externally visible to other kernel files (not marked ``static``). We also recommend providing kernel-doc formatted documentation for private (file ``static``) routines, for consistency of kernel source code layout. This is lower priority and at the discretion of the maintainer of that kernel source file.h](hIt is good practice to also provide kernel-doc formatted documentation for functions externally visible to other kernel files (not marked }(hjwhhhNhNubjL)}(h ``static``h]hstatic}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjwubhT). We also recommend providing kernel-doc formatted documentation for private (file }(hjwhhhNhNubjL)}(h ``static``h]hstatic}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjwubh) routines, for consistency of kernel source code layout. This is lower priority and at the discretion of the maintainer of that kernel source file.}(hjwhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hhh](h)}(h!How to format kernel-doc commentsh]h!How to format kernel-doc comments}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK(ubh)}(hXThe opening comment mark ``/**`` is used for kernel-doc comments. The ``kernel-doc`` tool will extract comments marked this way. The rest of the comment is formatted like a normal multi-line comment with a column of asterisks on the left side, closing with ``*/`` on a line by itself.h](hThe opening comment mark }(hjhhhNhNubjL)}(h``/**``h]h/**}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh& is used for kernel-doc comments. The }(hjhhhNhNubjL)}(h``kernel-doc``h]h kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh tool will extract comments marked this way. The rest of the comment is formatted like a normal multi-line comment with a column of asterisks on the left side, closing with }(hjhhhNhNubjL)}(h``*/``h]h*/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh on a line by itself.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubh)}(hX%The function and type kernel-doc comments should be placed just before the function or type being described in order to maximise the chance that somebody changing the code will also change the documentation. The overview kernel-doc comments may be placed anywhere at the top indentation level.h]hX%The function and type kernel-doc comments should be placed just before the function or type being described in order to maximise the chance that somebody changing the code will also change the documentation. The overview kernel-doc comments may be placed anywhere at the top indentation level.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK/hjhhubh)}(hRunning the ``kernel-doc`` tool with increased verbosity and without actual output generation may be used to verify proper formatting of the documentation comments. For example::h](h Running the }(hj hhhNhNubjL)}(h``kernel-doc``h]h kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh tool with increased verbosity and without actual output generation may be used to verify proper formatting of the documentation comments. For example:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK5hjhhubh literal_block)}(h0tools/docs/kernel-doc -v -none drivers/foo/bar.ch]h0tools/docs/kernel-doc -v -none drivers/foo/bar.c}hj.sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j,hhhK9hjhhubh)}(hThe documentation format of ``.c`` files is also verified by the kernel build when it is requested to perform extra gcc checks::h](hThe documentation format of }(hj>hhhNhNubjL)}(h``.c``h]h.c}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj>ubh] files is also verified by the kernel build when it is requested to perform extra gcc checks:}(hj>hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK;hjhhubj-)}(hmake W=nh]hmake W=n}hj^sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhK>hjhhubh)}(hqHowever, the above command does not verify header files. These should be checked separately using ``kernel-doc``.h](hbHowever, the above command does not verify header files. These should be checked separately using }(hjlhhhNhNubjL)}(h``kernel-doc``h]h kernel-doc}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjlubh.}(hjlhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK@hjhhubeh}(h]!how-to-format-kernel-doc-commentsah ]h"]!how to format kernel-doc commentsah$]h&]uh1hhhhhhhhK(ubh)}(hhh](h)}(hFunction documentationh]hFunction documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKDubh)}(hPThe general format of a function and function-like macro kernel-doc comment is::h]hOThe general format of a function and function-like macro kernel-doc comment is:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjhhubj-)}(hX^/** * function_name() - Brief description of function. * @arg1: Describe the first argument. * @arg2: Describe the second argument. * One can provide multiple line descriptions * for arguments. * * A longer description, with more discussion of the function function_name() * that might be useful to those using or modifying it. Begins with an * empty comment line, and may include additional embedded empty * comment lines. * * The longer description may have multiple paragraphs. * * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. */h]hX^/** * function_name() - Brief description of function. * @arg1: Describe the first argument. * @arg2: Describe the second argument. * One can provide multiple line descriptions * for arguments. * * A longer description, with more discussion of the function function_name() * that might be useful to those using or modifying it. Begins with an * empty comment line, and may include additional embedded empty * comment lines. * * The longer description may have multiple paragraphs. * * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. */}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKHhjhhubh)}(hThe brief description following the function name may span multiple lines, and ends with an argument description, a blank comment line, or the end of the comment block.h]hThe brief description following the function name may span multiple lines, and ends with an argument description, a blank comment line, or the end of the comment block.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hjhhubh)}(hhh](h)}(hFunction parametersh]hFunction parameters}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKdubh)}(hEach function argument should be described in order, immediately following the short function description. Do not leave a blank line between the function description and the arguments, nor between the arguments.h]hEach function argument should be described in order, immediately following the short function description. Do not leave a blank line between the function description and the arguments, nor between the arguments.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKfhjhhubh)}(h8Each ``@argument:`` description may span multiple lines.h](hEach }(hjhhhNhNubjL)}(h``@argument:``h]h @argument:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh% description may span multiple lines.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubh)}(hXGIf the ``@argument`` description has multiple lines, the continuation of the description should start at the same column as the previous line:: * @argument: some long description * that continues on next lines or:: * @argument: * some long description * that continues on next linesh](h)}(hIf the ``@argument`` description has multiple lines, the continuation of the description should start at the same column as the previous line::h](hIf the }(hjhhhNhNubjL)}(h ``@argument``h]h @argument}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubhz description has multiple lines, the continuation of the description should start at the same column as the previous line:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKnhjubj-)}(hL* @argument: some long description * that continues on next linesh]hL* @argument: some long description * that continues on next lines}hj2sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKqhjubh)}(hor::h]hor:}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKthjubj-)}(hS* @argument: * some long description * that continues on next linesh]hS* @argument: * some long description * that continues on next lines}hjNsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKvhjubeh}(h]h ]h"]h$]h&]uh1hhjhhhhhNubh)}(hoIf a function has a variable number of arguments, its description should be written in kernel-doc notation as::h]hnIf a function has a variable number of arguments, its description should be written in kernel-doc notation as:}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKzhjhhubj-)}(h* @...: descriptionh]h* @...: description}hjpsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhK}hjhhubeh}(h]function-parametersah ]h"]function parametersah$]h&]uh1hhjhhhhhKdubh)}(hhh](h)}(hFunction contexth]hFunction context}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hX The context in which a function can be called should be described in a section named ``Context``. This should include whether the function sleeps or can be called from interrupt context, as well as what locks it takes, releases and expects to be held by its caller.h](hUThe context in which a function can be called should be described in a section named }(hjhhhNhNubjL)}(h ``Context``h]hContext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh. This should include whether the function sleeps or can be called from interrupt context, as well as what locks it takes, releases and expects to be held by its caller.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h Examples::h]h Examples:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj-)}(hXj* Context: Any context. * Context: Any context. Takes and releases the RCU lock. * Context: Any context. Expects to be held by caller. * Context: Process context. May sleep if @gfp flags permit. * Context: Process context. Takes and releases . * Context: Softirq or process context. Takes and releases , BH-safe. * Context: Interrupt context.h]hXj* Context: Any context. * Context: Any context. Takes and releases the RCU lock. * Context: Any context. Expects to be held by caller. * Context: Process context. May sleep if @gfp flags permit. * Context: Process context. Takes and releases . * Context: Softirq or process context. Takes and releases , BH-safe. * Context: Interrupt context.}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKhjhhubeh}(h]function-contextah ]h"]function contextah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h Return valuesh]h Return values}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hgThe return value, if any, should be described in a dedicated section named ``Return`` (or ``Returns``).h](hKThe return value, if any, should be described in a dedicated section named }(hjhhhNhNubjL)}(h ``Return``h]hReturn}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh (or }(hjhhhNhNubjL)}(h ``Returns``h]hReturns}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX #) The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in:: * Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memory this will all run together and produce:: Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory So, in order to produce the desired line breaks, you need to use a ReST list, e. g.:: * Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspended #) If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which probably won't produce the desired effect.h]henumerated_list)}(hhh](h list_item)}(hXThe multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in:: * Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memory this will all run together and produce:: Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory So, in order to produce the desired line breaks, you need to use a ReST list, e. g.:: * Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspended h](h)}(hThe multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in::h](h1The multi-line descriptive text you provide does }(hj-hhhNhNubhemphasis)}(h*not*h]hnot}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj-ubhH recognize line breaks, so if you try to format some text nicely, as in:}(hj-hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj)ubj-)}(hL* Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memoryh]hL* Return: * %0 - OK * %-EINVAL - invalid argument * %-ENOMEM - out of memory}hjOsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKhj)ubh)}(h(this will all run together and produce::h]h'this will all run together and produce:}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj)ubj-)}(hAReturn: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memoryh]hAReturn: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory}hjksbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKhj)ubh)}(hUSo, in order to produce the desired line breaks, you need to use a ReST list, e. g.::h]hTSo, in order to produce the desired line breaks, you need to use a ReST list, e. g.:}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj)ubj-)}(hy* Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspendedh]hy* Return: * * %0 - OK to runtime suspend the device * * %-EBUSY - Device should not be runtime suspended}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKhj)ubeh}(h]h ]h"]h$]h&]uh1j'hj$ubj()}(hIf the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which probably won't produce the desired effect.h]h)}(hIf the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which probably won't produce the desired effect.h]hIf the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which probably won’t produce the desired effect.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j'hj$ubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix)uh1j"hjubah}(h]h ]h"]h$]h&]uh1hhjhhhNhNubeh}(h] return-valuesah ]h"] return valuesah$]h&]uh1hhjhhhhhKubeh}(h]function-documentationah ]h"]function documentationah$]h&]uh1hhhhhhhhKDubh)}(hhh](h)}(h/Structure, union, and enumeration documentationh]h/Structure, union, and enumeration documentation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hSThe general format of a ``struct``, ``union``, and ``enum`` kernel-doc comment is::h](hThe general format of a }(hjhhhNhNubjL)}(h ``struct``h]hstruct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh, }(hjhhhNhNubjL)}(h ``union``h]hunion}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh, and }(hjhhhNhNubjL)}(h``enum``h]henum}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh kernel-doc comment is:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj-)}(h/** * struct struct_name - Brief description. * @member1: Description of member1. * @member2: Description of member2. * One can provide multiple line descriptions * for members. * * Description of the structure. */h]h/** * struct struct_name - Brief description. * @member1: Description of member1. * @member2: Description of member2. * One can provide multiple line descriptions * for members. * * Description of the structure. */}hj)sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKhjhhubh)}(hYou can replace the ``struct`` in the above example with ``union`` or ``enum`` to describe unions or enums. ``member`` is used to mean ``struct`` and ``union`` member names as well as enumerations in an ``enum``.h](hYou can replace the }(hj7hhhNhNubjL)}(h ``struct``h]hstruct}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh in the above example with }(hj7hhhNhNubjL)}(h ``union``h]hunion}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh or }(hj7hhhNhNubjL)}(h``enum``h]henum}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh to describe unions or enums. }(hj7hhhNhNubjL)}(h ``member``h]hmember}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh is used to mean }(hj7hhhNhNubjL)}(h ``struct``h]hstruct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh and }(hj7hhhNhNubjL)}(h ``union``h]hunion}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh, member names as well as enumerations in an }(hj7hhhNhNubjL)}(h``enum``h]henum}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj7ubh.}(hj7hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe brief description following the structure name may span multiple lines, and ends with a member description, a blank comment line, or the end of the comment block.h]hThe brief description following the structure name may span multiple lines, and ends with a member description, a blank comment line, or the end of the comment block.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hhh](h)}(hMembersh]hMembers}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hMembers of structs, unions and enums should be documented the same way as function parameters; they immediately succeed the short description and may be multi-line.h]hMembers of structs, unions and enums should be documented the same way as function parameters; they immediately succeed the short description and may be multi-line.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hInside a ``struct`` or ``union`` description, you can use the ``private:`` and ``public:`` comment tags. Structure fields that are inside a ``private:`` area are not listed in the generated output documentation.h](h Inside a }(hjhhhNhNubjL)}(h ``struct``h]hstruct}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh or }(hjhhhNhNubjL)}(h ``union``h]hunion}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh description, you can use the }(hjhhhNhNubjL)}(h ``private:``h]hprivate:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh and }(hjhhhNhNubjL)}(h ``public:``h]hpublic:}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh2 comment tags. Structure fields that are inside a }(hjhhhNhNubjL)}(h ``private:``h]hprivate:}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh; area are not listed in the generated output documentation.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe ``private:`` and ``public:`` tags must begin immediately following a ``/*`` comment marker. They may optionally include comments between the ``:`` and the ending ``*/`` marker.h](hThe }(hjXhhhNhNubjL)}(h ``private:``h]hprivate:}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjXubh and }(hjXhhhNhNubjL)}(h ``public:``h]hpublic:}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjXubh) tags must begin immediately following a }(hjXhhhNhNubjL)}(h``/*``h]h/*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjXubhB comment marker. They may optionally include comments between the }(hjXhhhNhNubjL)}(h``:``h]h:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjXubh and the ending }(hjXhhhNhNubjL)}(h``*/``h]h*/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjXubh marker.}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXWhen ``private:`` is used on nested structs, it propagates only to inner structs/unions.h](hWhen }(hjhhhNhNubjL)}(h ``private:``h]hprivate:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubhG is used on nested structs, it propagates only to inner structs/unions.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h Example::h]hExample:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj-)}(hX/** * struct my_struct - short description * @a: first member * @b: second member * @d: fourth member * * Longer description */ struct my_struct { int a; int b; /* private: internal use only */ int c; /* public: the next one is public */ int d; };h]hX/** * struct my_struct - short description * @a: first member * @b: second member * @d: fourth member * * Longer description */ struct my_struct { int a; int b; /* private: internal use only */ int c; /* public: the next one is public */ int d; };}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhKhjhhubeh}(h]membersah ]h"]membersah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hNested structs/unionsh]hNested structs/unions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hmember`` or ``&struct_name.member`` ``struct`` or ``union`` member reference. The cross-reference will be to the ``struct`` or ``union`` definition, not the member directly. h](j) )}(h3``&struct_name->member`` or ``&struct_name.member``h](jL)}(h``&struct_name->member``h]h&struct_name->member}(hjL hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjH ubh or }(hjH hhhNhNubjL)}(h``&struct_name.member``h]h&struct_name.member}(hj^ hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjH ubeh}(h]h ]h"]h$]h&]uh1j( hhhMhjD ubjB )}(hhh]h)}(h``struct`` or ``union`` member reference. The cross-reference will be to the ``struct`` or ``union`` definition, not the member directly.h](jL)}(h ``struct``h]hstruct}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhju ubh or }(hju hhhNhNubjL)}(h ``union``h]hunion}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhju ubh6 member reference. The cross-reference will be to the }(hju hhhNhNubjL)}(h ``struct``h]hstruct}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhju ubh or }hju sbjL)}(h ``union``h]hunion}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhju ubh% definition, not the member directly.}(hju hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjr ubah}(h]h ]h"]h$]h&]uh1jA hjD ubeh}(h]h ]h"]h$]h&]uh1j" hhhMhj hhubj# )}(h``&name`` A generic type reference. Prefer using the full reference described above instead. This is mostly for legacy comments. h](j) )}(h ``&name``h]jL)}(hj h]h&name}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubah}(h]h ]h"]h$]h&]uh1j( hhhMhj ubjB )}(hhh]h)}(hvA generic type reference. Prefer using the full reference described above instead. This is mostly for legacy comments.h]hvA generic type reference. Prefer using the full reference described above instead. This is mostly for legacy comments.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jA hj ubeh}(h]h ]h"]h$]h&]uh1j" hhhMhj hhubeh}(h]h ]h"]h$]h&]uh1j hj hhhhhNubh)}(hhh](h)}(h'Cross-referencing from reStructuredTexth]h'Cross-referencing from reStructuredText}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXNo additional syntax is needed to cross-reference the functions and types defined in the kernel-doc comments from reStructuredText documents. Just end function names with ``()`` and write ``struct``, ``union``, ``enum`` or ``typedef`` before types. For example::h](hNo additional syntax is needed to cross-reference the functions and types defined in the kernel-doc comments from reStructuredText documents. Just end function names with }(hj" hhhNhNubjL)}(h``()``h]h()}(hj* hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj" ubh and write }(hj" hhhNhNubjL)}(h ``struct``h]hstruct}(hj< hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj" ubh, }(hj" hhhNhNubjL)}(h ``union``h]hunion}(hjN hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj" ubh, }hj" sbjL)}(h``enum``h]henum}(hj` hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj" ubh or }(hj" hhhNhNubjL)}(h ``typedef``h]htypedef}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj" ubh before types. For example:}(hj" hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj-)}(hHSee foo(). See struct foo. See union bar. See enum baz. See typedef meh.h]hHSee foo(). See struct foo. See union bar. See enum baz. See typedef meh.}hj sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMhj hhubh)}(hmHowever, if you want custom text in the cross-reference link, that can be done through the following syntax::h]hlHowever, if you want custom text in the cross-reference link, that can be done through the following syntax:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj-)}(hqSee :c:func:`my custom link text for function foo `. See :c:type:`my custom link text for struct bar `.h]hqSee :c:func:`my custom link text for function foo `. See :c:type:`my custom link text for struct bar `.}hj sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMhj hhubh)}(hJFor further details, please refer to the `Sphinx C Domain`_ documentation.h](h)For further details, please refer to the }(hj hhhNhNubj)}(h`Sphinx C Domain`_h]hSphinx C Domain}(hj hhhNhNubah}(h]h ]h"]h$]h&]nameSphinx C Domainj'j(uh1jhj j)Kubh documentation.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hrVariables aren't automatically cross referenced. For those, you need to explicitly add a C domain cross-reference.h]h)}(hrVariables aren't automatically cross referenced. For those, you need to explicitly add a C domain cross-reference.h]htVariables aren’t automatically cross referenced. For those, you need to explicitly add a C domain cross-reference.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1hhj hhhhhNubeh}(h]'cross-referencing-from-restructuredtextah ]h"]'cross-referencing from restructuredtextah$]h&]uh1hhj hhhhhMubeh}(h]highlights-and-cross-referencesah ]h"]highlights and cross-referencesah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hOverview documentation commentsh]hOverview documentation comments}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXMTo facilitate having source code and comments close together, you can include kernel-doc documentation blocks that are free-form comments instead of being kernel-doc for functions, structures, unions, enums, typedefs or variables. This could be used for something like a theory of operation for a driver or library code, for example.h]hXMTo facilitate having source code and comments close together, you can include kernel-doc documentation blocks that are free-form comments instead of being kernel-doc for functions, structures, unions, enums, typedefs or variables. This could be used for something like a theory of operation for a driver or library code, for example.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hFThis is done by using a ``DOC:`` section keyword with a section title.h](hThis is done by using a }(hjhhhNhNubjL)}(h``DOC:``h]hDOC:}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh& section keyword with a section title.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hJThe general format of an overview or high-level documentation comment is::h]hIThe general format of an overview or high-level documentation comment is:}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj-)}(hX7/** * DOC: Theory of Operation * * The whizbang foobar is a dilly of a gizmo. It can do whatever you * want it to do, at any time. It reads your mind. Here's how it works. * * foo bar splat * * The only drawback to this gizmo is that is can sometimes damage * hardware, software, or its subject(s). */h]hX7/** * DOC: Theory of Operation * * The whizbang foobar is a dilly of a gizmo. It can do whatever you * want it to do, at any time. It reads your mind. Here's how it works. * * foo bar splat * * The only drawback to this gizmo is that is can sometimes damage * hardware, software, or its subject(s). */}hjKsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMhj hhubh)}(hThe title following ``DOC:`` acts as a heading within the source file, but also as an identifier for extracting the documentation comment. Thus, the title must be unique within the file.h](hThe title following }(hjYhhhNhNubjL)}(h``DOC:``h]hDOC:}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjYubh acts as a heading within the source file, but also as an identifier for extracting the documentation comment. Thus, the title must be unique within the file.}(hjYhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]overview-documentation-commentsah ]h"]overview documentation commentsah$]h&]uh1hhhhhhhhMubeh}(h]writing-kernel-doc-commentsah ]h"]writing kernel-doc commentsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hIncluding kernel-doc commentsh]hIncluding kernel-doc comments}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM ubh)}(hThe documentation comments may be included in any of the reStructuredText documents using a dedicated kernel-doc Sphinx directive extension.h]hThe documentation comments may be included in any of the reStructuredText documents using a dedicated kernel-doc Sphinx directive extension.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(h+The kernel-doc directive is of the format::h]h*The kernel-doc directive is of the format:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj-)}(h".. kernel-doc:: source :option:h]h".. kernel-doc:: source :option:}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMhjhhubh)}(h}The *source* is the path to a source file, relative to the kernel source tree. The following directive options are supported:h](hThe }(hjhhhNhNubj6)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubhq is the path to a source file, relative to the kernel source tree. The following directive options are supported:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj )}(hhh](j# )}(hXexport: *[source-pattern ...]* Include documentation for all functions in *source* that have been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any of the files specified by *source-pattern*. The *source-pattern* is useful when the kernel-doc comments have been placed in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to the function definitions. Examples:: .. kernel-doc:: lib/bitmap.c :export: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c h](j) )}(hexport: *[source-pattern ...]*h](hexport: }(hjhhhNhNubj6)}(h*[source-pattern ...]*h]h[source-pattern ...]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubeh}(h]h ]h"]h$]h&]uh1j( hhhM&hjubjB )}(hhh](h)}(hInclude documentation for all functions in *source* that have been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any of the files specified by *source-pattern*.h](h+Include documentation for all functions in }(hj hhhNhNubj6)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj ubh that have been exported using }(hj hhhNhNubjL)}(h[P``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh or }(hj hhhNhNubjL)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj ubh either in }(hj hhhNhNubj6)}(h*source*h]hsource}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj ubh% or in any of the files specified by }(hj hhhNhNubj6)}(h*source-pattern*h]hsource-pattern}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(hThe *source-pattern* is useful when the kernel-doc comments have been placed in header files, while ``EXPORT_SYMBOL`` and ``EXPORT_SYMBOL_GPL`` are next to the function definitions.h](hThe }(hjrhhhNhNubj6)}(h*source-pattern*h]hsource-pattern}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjrubhP is useful when the kernel-doc comments have been placed in header files, while }(hjrhhhNhNubjL)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjrubh and }(hjrhhhNhNubjL)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjrubh& are next to the function definitions.}(hjrhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(h Examples::h]h Examples:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjubj-)}(hm.. kernel-doc:: lib/bitmap.c :export: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.ch]hm.. kernel-doc:: lib/bitmap.c :export: .. kernel-doc:: include/net/mac80211.h :export: net/mac80211/*.c}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhM"hjubeh}(h]h ]h"]h$]h&]uh1jA hjubeh}(h]h ]h"]h$]h&]uh1j" hhhM&hjubj# )}(hXJinternal: *[source-pattern ...]* Include documentation for all functions and types in *source* that have **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any of the files specified by *source-pattern*. Example:: .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal: h](j) )}(h internal: *[source-pattern ...]*h](h internal: }(hjhhhNhNubj6)}(h*[source-pattern ...]*h]h[source-pattern ...]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubeh}(h]h ]h"]h$]h&]uh1j( hhhM0hjubjB )}(hhh](h)}(hInclude documentation for all functions and types in *source* that have **not** been exported using ``EXPORT_SYMBOL`` or ``EXPORT_SYMBOL_GPL`` either in *source* or in any of the files specified by *source-pattern*.h](h5Include documentation for all functions and types in }(hjhhhNhNubj6)}(h*source*h]hsource}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh that have }(hjhhhNhNubj )}(h**not**h]hnot}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j hjubh been exported using }(hjhhhNhNubjL)}(h``EXPORT_SYMBOL``h]h EXPORT_SYMBOL}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh or }(hjhhhNhNubjL)}(h``EXPORT_SYMBOL_GPL``h]hEXPORT_SYMBOL_GPL}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh either in }(hjhhhNhNubj6)}(h*source*h]hsource}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh% or in any of the files specified by }(hjhhhNhNubj6)}(h*source-pattern*h]hsource-pattern}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM)hjubh)}(h Example::h]hExample:}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hjubj-)}(h@.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal:h]h@.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal:}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhM/hjubeh}(h]h ]h"]h$]h&]uh1jA hjubeh}(h]h ]h"]h$]h&]uh1j" hhhM0hjhhubj# )}(hXidentifiers: *[ function/type ...]* Include documentation for each *function* and *type* in *source*. If no *function* is specified, the documentation for all functions and types in the *source* will be included. *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var`` identifier. Examples:: .. kernel-doc:: lib/bitmap.c :identifiers: bitmap_parselist bitmap_parselist_user .. kernel-doc:: lib/idr.c :identifiers: h](j) )}(h#identifiers: *[ function/type ...]*h](h identifiers: }(hjhhhNhNubj6)}(h*[ function/type ...]*h]h[ function/type ...]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubeh}(h]h ]h"]h$]h&]uh1j( hhhM?hjubjB )}(hhh](h)}(hXInclude documentation for each *function* and *type* in *source*. If no *function* is specified, the documentation for all functions and types in the *source* will be included. *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var`` identifier.h](hInclude documentation for each }(hjhhhNhNubj6)}(h *function*h]hfunction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh and }(hjhhhNhNubj6)}(h*type*h]htype}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh in }(hjhhhNhNubj6)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh. If no }(hjhhhNhNubj6)}(h *function*h]hfunction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubhD is specified, the documentation for all functions and types in the }(hjhhhNhNubj6)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh will be included. }(hjhhhNhNubj6)}(h*type*h]htype}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh can be a }(hjhhhNhNubjL)}(h ``struct``h]hstruct}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh, }(hjhhhNhNubjL)}(h ``union``h]hunion}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh, }hjsbjL)}(h``enum``h]henum}(hj^hhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh, }hjsbjL)}(h ``typedef``h]htypedef}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh or }(hjhhhNhNubjL)}(h``var``h]hvar}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh identifier.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM3hjubh)}(h Examples::h]h Examples:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM9hjubj-)}(h.. kernel-doc:: lib/bitmap.c :identifiers: bitmap_parselist bitmap_parselist_user .. kernel-doc:: lib/idr.c :identifiers:h]h.. kernel-doc:: lib/bitmap.c :identifiers: bitmap_parselist bitmap_parselist_user .. kernel-doc:: lib/idr.c :identifiers:}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhM;hjubeh}(h]h ]h"]h$]h&]uh1jA hjubeh}(h]h ]h"]h$]h&]uh1j" hhhM?hjhhubj# )}(hno-identifiers: *[ function/type ...]* Exclude documentation for each *function* and *type* in *source*. Example:: .. kernel-doc:: lib/bitmap.c :no-identifiers: bitmap_parselist h](j) )}(h&no-identifiers: *[ function/type ...]*h](hno-identifiers: }(hjhhhNhNubj6)}(h*[ function/type ...]*h]h[ function/type ...]}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubeh}(h]h ]h"]h$]h&]uh1j( hhhMGhjubjB )}(hhh](h)}(hAExclude documentation for each *function* and *type* in *source*.h](hExclude documentation for each }(hjhhhNhNubj6)}(h *function*h]hfunction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh and }(hjhhhNhNubj6)}(h*type*h]htype}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh in }(hjhhhNhNubj6)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMBhjubh)}(h Example::h]hExample:}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMDhjubj-)}(hA.. kernel-doc:: lib/bitmap.c :no-identifiers: bitmap_parselisth]hA.. kernel-doc:: lib/bitmap.c :no-identifiers: bitmap_parselist}hj7sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMFhjubeh}(h]h ]h"]h$]h&]uh1jA hjubeh}(h]h ]h"]h$]h&]uh1j" hhhMGhjhhubj# )}(hbfunctions: *[ function/type ...]* This is an alias of the 'identifiers' directive and deprecated. h](j) )}(h!functions: *[ function/type ...]*h](h functions: }(hjUhhhNhNubj6)}(h*[ function/type ...]*h]h[ function/type ...]}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjUubeh}(h]h ]h"]h$]h&]uh1j( hhhMJhjQubjB )}(hhh]h)}(h?This is an alias of the 'identifiers' directive and deprecated.h]hCThis is an alias of the ‘identifiers’ directive and deprecated.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjqubah}(h]h ]h"]h$]h&]uh1jA hjQubeh}(h]h ]h"]h$]h&]uh1j" hhhMJhjhhubj# )}(hXdoc: *title* Include documentation for the ``DOC:`` paragraph identified by *title* in *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* is only used as an identifier for the paragraph, and is not included in the output. Please make sure to have an appropriate heading in the enclosing reStructuredText document. Example:: .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port h](j) )}(h doc: *title*h](hdoc: }(hjhhhNhNubj6)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubeh}(h]h ]h"]h$]h&]uh1j( hhhMVhjubjB )}(hhh](h)}(hXHInclude documentation for the ``DOC:`` paragraph identified by *title* in *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* is only used as an identifier for the paragraph, and is not included in the output. Please make sure to have an appropriate heading in the enclosing reStructuredText document.h](hInclude documentation for the }(hjhhhNhNubjL)}(h``DOC:``h]hDOC:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh paragraph identified by }(hjhhhNhNubj6)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh in }(hjhhhNhNubj6)}(h*source*h]hsource}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh. Spaces are allowed in }(hjhhhNhNubj6)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh; do not quote the }(hjhhhNhNubj6)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh. The }(hjhhhNhNubj6)}(h*title*h]htitle}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j5hjubh is only used as an identifier for the paragraph, and is not included in the output. Please make sure to have an appropriate heading in the enclosing reStructuredText document.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMMhjubh)}(h Example::h]hExample:}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMShjubj-)}(hl.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Porth]hl.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port}hj9sbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMUhjubeh}(h]h ]h"]h$]h&]uh1jA hjubeh}(h]h ]h"]h$]h&]uh1j" hhhMVhjhhubeh}(h]h ]h"]h$]h&]uh1j hjhhhhhNubh)}(hcWithout options, the kernel-doc directive includes all documentation comments from the source file.h]hcWithout options, the kernel-doc directive includes all documentation comments from the source file.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMXhjhhubh)}(hThe kernel-doc extension is included in the kernel source tree, at ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the ``tools/docs/kernel-doc`` script to extract the documentation comments from the source.h](hCThe kernel-doc extension is included in the kernel source tree, at }(hjghhhNhNubjL)}(h%``Documentation/sphinx/kerneldoc.py``h]h!Documentation/sphinx/kerneldoc.py}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjgubh. Internally, it uses the }(hjghhhNhNubjL)}(h``tools/docs/kernel-doc``h]htools/docs/kernel-doc}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjgubh> script to extract the documentation comments from the source.}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM[hjhhubj5)}(h.. _kernel_doc:h]h}(h]h ]h"]h$]h&]refid kernel-docuh1j4hM`hjhhhhubh)}(hhh](h)}(h+How to use kernel-doc to generate man pagesh]h+How to use kernel-doc to generate man pages}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMcubh)}(hJTo generate man pages for all files that contain kernel-doc markups, run::h]hITo generate man pages for all files that contain kernel-doc markups, run:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMehjhhubj-)}(h$ make mandocsh]h$ make mandocs}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMghjhhubh)}(h.Or calling ``script-build-wrapper`` directly::h](h Or calling }(hjhhhNhNubjL)}(h``script-build-wrapper``h]hscript-build-wrapper}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh directly:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMihjhhubj-)}(h+$ ./tools/docs/sphinx-build-wrapper mandocsh]h+$ ./tools/docs/sphinx-build-wrapper mandocs}hjsbah}(h]h ]h"]h$]h&]j<j=uh1j,hhhMkhjhhubh)}(hlThe output will be at ``/man`` directory inside the output directory (by default: ``Documentation/output``).h](hThe output will be at }(hjhhhNhNubjL)}(h``/man``h]h/man}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh4 directory inside the output directory (by default: }(hjhhhNhNubjL)}(h``Documentation/output``h]hDocumentation/output}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMmhjhhubh)}(hVOptionally, it is possible to generate a partial set of man pages by using SPHINXDIRS:h]hVOptionally, it is possible to generate a partial set of man pages by using SPHINXDIRS:}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphjhhubh block_quote)}(h+$ make SPHINXDIRS=driver-api/media mandocs h]h)}(h*$ make SPHINXDIRS=driver-api/media mandocsh]h*$ make SPHINXDIRS=driver-api/media mandocs}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMshjBubah}(h]h ]h"]h$]h&]uh1j@hhhMshjhhubh)}(hWhen SPHINXDIRS={subdir} is used, it will only generate man pages for the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file.h]h)}(hWhen SPHINXDIRS={subdir} is used, it will only generate man pages for the files explicitly inside a ``Documentation/{subdir}/.../*.rst`` file.h](hdWhen SPHINXDIRS={subdir} is used, it will only generate man pages for the files explicitly inside a }(hj^hhhNhNubjL)}(h$``Documentation/{subdir}/.../*.rst``h]h Documentation/{subdir}/.../*.rst}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1jKhj^ubh file.}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMwhjZubah}(h]h ]h"]h$]h&]uh1hhjhhhhhNubeh}(h](+how-to-use-kernel-doc-to-generate-man-pagesjeh ]h"](+how to use kernel-doc to generate man pages kernel_doceh$]h&]uh1hhjhhhhhMcexpect_referenced_by_name}jjsexpect_referenced_by_id}jjsubeh}(h]including-kernel-doc-commentsah ]h"]including kernel-doc commentsah$]h&]uh1hhhhhhhhM ubeh}(h]h ]h"]h$]h&]sourcehhKernel-doc commentsuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}sphinx c domain](jj j esrefids}j]jasnameids}(jjj?j<jjjjjjjjjjjtjqjjjjjljijjj j j j j j j j j~j{jjjjjju nametypes}(jj?jjjjjjtjjjljj j j j j~jjjuh}(jhj<j6jjjjjjjjjjjqjjjjjjijjjwj jj j j j j j j{j jjjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h0Hyperlink target "kernel-doc" is not referenced.}hj)sbah}(h]h ]h"]h$]h&]uh1hhj&ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehʌlineM`uh1j$uba transformerN include_log] decorationNhhub.