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);
>
>
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
[Index of Archives]
[Kernel Newbies]
[Netfilter]
[Bugtraq]
[Photo]
[Stuff]
[Gimp]
[Yosemite News]
[MIPS Linux]
[ARM Linux]
[Linux Security]
[Linux RAID]
[Video 4 Linux]
[Linux for the blind]
[Linux Resources]
