Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1740087 > unrolled thread

[PATCH 00/10] kernel-doc: add supported to document nested structs/unions

Back to article view | Back to linux.kernel

Contents

  [PATCH 00/10] kernel-doc: add supported to document nested structs/unions Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-09-26 20:10 +0200
    [PATCH 02/10] docs: kernel-doc.rst: better describe kernel-doc arguments Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-09-26 20:10 +0200
      Re: [PATCH 02/10] docs: kernel-doc.rst: better describe kernel-doc  arguments Randy Dunlap <rdunlap@infradead.org> - 2017-09-27 04:10 +0200
    Re: [PATCH 01/10] scripts: kernel-doc: get rid of unused output  formats Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-09-27 22:50 +0200

#1740087 — [PATCH 00/10] kernel-doc: add supported to document nested structs/unions

Right now, it is not possible to document nested struct and nested unions.
kernel-doc simply ignore them.

Add support to document them.

This series starts with a patch getting rid of the now unused output formats
for kernel-doc: since we got rid of all DocBook stuff, we should not need
them anymore. The reason for dropping it (despite cleaning up), is that
it doesn't make sense to invest time on adding new features for formats
that aren't used anymore.

The next 8 patches on this series improve kernel-doc documentation and
finally get rid of its old documentation (kernel-doc-nano-HOWTO.txt).

Patch 9/10 is the most interesting one in this series: it adds support for
nested structures and unions.

Patch 10/10 is just an example from a random header with kernel-doc
markups. There's no special reason for selecting this file, and the
comments there are likely wrong. So, please use it only as a way to test
the new parser logic from patch 9/10.

Mauro Carvalho Chehab (10):
  scripts: kernel-doc: get rid of unused output formats
  docs: kernel-doc.rst: better describe kernel-doc arguments
  docs: kernel-doc.rst: improve private members description
  docs: kernel-doc.rst: improve function documentation section
  docs: kernel-doc.rst: improve structs chapter
  docs: kernel-doc: improve typedef documentation
  docs: kernel-doc.rst: add documentation about man pages
  docs: get rid of kernel-doc-nano-HOWTO.txt
  scripts: kernel-doc: parse next structs/unions
  [RFC] w1_netlink.h: add support for nested structs

---

Before this series, I send a few PoC patches. They were all
replaced by patch 9/10.

 Documentation/00-INDEX                  |    2 -
 Documentation/doc-guide/kernel-doc.rst  |  387 ++++++---
 Documentation/kernel-doc-nano-HOWTO.txt |  322 --------
 drivers/w1/w1_netlink.h                 |    4 +
 scripts/kernel-doc                      | 1304 ++-----------------------------
 5 files changed, 346 insertions(+), 1673 deletions(-)
 delete mode 100644 Documentation/kernel-doc-nano-HOWTO.txt

-- 
2.13.5

[toc] | [next] | [standalone]

#1740091 — [PATCH 02/10] 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>
---
 Documentation/doc-guide/kernel-doc.rst | 44 +++++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index b24854b5d6be..7a3f5c710c0b 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.
+   * @argument1: 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
 -------------------------------
 
-- 
2.13.5

[toc] | [prev] | [next] | [standalone]

#1740349 — Re: [PATCH 02/10] docs: kernel-doc.rst: better describe kernel-doc arguments

On 09/26/17 10:59, Mauro Carvalho Chehab wrote:
> 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>
> ---
>  Documentation/doc-guide/kernel-doc.rst | 44 +++++++++++++++++++++++++++++++---
>  1 file changed, 41 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
> index b24854b5d6be..7a3f5c710c0b 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.
> +   * @argument1: Description of parameter argument2 of foobar.

        @argument2:

>     *
>     * Longer description of foobar.
>     *
>     * Return: Description of return value of foobar.
>     */
> -  int foobar(int arg)
> +  int foobar(int argument1, char *argument2)


-- 
~Randy

[toc] | [prev] | [next] | [standalone]

#1741016 — Re: [PATCH 01/10] scripts: kernel-doc: get rid of unused output formats

Em Wed, 27 Sep 2017 17:36:59 +0300
Jani Nikula <jani.nikula@linux.intel.com> escreveu:

> On Tue, 26 Sep 2017, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> > Since there isn't any docbook code anymore upstream,
> > we can get rid of several output formats:
> >
> > - docbook/xml, html, html5 and list formats were used by
> >   the old build system;
> > - As ReST is text, there's not much sense on outputting
> >   on a different text format.
> >
> > After this patch, only man and rst output formats are
> > supported.  
> 
> FWIW,
> 
> Acked-by: Jani Nikula <jani.nikula@intel.com>

Thanks!

> Please do keep at least two output formats going forward. Otherwise the
> mechanisms of having more than one output format will bitrot and get
> conflated into the one output format.

Yeah, if we leave just one output format, some extra cleanup would be
needed.

Anyway, as we currently doesn't have other ways to generate manpages,
we should be keeping both ReST and man for now.

Thanks,
Mauro

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web