[PATCH 0/6] Add support for in-line nested struct comments

[PATCH 0/6] Add support for in-line nested struct comments

[Mauro Carvalho Chehab]

This series fix two bugs at kernel-doc.rst examples and add support
for in-line nested struct comments.

It also converts one documentation at intel_dpio_phy to use it,
in order to give a practical example about how to use it.

Mauro Carvalho Chehab (6):
  doc-guide: kernel-doc: fix example for nested_foobar struct
  doc-guide: kernel-doc: fix example for inlined comments
  doc-guide: kernel-doc: move in-line section to be after nested struct
  scripts: kernel-doc: support in-line comments on nested structs/unions
  doc-guide: kernel-doc: add examples about nested union/structs
  drm: intel_dpio_phy: fix kernel-doc comments at nested struct

 Documentation/doc-guide/kernel-doc.rst | 69 ++++++++++++++++++++--------------
 drivers/gpu/drm/i915/intel_dpio_phy.c  |  2 +-
 scripts/kernel-doc                     |  2 +-
 3 files changed, 43 insertions(+), 30 deletions(-)

-- 
2.14.3

[PATCH 1/6] doc-guide: kernel-doc: fix example for nested_foobar struct

[Mauro Carvalho Chehab]

There's a missing */ at the end of Kernel docs example.
Even adding it, it will still produce 3 warnings:

	example:33: warning: Function parameter or member 'bar' not described in 'nested_foobar'
	example:33: warning: Function parameter or member 'bar.st1' not described in 'nested_foobar'
	example:33: warning: Function parameter or member 'bar.st2' not described in 'nested_foobar'

So, make the example more complete and add the missing end
of comment there.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 2fb7f2bfc245..9fce378dccb2 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -250,10 +250,14 @@ It is possible to document nested structs and unions, like::
        * @memb2: second member of anonymous union/anonymous struct
        * @memb3: third member of anonymous union/anonymous struct
        * @memb4: fourth member of anonymous union/anonymous struct
+       * @bar: non-anonymous union
+       * @bar.st1: struct st1 inside @bar
+       * @bar.st2: struct st2 inside @bar
        * @bar.st1.memb1: first member of struct st1 on union bar
        * @bar.st1.memb2: second member of struct st1 on union bar
        * @bar.st2.memb1: first member of struct st2 on union bar
        * @bar.st2.memb2: second member of struct st2 on union bar
+       */
       struct nested_foobar {
         /* Anonymous union/struct*/
         union {
-- 
2.14.3

[PATCH 2/6] doc-guide: kernel-doc: fix example for inlined comments

[Mauro Carvalho Chehab]

Without ending with a ";", kernel-doc doesn't recognize it
as an struct, and it fails to parse the example.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 9fce378dccb2..3c00ce0c84e5 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -237,7 +237,7 @@ on a line of their own, like all other kernel-doc comments::
         int baz;
         /** @foobar: Single line description. */
         int foobar;
-  }
+  };
 
 Nested structs/unions
 ~~~~~~~~~~~~~~~~~~~~~
-- 
2.14.3

[PATCH 3/6] doc-guide: kernel-doc: move in-line section to be after nested struct

[Mauro Carvalho Chehab]

We want to give some examples about how to do in-line comments
for nested structs. So, move it to be after nested structs/unions
chapter.

The section content was not changed on this patch.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 56 +++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 28 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 3c00ce0c84e5..1ddfe35c0e78 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -211,34 +211,6 @@ Example::
       int d;
   };
 
-In-line member documentation comments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The structure members may also be documented in-line within the definition.
-There are two styles, single-line comments where both the opening ``/**`` and
-closing ``*/`` are on the same line, and multi-line comments where they are each
-on a line of their own, like all other kernel-doc comments::
-
-  /**
-   * struct foo - Brief description.
-   * @foo: The Foo member.
-   */
-  struct foo {
-        int foo;
-        /**
-         * @bar: The Bar member.
-         */
-        int bar;
-        /**
-         * @baz: The Baz member.
-         *
-         * Here, the member description may contain several paragraphs.
-         */
-        int baz;
-        /** @foobar: Single line description. */
-        int foobar;
-  };
-
 Nested structs/unions
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -290,6 +262,34 @@ It is possible to document nested structs and unions, like::
    #) When the nested struct/union is anonymous, the member ``bar`` in it
       should be documented as ``@bar:``
 
+In-line member documentation comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The structure members may also be documented in-line within the definition.
+There are two styles, single-line comments where both the opening ``/**`` and
+closing ``*/`` are on the same line, and multi-line comments where they are each
+on a line of their own, like all other kernel-doc comments::
+
+  /**
+   * struct foo - Brief description.
+   * @foo: The Foo member.
+   */
+  struct foo {
+        int foo;
+        /**
+         * @bar: The Bar member.
+         */
+        int bar;
+        /**
+         * @baz: The Baz member.
+         *
+         * Here, the member description may contain several paragraphs.
+         */
+        int baz;
+        /** @foobar: Single line description. */
+        int foobar;
+  };
+
 Typedef documentation
 ---------------------
 
