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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

I am replying to this email as I have been told that the original was
filtered as spam due to the tarball attachment. The tarball contains
some example html output document files from sphinx.

I have uploaded the tarball here for your convenience:

http://xenbits.xenproject.org/people/sstabellini/html.tar.gz

You can read the original email below.


On Thu, 6 Aug 2020, Stefano Stabellini wrote:
> Hi all,
> 
> This patch series convert Xen in-code comments to the kernel-doc format:
> 
> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
> 
> 
> # 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 cannot be on a single line. They have
> to be:
> 
>   struct foo {
>       struct {
>           /**
>            * @u.bar: foobar
>            */
>           bar;
>       } u;
>   }
> 
> Otherwise for normal struct the single line comment works fine:
> 
>   struct foo {
>       /** @bar: foobar */
>       bar;
>   }
> 
> 
> 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
> 
> I am attaching two example output html files together with the static CSS
> and images to render them correctly. Note that of course I haven't
> worked on the CSS at all, clearly the style can be vastly improved, but
> I wanted to give you an idea of how readable they actually are even like
> this.
> 
> 
> Cheers,
> 
> Stefano
> 
> 
> The following changes since commit 81fd0d3ca4b2cd309403c6e8da662c325dd35750:
> 
>   x86/hvm: simplify 'mmio_direct' check in epte_get_entry_emt() (2020-07-31 
> 17:43:31 +0200)
> 
> are available in the Git repository at:
> 
>   http://xenbits.xenproject.org/git-http/people/sstabellini/xen-unstable.git 
> hyp-docs-1 
> 
> for you to fetch changes up to abbd21dfa0ff14a7eb5faa57aaf3db24f83a149f:
> 
>   kernel-doc: public/hvm/params.h (2020-08-06 16:27:22 -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    | 188 +++++++----
>  xen/include/public/features.h         |  78 +++--
>  xen/include/public/grant_table.h      | 443 +++++++++++++++-----------
>  xen/include/public/hvm/hvm_op.h       |  20 +-
>  xen/include/public/hvm/params.h       | 158 ++++++++--
>  xen/include/public/hypfs.h            |  72 +++--
>  xen/include/public/memory.h           | 232 +++++++++-----
>  xen/include/public/sched.h            | 129 +++++---
>  xen/include/public/vcpu.h             | 180 ++++++++---
>  xen/include/public/version.h          |  74 ++++-
>  xen/include/public/xen.h              | 567 
> ++++++++++++++++++++++------------
>  14 files changed, 1564 insertions(+), 753 deletions(-)