> On 31 Jul 2020, at 13:29, Jan Beulich <jbeul...@suse.com> wrote:
>
> 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.
The idea in the FuSa project is more to start with external interfaces like
hypercall definitions and public headers elements.
Bertrand
>
> Jan
