summaryrefslogtreecommitdiffstats
path: root/Documentation/doc-guide
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2017-12-18 10:30:02 -0200
committerJonathan Corbet <corbet@lwn.net>2017-12-21 13:41:45 -0700
commit63ac85174a5455bf0ed14fa37515015de33d0fe9 (patch)
treecaeaf3c3a78f5cf51d29b2de2072949831684530 /Documentation/doc-guide
parent012e93cbdb28329e615b937bb2bb7d61aee5d0d1 (diff)
downloadlinux-63ac85174a5455bf0ed14fa37515015de33d0fe9.tar.bz2
docs: kernel-doc.rst: better describe kernel-doc arguments
Add a new section to describe kernel-doc arguments, adding examples about how identation should happen, as failing to do that causes Sphinx to do the wrong thing. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/doc-guide')
-rw-r--r--Documentation/doc-guide/kernel-doc.rst44
1 files changed, 41 insertions, 3 deletions
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 0268335414ce..f1c03c16f03b 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -112,16 +112,17 @@ Example kernel-doc function comment::
/**
* foobar() - Brief description of foobar.
- * @arg: Description of argument of foobar.
+ * @argument1: Description of parameter argument1 of foobar.
+ * @argument2: Description of parameter argument2 of foobar.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
- int foobar(int arg)
+ int foobar(int argument1, char *argument2)
The format is similar for documentation for structures, enums, paragraphs,
-etc. See the sections below for details.
+etc. See the sections below for specific details of each type.
The kernel-doc structure is extracted from the comments, and proper `Sphinx C
Domain`_ function and type descriptions with anchors are generated for them. The
@@ -130,6 +131,43 @@ cross-references. See below for details.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
+
+Parameters and member arguments
+-------------------------------
+
+The kernel-doc function comments describe each parameter to the function and
+function typedefs or each member of struct/union, in order, with the
+``@argument:`` descriptions. For each non-private member argument, one
+``@argument`` definition is needed.
+
+The ``@argument:`` descriptions begin on the very next line following
+the opening brief function description line, with no intervening blank
+comment lines.
+
+The ``@argument:`` descriptions may span multiple lines.
+
+.. note::
+
+ If the ``@argument`` description has multiple lines, the continuation
+ of the description should be starting exactly at the same column as
+ the previous line, e. g.::
+
+ * @argument: some long description
+ * that continues on next lines
+
+ or::
+
+ * @argument:
+ * some long description
+ * that continues on next lines
+
+If a function or typedef parameter argument is ``...`` (e. g. a variable
+number of arguments), its description should be listed in kernel-doc
+notation as::
+
+ * @...: description
+
+
Highlights and cross-references
-------------------------------