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
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 <[email protected]>
---
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
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(-)
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
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 <[email protected]>
Tested-by: Jani Nikula <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
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 <[email protected]>
---
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
Em Fri, 16 Feb 2018 15:52:33 +0100
Markus Heiser <[email protected]> escreveu:
> > 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(-)
> >
> > 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
> 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(-)
>
> 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 --
> 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:
>
>>> 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(-)
>>>
>>> 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 --
On Fri, 16 Feb 2018 11:48:14 -0200
Mauro Carvalho Chehab <[email protected]> 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
On Sun, 18 Feb 2018, Jonathan Corbet <[email protected]> wrote:
> On Fri, 16 Feb 2018 11:48:14 -0200
> Mauro Carvalho Chehab <[email protected]> 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
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
> [email protected]
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch