[PATCH 5/6] kernel-doc: nested structs and unions support

[PATCH 5/6] kernel-doc: nested structs and unions support

[Alexey Dobriyan]

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 <adobriyan@gmail.com>
---

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

Re: [PATCH 5/6] kernel-doc: nested structs and unions support

[Sam Ravnborg]

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 <adobriyan@gmail.com>
> ---
> 
>  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);
>  
> 

Re: [PATCH 5/6] kernel-doc: nested structs and unions support

[Randy.Dunlap]

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 <adobriyan@gmail.com>
> > ---
> > 
> >  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.

Re: [PATCH 5/6] kernel-doc: nested structs and unions support

[Martin Waitz]

[-- Attachment #1: Type: text/plain, Size: 493 bytes --]

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

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]