-- 
2.14.3

[PATCH 4/6] scripts: kernel-doc: support in-line comments on nested structs/unions

[Mauro Carvalho Chehab]

The parser at kernel-doc rejects names with dots in the middle.
Fix it, in order to support nested structs/unions.

Tested-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index fee8952037b1..06d7f3f2c094 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
-my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
+my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
-- 
2.14.3

Re: [PATCH 4/6] scripts: kernel-doc: support in-line comments on nested structs/unions

[Markus Heiser]

> Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> The parser at kernel-doc rejects names with dots in the middle.
> Fix it, in order to support nested structs/unions.
> 
> Tested-by: Jani Nikula <jani.nikula@intel.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> scripts/kernel-doc | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index fee8952037b1..06d7f3f2c094 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> my $doc_content = $doc_com_body . '(.*)';
> my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> my $doc_inline_start = '^\s*/\*\*\s*$';
> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';

Thanks!

FWIW: added similar patch to python variant of kernel-doc:

https://github.com/return42/linuxdoc/commit/5c5da9a

rendered example:

  https://return42.github.io/linuxdoc/linuxdoc-howto/all-in-a-tumble.html#struct-my-long-struct

-- Markus --

Re: [PATCH 4/6] scripts: kernel-doc: support in-line comments on nested structs/unions

[Mauro Carvalho Chehab]

Em Fri, 16 Feb 2018 15:52:33 +0100
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> > Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> > 
> > The parser at kernel-doc rejects names with dots in the middle.
> > Fix it, in order to support nested structs/unions.
> > 
> > Tested-by: Jani Nikula <jani.nikula@intel.com>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> > scripts/kernel-doc | 2 +-
> > 1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index fee8952037b1..06d7f3f2c094 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
> > my $doc_content = $doc_com_body . '(.*)';
> > my $doc_block = $doc_com . 'DOC:\s*(.*)?';
> > my $doc_inline_start = '^\s*/\*\*\s*$';
> > -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
> > +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';  
> 
> Thanks!
> 
> FWIW: added similar patch to python variant of kernel-doc:
> 
> https://github.com/return42/linuxdoc/commit/5c5da9a
> 
> rendered example:
> 
>   https://return42.github.io/linuxdoc/linuxdoc-howto/all-in-a-tumble.html#struct-my-long-struct

On a quick look, on your example, bar2.barbar description looks different
than what we get from the perl version.

There, it generates it as:

``bar2.barbar``
  Description for **barbar** inside **foo.bar2**

Regards,
Mauro

Re: [PATCH 4/6] scripts: kernel-doc: support in-line comments on nested structs/unions

[Markus Heiser]

> Am 16.02.2018 um 15:56 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> Em Fri, 16 Feb 2018 15:52:33 +0100
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
>>> Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
>>> 
>>> The parser at kernel-doc rejects names with dots in the middle.
>>> Fix it, in order to support nested structs/unions.
>>> 
>>> Tested-by: Jani Nikula <jani.nikula@intel.com>
>>> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>>> ---
>>> scripts/kernel-doc | 2 +-
>>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>> 
>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>>> index fee8952037b1..06d7f3f2c094 100755
>>> --- a/scripts/kernel-doc
>>> +++ b/scripts/kernel-doc
>>> @@ -363,7 +363,7 @@ my $doc_sect = $doc_com .
>>> my $doc_content = $doc_com_body . '(.*)';
>>> my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>>> my $doc_inline_start = '^\s*/\*\*\s*$';
>>> -my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
>>> +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';  
>> 
>> Thanks!
>> 
>> FWIW: added similar patch to python variant of kernel-doc:
>> 
>> https://github.com/return42/linuxdoc/commit/5c5da9a
>> 
>> rendered example:
>> 
>>  https://return42.github.io/linuxdoc/linuxdoc-howto/all-in-a-tumble.html#struct-my-long-struct
> 
> On a quick look, on your example, bar2.barbar description looks different
> than what we get from the perl version.
> 
> There, it generates it as:
> 
> ``bar2.barbar``
>  Description for **barbar** inside **foo.bar2**

very attentive, thanks a lot!

When I implemented support for nested data types, I missed
to fix the highlighting pattern of those.

  https://github.com/return42/linuxdoc/commit/4b43f419

rendered: https://return42.github.io/linuxdoc/linuxdoc-howto/all-in-a-tumble.html#struct-my-long-struct

-- Markus --

