Re: kernel-doc and xen.git

[Ian Jackson <ian.jackson@xxxxxxxxxx>]

George Dunlap writes ("Re: kernel-doc and xen.git"):
> > On Jul 30, 2020, at 2:27 AM, Stefano Stabellini <sstabellini@xxxxxxxxxx> 
> > 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.

Ian.