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

From: Stefano Stabellini <sstabellini@kernel.org>
To: Jan Beulich <jbeulich@suse.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	julien@xen.org, wl@xen.org, andrew.cooper3@citrix.com,
	ian.jackson@eu.citrix.com, george.dunlap@citrix.com,
	xen-devel@lists.xenproject.org
Subject: Re: [PATCH 00/14] kernel-doc: public/arch-arm.h
Date: Fri, 7 Aug 2020 14:51:10 -0700 (PDT)	[thread overview]
Message-ID: <alpine.DEB.2.21.2008071210140.16004@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <7923d0f4-a446-c852-5423-0fe65ef27a41@suse.com>

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.