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