Xen-Devel Archive on lore.kernel.org
 help / color / Atom feed
From: Stefano Stabellini <sstabellini@kernel.org>
To: George Dunlap <George.Dunlap@citrix.com>
Cc: "xen-devel@lists.xenproject.org" <xen-devel@lists.xenproject.org>,
	Stefano Stabellini <sstabellini@kernel.org>,
	"committers@xenproject.org" <committers@xenproject.org>,
	Jan Beulich <jbeulich@suse.com>,
	"Bertrand.Marquis@arm.com" <Bertrand.Marquis@arm.com>
Subject: Re: kernel-doc and xen.git
Date: Fri, 31 Jul 2020 09:18:51 -0700 (PDT)
Message-ID: <alpine.DEB.2.21.2007310918360.1767@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <F09D32F7-4826-421B-99A6-3E94756FFCEF@citrix.com>


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

On Fri, 31 Jul 2020, George Dunlap wrote:
> > On Jul 31, 2020, at 12:29 PM, Jan Beulich <jbeulich@suse.com> wrote:
> > 
> > On 30.07.2020 03:27, Stefano Stabellini wrote:
> >> Hi all,
> >> 
> >> I would like to ask for your feedback on the adoption of the kernel-doc
> >> format for in-code comments.
> >> 
> >> In the FuSa SIG we have started looking into FuSa documents for Xen. One
> >> of the things we are investigating are ways to link these documents to
> >> in-code comments in xen.git and vice versa.
> >> 
> >> In this context, Andrew Cooper suggested to have a look at "kernel-doc"
> >> [1] during one of the virtual beer sessions at the last Xen Summit.
> >> 
> >> 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.
> > 
> > How far is this intended to go? The example is description of a
> > function's parameters, which is definitely fine (albeit I wonder
> > if there's a hidden implication then that _all_ functions
> > whatsoever are supposed to gain such comments). But the text just
> > says much more generally "in-code comments", which could mean all
> > of them. I'd consider the latter as likely going too far.
> 
> I took him to mean comments in the code at the moment, which describe some interface, but aren’t in kernel-doc format.  Naturally we wouldn’t want *all* comments to be stuffed into a document somewhere.

+1

  reply index

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-30  1:27 Stefano Stabellini
2020-07-30 11:13 ` George Dunlap
2020-07-30 13:07   ` Ian Jackson
2020-07-31  1:16     ` Stefano Stabellini
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 [this message]
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.2007310918360.1767@sstabellini-ThinkPad-T480s \
    --to=sstabellini@kernel.org \
    --cc=Bertrand.Marquis@arm.com \
    --cc=George.Dunlap@citrix.com \
    --cc=committers@xenproject.org \
    --cc=jbeulich@suse.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

Xen-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/xen-devel/0 xen-devel/git/0.git
	git clone --mirror https://lore.kernel.org/xen-devel/1 xen-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 xen-devel xen-devel/ https://lore.kernel.org/xen-devel \
		xen-devel@lists.xenproject.org xen-devel@lists.xen.org
	public-inbox-index xen-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.xenproject.lists.xen-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git