| Message ID | alpine.DEB.2.21.2008061605410.16004@sstabellini-ThinkPad-T480s (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
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
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(-)
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.
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.
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 :-)
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(-)