mbox

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

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

Pull-request

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

Message

Stefano Stabellini Oct. 21, 2020, midnight UTC
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(-)

Comments

Andrew Cooper Oct. 21, 2020, 5:41 p.m. UTC | #1
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
Stefano Stabellini Oct. 21, 2020, 10:08 p.m. UTC | #2
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.
Andrew Cooper Oct. 21, 2020, 10:19 p.m. UTC | #3
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