| Message ID | alpine.DEB.2.21.2010201646370.12247@sstabellini-ThinkPad-T480s (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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
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... Is it just a matter of retaining the keywords like `incontents 50 and other comments starting with ` ? Otherwise, yes, I could add kernel-doc to docs/ or scripts/ to generate markdown documents, which could be turned to HTML with Sphynx.
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
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 # WHAT WAS CONVERTED I started from the public/ header files as I thought they are the most important to generated documentation for. I didn't cover all files under xen/include/public/, but we don't have to boil the ocean in one go. For the header files I addressed, I did cover all in-code comments except for very few exceptions where the conversion to kernel-doc format wasn't easily doable without major changes to the comments/code. The conversion was done by hand (sigh!) but was mechanical, and only stylistic: I didn't change the content of the comments (only in a couple of places to make the English work right, e.g. when a comment has been split into two comments.) # THE KERNEL-DOC KEYWORDS USED I used the "struct" keyword for structures, i.e.: /** * struct foobar */ "struct" makes kernel-doc go and look at the following struct in the code, parses struct members comments, and generate a doc optimized to describe a struct. Note that in these cases the struct needs to follow immediately the comment. Thus, I had to move an #define between the comment and the struct in a few places. Also note that kernel-doc supports nested structs but due to a quirk comments for nested struct members are not recognized if they are on a single line. Still, this version of the series uses single line comments with the idea of fixing the document-generation tool later. I used the "DOC" keyword otherwise. "DOC" is freeform, not particularly tied to anything following (functions, enums, etc.) I kept a black line between "DOC" and the following comment if multiline and no blank line if it is single line. /** * DOC: doc1 * single line comment */ /** * DOC: doc2 * * this is * multiline */ DOC doesn't generate any cross-documents links but it is still a great place to start as it makes the in-code comments immediately available as documents. Linking and references can be added later. # HOW TO TEST IT Simply run kernel-doc on a header file, for instance: ../linux/scripts/kernel-doc xen/include/public/event_channel.h > /tmp/doc.rst You can inspect the rst file and also generate a html file out of it with sphinx: sphinx-quickstart sphinx-build . /path/to/out Cheers, Stefano The following changes since commit 3b49791e4cc2f38dd84bf331b75217adaef636e3: xen/arm: Print message if reset did not work (2020-10-20 13:20:31 -0700) are available in the Git repository at: http://xenbits.xenproject.org/git-http/people/sstabellini/xen-unstable.git hyp-docs-2 for you to fetch changes up to 393bd090ae4f09bc68aa35af74e087cd4615be5a: kernel-doc: public/hvm/params.h (2020-10-20 16:45:54 -0700) ---------------------------------------------------------------- Stefano Stabellini (14): kernel-doc: public/arch-arm.h kernel-doc: public/hvm/hvm_op.h kernel-doc: public/device_tree_defs.h kernel-doc: public/event_channel.h kernel-doc: public/features.h kernel-doc: public/grant_table.h kernel-doc: public/hypfs.h kernel-doc: public/memory.h kernel-doc: public/sched.h kernel-doc: public/vcpu.h kernel-doc: public/version.h kernel-doc: public/xen.h kernel-doc: public/elfnote.h kernel-doc: public/hvm/params.h xen/include/public/arch-arm.h | 43 ++- xen/include/public/device_tree_defs.h | 24 +- xen/include/public/elfnote.h | 109 +++++-- xen/include/public/event_channel.h | 184 ++++++----- xen/include/public/features.h | 78 +++-- xen/include/public/grant_table.h | 447 +++++++++++++++------------ xen/include/public/hvm/hvm_op.h | 20 +- xen/include/public/hvm/params.h | 153 +++++++-- xen/include/public/hypfs.h | 72 +++-- xen/include/public/memory.h | 236 +++++++++----- xen/include/public/sched.h | 134 +++++--- xen/include/public/vcpu.h | 180 ++++++++--- xen/include/public/version.h | 73 ++++- xen/include/public/xen.h | 566 ++++++++++++++++++++++------------ 14 files changed, 1544 insertions(+), 775 deletions(-)