All of lore.kernel.org
 help / color / mirror / Atom feed
From: Stefano Stabellini <sstabellini@kernel.org>
To: Ian Jackson <ian.jackson@citrix.com>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	 "xen-devel@lists.xenproject.org"
	<xen-devel@lists.xenproject.org>,
	 Andrew Cooper <Andrew.Cooper3@citrix.com>,
	 George Dunlap <George.Dunlap@citrix.com>,
	 "jbeulich@suse.com" <jbeulich@suse.com>,
	"julien@xen.org" <julien@xen.org>,  "wl@xen.org" <wl@xen.org>,
	 Stefano Stabellini <stefano.stabellini@xilinx.com>
Subject: Re: [PATCH 01/14] kernel-doc: public/arch-arm.h
Date: Thu, 20 Aug 2020 12:05:41 -0700 (PDT)	[thread overview]
Message-ID: <alpine.DEB.2.21.2008201157520.6005@sstabellini-ThinkPad-T480s> (raw)
In-Reply-To: <24379.52418.438897.155721@mariner.uk.xensource.com>

On Tue, 18 Aug 2020, Ian Jackson wrote:
> Stefano Stabellini writes ("[PATCH 01/14] kernel-doc: public/arch-arm.h"):
> > From: Stefano Stabellini <stefano.stabellini@xilinx.com>
> > 
> > Convert in-code comments to kernel-doc format wherever possible.
> 
> Thanks.  But, err, I think there is not yet any in-tree machinery for
> actually building and publishing these kernel-doc comments ?

No, there isn't. But you can call kernel-doc on the headers manually and
it will produce fully readable docs in RST format. (Then you can covert
RST docs to HTML with Sphinx.) Like:

  kernel-doc xen/include/public/features.h > readme-features.rst

I also gave a few more details on the plan I had in my other email
reply.


> As I said I think replacing our ad-hoc in-tree system with kernel-doc
> is a good idea, but...
> 
> > -/*
> > - * `incontents 50 arm_abi Hypercall Calling Convention
> > +/**
> > + * DOC: Hypercall Calling Convention
> 
> ... let us not replace the in-tree markup for that system until we
> have its replacement.

Ah! I didn't know what 

  `incontents 50 arm_abi

was for. I assumed it was a relic of another era and removed it.

Is it actually used (and the other markups like that)? Is there
a script somewhere that parses it in xen.git or on xenbits already?

If they are in-use, then I can try to retain them for now until we have
the kernel-doc infrastructure on xenbits -- they should be compatible
with the kernel-doc syntax.


  reply	other threads:[~2020-08-20 19:05 UTC|newest]

Thread overview: 38+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-06 23:49 [PATCH 00/14] kernel-doc: public/arch-arm.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 01/14] " Stefano Stabellini
2020-08-18 12:42   ` Ian Jackson
2020-08-20 19:05     ` Stefano Stabellini [this message]
2020-08-06 23:49 ` [PATCH 02/14] kernel-doc: public/hvm/hvm_op.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 03/14] kernel-doc: public/device_tree_defs.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 04/14] kernel-doc: public/event_channel.h Stefano Stabellini
2020-08-07 13:01   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 05/14] kernel-doc: public/features.h Stefano Stabellini
2020-08-07 12:54   ` Jan Beulich
2020-08-07 21:52     ` Stefano Stabellini
2020-08-17 15:26       ` Jan Beulich
2020-08-17 22:56         ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 06/14] kernel-doc: public/grant_table.h Stefano Stabellini
2020-08-07 12:59   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 07/14] kernel-doc: public/hypfs.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 08/14] kernel-doc: public/memory.h Stefano Stabellini
2020-08-07 13:07   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-17 15:32       ` Jan Beulich
2020-08-17 22:56         ` Stefano Stabellini
2020-08-18  8:05           ` Jan Beulich
2020-08-20 23:20             ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 09/14] kernel-doc: public/sched.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 10/14] kernel-doc: public/vcpu.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 11/14] kernel-doc: public/version.h Stefano Stabellini
2020-08-07 13:12   ` Jan Beulich
2020-08-07 21:51     ` Stefano Stabellini
2020-08-06 23:49 ` [PATCH 12/14] kernel-doc: public/xen.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 13/14] kernel-doc: public/elfnote.h Stefano Stabellini
2020-08-06 23:49 ` [PATCH 14/14] kernel-doc: public/hvm/params.h Stefano Stabellini
2020-08-07  8:48 ` [PATCH 00/14] kernel-doc: public/arch-arm.h Jan Beulich
2020-08-07 21:51   ` Stefano Stabellini
2020-08-07 16:56 ` Stefano Stabellini
2020-08-18 12:52   ` Ian Jackson
2020-08-20 19:02     ` Stefano Stabellini

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.2008201157520.6005@sstabellini-ThinkPad-T480s \
    --to=sstabellini@kernel.org \
    --cc=Andrew.Cooper3@citrix.com \
    --cc=George.Dunlap@citrix.com \
    --cc=ian.jackson@citrix.com \
    --cc=jbeulich@suse.com \
    --cc=julien@xen.org \
    --cc=stefano.stabellini@xilinx.com \
    --cc=wl@xen.org \
    --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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.