All of lore.kernel.org
 help / color / mirror / Atom feed
From: Stefano Stabellini <sstabellini@kernel.org>
To: xen-devel@lists.xenproject.org
Cc: sstabellini@kernel.org, julien@xen.org, wl@xen.org,
	andrew.cooper3@citrix.com, ian.jackson@eu.citrix.com,
	george.dunlap@citrix.com, jbeulich@suse.com
Subject: [PATCH 00/14] kernel-doc: public/arch-arm.h
Date: Thu, 6 Aug 2020 16:49:15 -0700 (PDT)	[thread overview]
Message-ID: <alpine.DEB.2.21.2008061605410.16004@sstabellini-ThinkPad-T480s> (raw)

[-- Attachment #1: Type: text/plain, Size: 4688 bytes --]

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(-)

[-- Attachment #2: Type: application/gzip, Size: 128296 bytes --]

             reply	other threads:[~2020-08-06 23:49 UTC|newest]

Thread overview: 38+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-06 23:49 Stefano Stabellini [this message]
2020-08-06 23:49 ` [PATCH 01/14] " Stefano Stabellini
2020-08-18 12:42   ` Ian Jackson
2020-08-20 19:05     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 02/14] kernel-doc: public/hvm/hvm_op.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 03/14] kernel-doc: public/device_tree_defs.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 04/14] kernel-doc: public/event_channel.h Stefano Stabellini
2020-08-07 13:01   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 05/14] kernel-doc: public/features.h Stefano Stabellini
2020-08-07 12:54   ` Jan Beulich
2020-08-07 21:52     ` Stefano Stabellini
2020-08-17 15:26       ` Jan Beulich
2020-08-17 22:56         ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 06/14] kernel-doc: public/grant_table.h Stefano Stabellini
2020-08-07 12:59   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 07/14] kernel-doc: public/hypfs.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 08/14] kernel-doc: public/memory.h Stefano Stabellini
2020-08-07 13:07   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-17 15:32       ` Jan Beulich
2020-08-17 22:56         ` Stefano Stabellini
2020-08-18  8:05           ` Jan Beulich
2020-08-20 23:20             ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 09/14] kernel-doc: public/sched.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 10/14] kernel-doc: public/vcpu.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 11/14] kernel-doc: public/version.h Stefano Stabellini
2020-08-07 13:12   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 12/14] kernel-doc: public/xen.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 13/14] kernel-doc: public/elfnote.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 14/14] kernel-doc: public/hvm/params.h Stefano Stabellini
2020-08-07  8:48 ` [PATCH 00/14] kernel-doc: public/arch-arm.h Jan Beulich
2020-08-07 21:51   ` Stefano Stabellini
2020-08-07 16:56 ` Stefano Stabellini
2020-08-18 12:52   ` Ian Jackson
2020-08-20 19:02     ` Stefano Stabellini

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=alpine.DEB.2.21.2008061605410.16004@sstabellini-ThinkPad-T480s \
    --to=sstabellini@kernel.org \
    --cc=andrew.cooper3@citrix.com \
    --cc=george.dunlap@citrix.com \
    --cc=ian.jackson@eu.citrix.com \
    --cc=jbeulich@suse.com \
    --cc=julien@xen.org \
    --cc=wl@xen.org \
    --cc=xen-devel@lists.xenproject.org \
    --subject='Re: [PATCH 00/14] kernel-doc: public/arch-arm.h' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.