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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

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.

~Andrew