Re: [PATCH 01/14] kernel-doc: public/arch-arm.h

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

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@xxxxxxxxxx>
> > 
> > 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.