Re: kernel-doc and xen.git

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

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

I agree.

Great, thank you both for the feedback!