Re: [PATCH 00/14] kernel-doc: public/arch-arm.h

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Fri, 7 Aug 2020, Jan Beulich wrote:
> On 07.08.2020 01:49, Stefano Stabellini wrote:
> > # THE KERNEL-DOC KEYWORDS USED
> > 
> > I used the "struct" keyword for structures, i.e.:
> > 
> > /**
> >  * struct foobar
> >  */
> > 
> > "struct" makes kernel-doc go and look at the following struct in the
> > code, parses struct members comments, and generate a doc optimized to
> > describe a struct. Note that in these cases the struct needs to follow
> > immediately the comment. Thus, I had to move an #define between the
> > comment and the struct in a few places.
> > 
> > Also note that kernel-doc supports nested structs but due to a quirk,
> > comments for nested struct members cannot be on a single line. They have
> > to be:
> > 
> >   struct foo {
> >       struct {
> >           /**
> >            * @u.bar: foobar
> >            */
> >           bar;
> >       } u;
> >   }
> 
> Urgh.
> 
> > Otherwise for normal struct the single line comment works fine:
> > 
> >   struct foo {
> >       /** @bar: foobar */
> >       bar;
> >   }
> > 
> > 
> > I used the "DOC" keyword otherwise. "DOC" is freeform, not particularly
> > tied to anything following (functions, enums, etc.) I kept a black line
> > between "DOC" and the following comment if multiline and no blank line
> > if it is single line.
> > 
> >   /**
> >    * DOC: doc1
> >    * single line comment
> >    */
> > 
> >    /**
> >     * DOC: doc2
> >     *
> >     * this is
> >     * multiline
> >     */
> 
> I think before the first piece of this goes in (or together with it
> going in), ./CODING_STYLE wants to be updated to reflect this. It is
> particularly relevant imo to mention the quirk above and hence the
> necessary exception (even better of course would be to get the quirk
> out of kernel-doc).
 
Yes, I can add a patch to change ./CODING_STYLE. I think we should
encourage people to use the kernel-doc syntax at least for public
headers. I can document the use of the "struct" and "DOC" keywords, and
also the quirk with nested structs.

Note that instead the black line after DOC is completely optional from
a kernel-doc perspective, I did it for style, but I can add that to
./CODING_STYLE too.