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

["Randy.Dunlap" <rdunlap@xenotime.net>]

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.