From: Stefano Stabellini <sstabellini@kernel.org>
To: Ian Jackson <ian.jackson@citrix.com>
Cc: "xen-devel@lists.xenproject.org" <xen-devel@lists.xenproject.org>,
Stefano Stabellini <sstabellini@kernel.org>,
Committers <committers@xenproject.org>,
George Dunlap <George.Dunlap@citrix.com>,
"Bertrand.Marquis@arm.com" <Bertrand.Marquis@arm.com>
Subject: Re: kernel-doc and xen.git
Date: Thu, 30 Jul 2020 18:16:08 -0700 (PDT) [thread overview]
Message-ID: <alpine.DEB.2.21.2007300956020.1767@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <24354.50708.138178.815210@mariner.uk.xensource.com>
[-- Attachment #1: Type: text/plain, Size: 2170 bytes --]
On Thu, 30 Jul 2020, Ian Jackson wrote:
> George Dunlap writes ("Re: kernel-doc and xen.git"):
> > > On Jul 30, 2020, at 2:27 AM, Stefano Stabellini <sstabellini@kernel.org> wrote:
> ...
> > > I did give a look at kernel-doc and it is very promising. kernel-doc is
> > > a script that can generate nice rst text documents from in-code
> > > comments. (The generated rst files can then be used as input for sphinx
> > > to generate html docs.) The comment syntax [2] is simple and similar to
> > > Doxygen:
> > >
> > > /**
> > > * function_name() - Brief description of function.
> > > * @arg1: Describe the first argument.
> > > * @arg2: Describe the second argument.
> > > * One can provide multiple line descriptions
> > > * for arguments.
> > > */
> > >
> > > kernel-doc is actually better than Doxygen because it is a much simpler
> > > tool, one we could customize to our needs and with predictable output.
> > > Specifically, we could add the tagging, numbering, and referencing
> > > required by FuSa requirement documents.
> > >
> > > I would like your feedback on whether it would be good to start
> > > converting xen.git in-code comments to the kernel-doc format so that
> > > proper documents can be generated out of them. One day we could import
> > > kernel-doc into xen.git/scripts and use it to generate a set of html
> > > documents via sphinx.
> >
> > `git-grep ‘^/\*\*$’ ` turns up loads of instances of kernel-doc-style comments in the tree already. I think it makes complete sense to:
> >
> > 1. Start using tools to pull the existing ones into sphinx docs
> > 2. Skim through the existing ones to make sure they’re accurate / useful
> > 3. Add such comments for elements of key importance to the FUSA SIG
> > 4. Encourage people include documentation for new features, &c
>
> I have no objection to this. Indeed switching to something the kernel
> folks find useable is likely to be a good idea.
>
> We should ideally convert the existing hypercall documentation, which
> is parsed from a bespoke magic comment format by a script in xen.git.
I agree.
Great, thank you both for the feedback!
next prev parent reply other threads:[~2020-07-31 1:16 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-07-30 1:27 kernel-doc and xen.git Stefano Stabellini
2020-07-30 11:13 ` George Dunlap
2020-07-30 13:07 ` Ian Jackson
2020-07-31 1:16 ` Stefano Stabellini [this message]
2020-07-31 11:29 ` Jan Beulich
2020-07-31 12:48 ` Bertrand Marquis
2020-07-31 12:51 ` George Dunlap
2020-07-31 16:18 ` Stefano Stabellini
2020-07-31 13:48 ` Andrew Cooper
2020-07-31 13:50 ` Bertrand Marquis
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.2007300956020.1767@sstabellini-ThinkPad-T480s \
--to=sstabellini@kernel.org \
--cc=Bertrand.Marquis@arm.com \
--cc=George.Dunlap@citrix.com \
--cc=committers@xenproject.org \
--cc=ian.jackson@citrix.com \
--cc=xen-devel@lists.xenproject.org \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).