[PATCH 5/6] doc-guide: kernel-doc: add examples about nested union/structs

[Mauro Carvalho Chehab]

It helps to give some examples about how to use in-line
comments also when nested union/structs are present. So add it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/doc-guide/kernel-doc.rst | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 1ddfe35c0e78..c6c329708d8a 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -286,8 +286,17 @@ on a line of their own, like all other kernel-doc comments::
          * Here, the member description may contain several paragraphs.
          */
         int baz;
-        /** @foobar: Single line description. */
-        int foobar;
+        union {
+                /** @foobar: Single line description. */
+                int foobar;
+        };
+        /** @bar2: Description for struct @bar2 inside @foo */
+        struct {
+                /**
+                 * @bar2.barbar: Description for @barbar inside @foo.bar2
+                 */
+                int barbar;
+        } bar2;
   };
 
 Typedef documentation
-- 
2.14.3

[PATCH 6/6] drm: intel_dpio_phy: fix kernel-doc comments at nested struct

[Mauro Carvalho Chehab]

The in-lined comments for channel.port doesn't follow the syntax
described at kernel-doc document, causing the following warning:

	$ ./scripts/kernel-doc -none drivers/gpu/drm/i915/intel_dpio_phy.c
	drivers/gpu/drm/i915/intel_dpio_phy.c:154: warning: Function parameter or member 'channel.port' not described in 'bxt_ddi_phy_info'

While the best would be for the Kernel to deduce that from the
context, supporting it is not trivial. So, let's just stick with
the existing syntax.

Reported-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 drivers/gpu/drm/i915/intel_dpio_phy.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/i915/intel_dpio_phy.c b/drivers/gpu/drm/i915/intel_dpio_phy.c
index 76473e9836c6..c8e9e44e5981 100644
--- a/drivers/gpu/drm/i915/intel_dpio_phy.c
+++ b/drivers/gpu/drm/i915/intel_dpio_phy.c
@@ -147,7 +147,7 @@ struct bxt_ddi_phy_info {
 	 */
 	struct {
 		/**
-		 * @port: which port maps to this channel.
+		 * @channel.port: which port maps to this channel.
 		 */
 		enum port port;
 	} channel[2];
-- 
2.14.3

Re: [PATCH 0/6] Add support for in-line nested struct comments

[Jonathan Corbet]

On Fri, 16 Feb 2018 11:48:14 -0200
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> his series fix two bugs at kernel-doc.rst examples and add support
> for in-line nested struct comments.
> 
> It also converts one documentation at intel_dpio_phy to use it,
> in order to give a practical example about how to use it.

OK, I've applied everything but the last patch, which I assume will go
through the DRM tree.

Thanks,

jon

Re: [PATCH 0/6] Add support for in-line nested struct comments

[Jani Nikula]

On Sun, 18 Feb 2018, Jonathan Corbet <corbet@lwn.net> wrote:
> On Fri, 16 Feb 2018 11:48:14 -0200
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
>
>> his series fix two bugs at kernel-doc.rst examples and add support
>> for in-line nested struct comments.
>> 
>> It also converts one documentation at intel_dpio_phy to use it,
>> in order to give a practical example about how to use it.
>
> OK, I've applied everything but the last patch, which I assume will go
> through the DRM tree.

I was going to reference the kernel-doc commit while applying patch 6,
but I can't find the others. I guess applied literally meant just
applied, not pushed... ;)

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

Re: [Intel-gfx] [PATCH 0/6] Add support for in-line nested struct comments

[Daniel Vetter]

On Fri, Feb 16, 2018 at 11:48:14AM -0200, Mauro Carvalho Chehab wrote:
> This series fix two bugs at kernel-doc.rst examples and add support
> for in-line nested struct comments.
> 
> It also converts one documentation at intel_dpio_phy to use it,
> in order to give a practical example about how to use it.
> 
> Mauro Carvalho Chehab (6):
>   doc-guide: kernel-doc: fix example for nested_foobar struct
>   doc-guide: kernel-doc: fix example for inlined comments
>   doc-guide: kernel-doc: move in-line section to be after nested struct
>   scripts: kernel-doc: support in-line comments on nested structs/unions
>   doc-guide: kernel-doc: add examples about nested union/structs
>   drm: intel_dpio_phy: fix kernel-doc comments at nested struct

Oh, this is cool. Thanks a lot for doing this.
-Daniel

> 
>  Documentation/doc-guide/kernel-doc.rst | 69 ++++++++++++++++++++--------------
>  drivers/gpu/drm/i915/intel_dpio_phy.c  |  2 +-
>  scripts/kernel-doc                     |  2 +-
>  3 files changed, 43 insertions(+), 30 deletions(-)
> 
> -- 
> 2.14.3
> 
> 
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch