Skip to contentSkip to conversation

Add support for in-line nested struct comments

PATCH In review Mauro Carvalho Chehab 5 participants 13 messages Feb 16, 2018 – Feb 19, 2018

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover Add support for in-line nested struct comments

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(-)
Signature · 7 lines
2.14.3


_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#9 lore raw

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

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.

---
 drivers/gpu/drm/i915/intel_dpio_phy.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/i915/intel_dpio_phy.c +1 -1
index 76473e9836c6..c8e9e44e5981 100644
@@ -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];
Signature · 6 lines
2.14.3

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#2 lore raw

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

In reply to Mauro Carvalho Chehab

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

---
 Documentation/doc-guide/kernel-doc.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/doc-guide/kernel-doc.rst +1 -1
index 9fce378dccb2..3c00ce0c84e5 100644
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~
Signature · 1 line
2.14.3
#1 lore raw

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

In reply to 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.

---
 Documentation/doc-guide/kernel-doc.rst | 4 ++++
 1 file changed, 4 insertions(+)
Documentation/doc-guide/kernel-doc.rst +4 -0
index 2fb7f2bfc245..9fce378dccb2 100644
@@ -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 {
Signature · 1 line
2.14.3
#8 lore raw

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

In reply to 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.

---
 Documentation/doc-guide/kernel-doc.rst | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)
Documentation/doc-guide/kernel-doc.rst +11 -2
index 1ddfe35c0e78..c6c329708d8a 100644
@@ -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
Signature · 1 line
2.14.3
#3 lore raw

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

In reply to 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.

---
 Documentation/doc-guide/kernel-doc.rst | 56 +++++++++++++++++-----------------
 1 file changed, 28 insertions(+), 28 deletions(-)
Documentation/doc-guide/kernel-doc.rst +28 -28
index 3c00ce0c84e5..1ddfe35c0e78 100644
@@ -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
 ---------------------
 
Signature · 1 line
2.14.3
#4 lore raw

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

In reply to Mauro Carvalho Chehab

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

---
 scripts/kernel-doc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/kernel-doc +1 -1
index fee8952037b1..06d7f3f2c094 100755
@@ -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*;';
Signature · 1 line
2.14.3
#5 lore raw

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

Quoted 17 lines

Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab <[email protected]>:

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

---
scripts/kernel-doc | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index fee8952037b1..06d7f3f2c094 100755

scripts/kernel-doc my $doc_sect = $doc_com . · line 366

Quoted 5 lines
scripts/kernel-doc +1 -1
@@ -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 --

#6 lore raw

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

Em Fri, 16 Feb 2018 15:52:33 +0100
Markus Heiser <[email protected]> escreveu:

Quoted 24 lines
Quoted 16 lines

Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab <[email protected]>:

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

---
scripts/kernel-doc | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index fee8952037b1..06d7f3f2c094 100755

scripts/kernel-doc my $doc_sect = $doc_com . · line 366

Quoted 5 lines
scripts/kernel-doc +1 -1
@@ -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!

Quoted 7 lines

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

#7 lore raw

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

Quoted 38 lines

Am 16.02.2018 um 15:56 schrieb Mauro Carvalho Chehab <[email protected]>:

Em Fri, 16 Feb 2018 15:52:33 +0100
Markus Heiser <[email protected]> escreveu:

Quoted 24 lines
Quoted 16 lines

Am 16.02.2018 um 14:48 schrieb Mauro Carvalho Chehab <[email protected]>:

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

---
scripts/kernel-doc | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index fee8952037b1..06d7f3f2c094 100755

scripts/kernel-doc my $doc_sect = $doc_com . · line 366

Quoted 5 lines
scripts/kernel-doc +1 -1
@@ -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!

Quoted 7 lines

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

Quoted 7 lines

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 --

maintainer
#10 lore raw
In reply to Mauro Carvalho Chehab
Quoted 5 lines · On Fri, 16 Feb 2018 11:48:14 -0200 Mauro Carvalho Chehab…

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
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#11 lore raw
Quoted 11 lines · Jonathan Corbet
Quoted 5 lines · On Fri, 16 Feb 2018 11:48:14 -0200 Mauro Carvalho Chehab…

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.

Signature · 5 lines
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#12 lore raw
In reply to Mauro Carvalho Chehab
Quoted 6 lines · 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.

Quoted 7 lines

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

Quoted 14 lines
 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(-)
Signature · 7 lines
2.14.3


_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Signature · 7 lines
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx