mbox

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

Message ID alpine.DEB.2.21.2008061605410.16004@sstabellini-ThinkPad-T480s
State New
Headers show

Pull-request

http://xenbits.xenproject.org/git-http/people/sstabellini/xen-unstable.git hyp-docs-1

Message

Stefano Stabellini Aug. 6, 2020, 11:49 p.m. UTC
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(-)

Comments

Jan Beulich Aug. 7, 2020, 8:48 a.m. UTC | #1
On 07.08.2020 01:49, Stefano Stabellini wrote:
> # 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;
>   }

Urgh.

> 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
>     */

I think before the first piece of this goes in (or together with it
going in), ./CODING_STYLE wants to be updated to reflect this. It is
particularly relevant imo to mention the quirk above and hence the
necessary exception (even better of course would be to get the quirk
out of kernel-doc).

Jan
Stefano Stabellini Aug. 7, 2020, 4:56 p.m. UTC | #2
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(-)
Stefano Stabellini Aug. 7, 2020, 9:51 p.m. UTC | #3
On Fri, 7 Aug 2020, Jan Beulich wrote:
> On 07.08.2020 01:49, Stefano Stabellini wrote:
> > # 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;
> >   }
> 
> Urgh.
> 
> > 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
> >     */
> 
> I think before the first piece of this goes in (or together with it
> going in), ./CODING_STYLE wants to be updated to reflect this. It is
> particularly relevant imo to mention the quirk above and hence the
> necessary exception (even better of course would be to get the quirk
> out of kernel-doc).
 
Yes, I can add a patch to change ./CODING_STYLE. I think we should
encourage people to use the kernel-doc syntax at least for public
headers. I can document the use of the "struct" and "DOC" keywords, and
also the quirk with nested structs.

Note that instead the black line after DOC is completely optional from
a kernel-doc perspective, I did it for style, but I can add that to
./CODING_STYLE too.
Ian Jackson Aug. 18, 2020, 12:52 p.m. UTC | #4
Stefano Stabellini writes ("Re: [PATCH 00/14] kernel-doc: public/arch-arm.h"):
> 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.

Thanks.

Thanks for all your work.  This is definiteely going in the right
direection.  I skimread all the patches and have nothing further to
add to what others have said.

How soon can we arrange for this processing to be done automatically
(on xenbits, I guess) ?  Would you be prepared to set this up if I add
your ssh key to the "xendocs" account which builds the existing docs ?

Ian.
Stefano Stabellini Aug. 20, 2020, 7:02 p.m. UTC | #5
On Tue, 18 Aug 2020, Ian Jackson wrote:
> Stefano Stabellini writes ("Re: [PATCH 00/14] kernel-doc: public/arch-arm.h"):
> > 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.
> 
> Thanks.
> 
> Thanks for all your work.  This is definiteely going in the right
> direection.  I skimread all the patches and have nothing further to
> add to what others have said.

Thanks for looking into it!


> How soon can we arrange for this processing to be done automatically
> (on xenbits, I guess) ?  Would you be prepared to set this up if I add
> your ssh key to the "xendocs" account which builds the existing docs ?

Yes, I can do that.

This series was only meant to provide the basic groundwork, I wasn't
thinking of adding the kernel-doc script to xen.git or the automatic
docs build as part of it. However, I do have work in the pipeline to do
that too: right now I am experimenting with some kernel-doc changes to
produce better output docs for Xen. I am planning on sending that out
soon after this series gets in, so maybe in few weeks or a month.

Since I am here, I'd like to give you a heads up that I'll need your
help reviewing or maybe making some changes to kernel-doc because my
perl is nonexistent so I am probably doing something awful :-)