On Mon, 17 Aug 2020, Jan Beulich wrote: > 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.
Thanks Jan. I would prefer to get this series in as is (with the other minor changes we discussed) as basic enablement for kernel-doc. I volunteer to have a look into this issue and try to come up with a better alternative afterward.