Sam, do you like the syntax? I hope properly indented rendering will
appear soon.
------------------------------------
[PATCH 5/6] kernel-doc: nested structs and unions support
Now something like this
struct a {
struct b_s {
union {
int c;
int g;
} u;
} b;
struct d_s {
int e;
} d;
};
is possible to document with the following kernel-doc comment:
/**
* struct a - ...
*
* @b: ...
* @b.u: ...
* @b.u.c: ...
* @b.u.g: ...
* @d: ...
* @d.e: ...
*/
Not-Yet-Signed-off-by: Alexey Dobriyan <[email protected]>
---
scripts/kernel-doc | 33 ++++++++++++++++++++++++++++-----
1 file changed, 28 insertions(+), 5 deletions(-)
--- linux-kernel-doc-004/scripts/kernel-doc 2005-05-09 02:34:59.000000000 +0000
+++ linux-kernel-doc-005/scripts/kernel-doc 2005-05-09 03:46:43.000000000 +0000
@@ -104,19 +104,26 @@ use strict;
# Beside functions you can also write documentation for structs, unions,
# enums and typedefs. Instead of the function name you must write the name
# of the declaration; the struct/union/enum/typedef must always precede
-# the name. Nesting of declarations is not supported.
+# the name.
# Use the argument mechanism to document members or constants.
# e.g.
# /**
# * struct my_struct - short description
# * @a: first member
# * @b: second member
+# * @c: nested struct
+# * @c.p: first member of nested struct
+# * @c.q: second member of nested struct
# *
# * Longer description
# */
# struct my_struct {
# int a;
# int b;
+# struct her_struct {
+# char **p;
+# short q;
+# } c;
# };
#
# All descriptions can be multiline, except the short function description.
@@ -156,7 +163,8 @@ my $warnings = 0;
# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
-my $type_param = '\@(\w+)';
+# "." is for nested structs/unions.
+my $type_param = '\@([\w.]+)';
my $type_struct = '\&((struct\s*)?[_\w]+)';
my $type_env = '(\$\w+)';
@@ -262,7 +270,8 @@ my $doc_start = '^/\*\*\s*$'; # Allow wh
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
my $doc_decl = $doc_com.'(\w+)';
-my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)';
+# "." is for nested structs/unions.
+my $doc_sect = $doc_com.'(['.$doc_special.']?[\w .]+):(.*)';
my $doc_content = $doc_com.'(.*)';
my $doc_block = $doc_com.'DOC:\s*(.*)?';
@@ -1292,8 +1301,22 @@ sub dump_struct($$) {
$declaration_name = $2;
my $members = $3;
- # ignore embedded structs or unions
- $members =~ s/{.*?}//g;
+ # Make nested structs/unions tree flat. Proceed from leaves to root.
+ # "." is needed when there is more than one level of nest.
+ while ($members =~ /{([^{]*?)}\s*([\w.]+)/) {
+ my $inner_members = $1;
+ my $struct_name = $2;
+
+ # Prefix members with the name of the struct/union they are in.
+ # struct a {
+ # char *p; => char *c.p
+ # } c;
+ $inner_members =~ s/(\**)\s*([\w.]+)\s*;/ $1$struct_name.$2;/g;
+
+ # Remove the leaf. Prefixed members are promoted to the next level
+ # as if they were there from the beginning.
+ $members =~ s/{[^{]*?}\s*([\w.]+)\s*;/$1;$inner_members/;
+ }
create_parameterlist($members, ';', $file);
On Tue, Nov 08, 2005 at 10:38:10PM +0300, Alexey Dobriyan wrote:
> Sam, do you like the syntax? I hope properly indented rendering will
> appear soon.
Looks good. But I like someone with more kernel-doc experince to
comment.
Randy?
Sam
> ------------------------------------
> [PATCH 5/6] kernel-doc: nested structs and unions support
>
> Now something like this
>
> struct a {
> struct b_s {
> union {
> int c;
> int g;
> } u;
> } b;
> struct d_s {
> int e;
> } d;
> };
>
> is possible to document with the following kernel-doc comment:
>
> /**
> * struct a - ...
> *
> * @b: ...
> * @b.u: ...
> * @b.u.c: ...
> * @b.u.g: ...
> * @d: ...
> * @d.e: ...
> */
>
> Not-Yet-Signed-off-by: Alexey Dobriyan <[email protected]>
> ---
>
> scripts/kernel-doc | 33 ++++++++++++++++++++++++++++-----
> 1 file changed, 28 insertions(+), 5 deletions(-)
>
> --- linux-kernel-doc-004/scripts/kernel-doc 2005-05-09 02:34:59.000000000 +0000
> +++ linux-kernel-doc-005/scripts/kernel-doc 2005-05-09 03:46:43.000000000 +0000
> @@ -104,19 +104,26 @@ use strict;
> # Beside functions you can also write documentation for structs, unions,
> # enums and typedefs. Instead of the function name you must write the name
> # of the declaration; the struct/union/enum/typedef must always precede
> -# the name. Nesting of declarations is not supported.
> +# the name.
> # Use the argument mechanism to document members or constants.
> # e.g.
> # /**
> # * struct my_struct - short description
> # * @a: first member
> # * @b: second member
> +# * @c: nested struct
> +# * @c.p: first member of nested struct
> +# * @c.q: second member of nested struct
> # *
> # * Longer description
> # */
> # struct my_struct {
> # int a;
> # int b;
> +# struct her_struct {
> +# char **p;
> +# short q;
> +# } c;
> # };
> #
> # All descriptions can be multiline, except the short function description.
> @@ -156,7 +163,8 @@ my $warnings = 0;
>
> # match expressions used to find embedded type information
> my $type_constant = '\%([-_\w]+)';
> my $type_func = '(\w+)\(\)';
> -my $type_param = '\@(\w+)';
> +# "." is for nested structs/unions.
> +my $type_param = '\@([\w.]+)';
> my $type_struct = '\&((struct\s*)?[_\w]+)';
> my $type_env = '(\$\w+)';
>
> @@ -262,7 +270,8 @@ my $doc_start = '^/\*\*\s*$'; # Allow wh
> my $doc_end = '\*/';
> my $doc_com = '\s*\*\s*';
> my $doc_decl = $doc_com.'(\w+)';
> -my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)';
> +# "." is for nested structs/unions.
> +my $doc_sect = $doc_com.'(['.$doc_special.']?[\w .]+):(.*)';
> my $doc_content = $doc_com.'(.*)';
> my $doc_block = $doc_com.'DOC:\s*(.*)?';
>
> @@ -1292,8 +1301,22 @@ sub dump_struct($$) {
> $declaration_name = $2;
> my $members = $3;
>
> - # ignore embedded structs or unions
> - $members =~ s/{.*?}//g;
> + # Make nested structs/unions tree flat. Proceed from leaves to root.
> + # "." is needed when there is more than one level of nest.
> + while ($members =~ /{([^{]*?)}\s*([\w.]+)/) {
> + my $inner_members = $1;
> + my $struct_name = $2;
> +
> + # Prefix members with the name of the struct/union they are in.
> + # struct a {
> + # char *p; => char *c.p
> + # } c;
> + $inner_members =~ s/(\**)\s*([\w.]+)\s*;/ $1$struct_name.$2;/g;
> +
> + # Remove the leaf. Prefixed members are promoted to the next level
> + # as if they were there from the beginning.
> + $members =~ s/{[^{]*?}\s*([\w.]+)\s*;/$1;$inner_members/;
> + }
>
> create_parameterlist($members, ';', $file);
>
>
hoi :)
On Tue, Nov 08, 2005 at 10:38:10PM +0300, Alexey Dobriyan wrote:
> Sam, do you like the syntax? I hope properly indented rendering will
> appear soon.
Syntax and patch for nested structs looks good.
But are there many nested structs that will be documented that way?
Or is it better to focus on cross references so that we can simply
add documentation for both the inner and outer structure, and add
hyperlinks from the outer to the inner structure?
--
Martin Waitz
On Tue, 8 Nov 2005 22:31:30 +0100 Sam Ravnborg wrote:
> On Tue, Nov 08, 2005 at 10:38:10PM +0300, Alexey Dobriyan wrote:
> > Sam, do you like the syntax? I hope properly indented rendering will
> > appear soon.
> Looks good. But I like someone with more kernel-doc experince to
> comment.
> Randy?
The kernel-doc syntax looks good to me. I'm not so sure about
the presentation part, but I guess that Alexey is stil working
on that part.
I think that I'm agreeing with what Martin Waitz said, that the
implementation is good, but not so sure about the usefulness of it.
Alexey, do you see lots of nested structs (and/or unions) in
kernel APIs? I haven't gone searching for them. Have you?
OTOH, it's not costly, so if it works, it's fine.
~Randy
> Sam
>
> > ------------------------------------
> > [PATCH 5/6] kernel-doc: nested structs and unions support
> >
> > Now something like this
> >
> > struct a {
> > struct b_s {
> > union {
> > int c;
> > int g;
> > } u;
> > } b;
> > struct d_s {
> > int e;
> > } d;
> > };
> >
> > is possible to document with the following kernel-doc comment:
> >
> > /**
> > * struct a - ...
> > *
> > * @b: ...
> > * @b.u: ...
> > * @b.u.c: ...
> > * @b.u.g: ...
> > * @d: ...
> > * @d.e: ...
> > */
> >
> > Not-Yet-Signed-off-by: Alexey Dobriyan <[email protected]>
> > ---
> >
> > scripts/kernel-doc | 33 ++++++++++++++++++++++++++++-----
> > 1 file changed, 28 insertions(+), 5 deletions(-)
> >
> > --- linux-kernel-doc-004/scripts/kernel-doc 2005-05-09 02:34:59.000000000 +0000
> > +++ linux-kernel-doc-005/scripts/kernel-doc 2005-05-09 03:46:43.000000000 +0000
> > @@ -104,19 +104,26 @@ use strict;
> > # Beside functions you can also write documentation for structs, unions,
> > # enums and typedefs. Instead of the function name you must write the name
> > # of the declaration; the struct/union/enum/typedef must always precede
> > -# the name. Nesting of declarations is not supported.
> > +# the name.
> > # Use the argument mechanism to document members or constants.
> > # e.g.
> > # /**
> > # * struct my_struct - short description
> > # * @a: first member
> > # * @b: second member
> > +# * @c: nested struct
> > +# * @c.p: first member of nested struct
> > +# * @c.q: second member of nested struct
> > # *
> > # * Longer description
> > # */
> > # struct my_struct {
> > # int a;
> > # int b;
> > +# struct her_struct {
> > +# char **p;
> > +# short q;
> > +# } c;
> > # };
> > #
> > # All descriptions can be multiline, except the short function description.