kernel-doc and xen.git

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

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.

At a minimum we'll need to start the in-code comment blocks with two
stars:

    /**

There could be also other small changes required to make sure the output
is appropriate.


Feedback is welcome!

Cheers,

Stefano

[1] 
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/kernel-doc
[2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html