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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 21/10/2020 23:08, Stefano Stabellini wrote:
> On Wed, 21 Oct 2020, Andrew Cooper wrote:
>> On 21/10/2020 01:00, Stefano Stabellini wrote:
>>> Hi all,
>>>
>>> This patch series converts Xen in-code comments to the kernel-doc (and
>>> doxygen) format:
>>>
>>> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
>>>
>>> Please note that this patch series is meant as groundwork. The end goal
>>> is to enable a more sophisticated documents generation with doxygen,
>>> see: https://marc.info/?l=xen-devel&m=160220627022339
>>>
>>>
>>> # Changes compared to v1:
>>> - addressed review comments
>>> - use oneline comments even for nested struct members
>> On the whole, good.
>>
>> However, there is one thing which problematic.  Right from patch 1, you
>> start breaking the content used to render
>> https://xenbits.xen.org/docs/unstable/hypercall/index.html
>>
>> Either the patches need to incrementally feed the converted files into
>> Sphinx directly (possibly with some one-time plumbing ahead of time), or
>> patch 1 needs to be some script in docs/ capable of rendering kernel-doc
>> to HTML, so we at least keep the plain docs around until the Sphinx
>> integration is complete.
>>
>> i.e. don't cause what we currently have to fall off
>> https://xenbits.xen.org/docs/ entirely as a consequence of this series.
> Thanks for pointing this out, it was not my intention. In fact, I wasn't
> aware of https://xenbits.xen.org/docs/unstable/hypercall/index.html at
> all. How is it generated? I am asking because I need to understand how
> that works in order not to break it...

docs/xen-headers which is a random perl script suffering from
NIH-syndrome in a world with many far better alternatives.

> Is it just a matter of retaining the keywords like `incontents 50 and other
> comments starting with ` ?

I deliberately tried not to specify that "it should remain as is".

I will happily delete this script and infrastructure if you don't beat
me too it first, and it was one of my goals of suggesting kernel-doc in
the first place.  After all, our longterm goal is to move fully over to
Sphinx.

If that means maintaining both the legacy and the new side-by-side,
fine.  If it means moving one single header at a time fully into sphinx,
also fine.  (Observe that https://xenbits.xen.org/docs/latest/ is Sphinx
rendered from staging).  I certainly don't intend for the docs to
survive in their current form forever.

All I want to avoid is that the hypercall documentation disappears
entirely from https://xenbits.xen.org/docs/ in the interim.

~Andrew