On 30.07.2020 03:27, Stefano Stabellini wrote: > 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.
How far is this intended to go? The example is description of a function's parameters, which is definitely fine (albeit I wonder if there's a hidden implication then that _all_ functions whatsoever are supposed to gain such comments). But the text just says much more generally "in-code comments", which could mean all of them. I'd consider the latter as likely going too far. Jan
