lkml.org 
[lkml]   [2005]   [Nov]   [9]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: [PATCH 5/6] kernel-doc: nested structs and unions support
    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.
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/

    \
     
     \ /
      Last update: 2005-11-09 06:31    [W:5.061 / U:0.012 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site