Re: [PATCH 05/14] kernel-doc: public/features.h

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Fri, 7 Aug 2020, Jan Beulich wrote:
> On 07.08.2020 01:49, Stefano Stabellini wrote:
> > @@ -41,19 +41,25 @@
> >   * XENFEAT_dom0 MUST be set if the guest is to be booted as dom0,
> >   */
> >  
> > -/*
> > - * If set, the guest does not need to write-protect its pagetables, and can
> > - * update them via direct writes.
> > +/**
> > + * DOC: XENFEAT_writable_page_tables
> > + *
> > + * If set, the guest does not need to write-protect its pagetables, and
> > + * can update them via direct writes.
> >   */
> >  #define XENFEAT_writable_page_tables       0
> 
> I dislike such redundancy (and it's more noticable here than with
> the struct-s). Is there really no way for the tool to find the
> right item, the more that in the cover letter you say that you
> even need to get the placement right, i.e. there can't be e.g.
> intervening #define-s?

Let me clarify that the right placement (nothing between the comment and
the following structure) is important for structs, typedefs, etc., but
not for "DOC". DOC is freeform and doesn't have to be followed by
anything specifically.


In regards to the redundancy, there is only another option, that I
didn't choose because it leads to worse documents being generated.
However, they are still readable, so if the agreement is to use the
other format, I would be OK with it.


The other format is the keyword "macro" (this one would have to have the
right placement, straight on top of the #define):

/**
 * macro XENFEAT_writable_page_tables
 *
 * If set, the guest does not need to write-protect its pagetables, and
 * can update them via direct writes.
 */


Which could be further simplified to:

/**
 * macro
 *
 * If set, the guest does not need to write-protect its pagetables, and
 * can update them via direct writes.
 */


In terms of redundancy, that's the best we can do.

The reason why I say it is not optimal is that with DOC the pleudo-html
generated via sphinx is:

---
* XENFEAT_writable_page_tables *

If set, the guest does not need to write-protect its pagetables, and
can update them via direct writes.
---

While with macro, two () parenthesis gets added to the title, and also an
empty "Parameters" section gets added, like this:

---
* XENFEAT_writable_page_tables() *

** Parameters **

** Description **

If set, the guest does not need to write-protect its pagetables, and
can update them via direct writes.
---


I think it could be confusing to the user: it looks like a macro with
parameters, which is not what we want.

For that reason, I think we should stick with "DOC" for now.