Add support for in-line nested struct comments
Subsystems (3)
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
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
@@ -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
PATCH 2/6 doc-guide: kernel-doc: fix example for inlined comments
In reply to Mauro Carvalho ChehabWithout 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
@@ -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
PATCH 1/6 doc-guide: kernel-doc: fix example for nested_foobar struct
In reply to Mauro Carvalho ChehabThere'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
@@ -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
PATCH 5/6 doc-guide: kernel-doc: add examples about nested union/structs
In reply to Mauro Carvalho ChehabIt 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
@@ -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
PATCH 3/6 doc-guide: kernel-doc: move in-line section to be after nested struct
In reply to Mauro Carvalho ChehabWe 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
@@ -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
PATCH 4/6 scripts: kernel-doc: support in-line comments on nested structs/unions
In reply to Mauro Carvalho ChehabThe 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
@@ -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
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.
Tested-by Jani Nikula <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>---
scripts/kernel-doc| 2 +-1 file changed, 1 insertion(+), 1 deletion(-)scripts/kernel-doc +0
-0
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 --
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.
Tested-by Jani Nikula <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>---
scripts/kernel-doc| 2 +-1 file changed, 1 insertion(+), 1 deletion(-)scripts/kernel-doc +0
-0scripts/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
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.
Tested-by Jani Nikula <[email protected]>Signed-off-by Mauro Carvalho Chehab <[email protected]>---
scripts/kernel-doc| 2 +-1 file changed, 1 insertion(+), 1 deletion(-)scripts/kernel-doc +0
-0scripts/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 --
Jonathan Corbet
maintainerQuoted 5 lines · On Fri, 16 Feb 2018 11:48:14 -0200 Mauro Carvalho Chehab…
his series fix two bugs at
kernel-doc.rstexamples and add support for in-line nested struct comments.It also converts one documentation at
intel_dpio_phyto 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
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.rstexamples and add support for in-line nested struct comments.It also converts one documentation at
intel_dpio_phyto 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
Quoted 6 lines · Mauro Carvalho Chehab
This series fix two bugs at
kernel-doc.rstexamples and add support for in-line nested struct comments.It also converts one documentation at
intel_dpio_phyto 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 fornested_foobarstruct
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