On 07.08.2020 23:52, Stefano Stabellini wrote: > 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.
Agreed, so ... > For that reason, I think we should stick with "DOC" for now. ... if there are no (better) alternatives we'll have to live with the redundancy. Jan
