[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: kernel-doc and xen.git

  • To: Jan Beulich <jbeulich@xxxxxxxx>
  • From: Bertrand Marquis <Bertrand.Marquis@xxxxxxx>
  • Date: Fri, 31 Jul 2020 12:48:01 +0000
  • Accept-language: en-GB, en-US
  • Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none
  • Arc-message-signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=63LxU5fX9gZp/NnEyliV3iSuEgzXGxcrXnHh99UrHXk=; b=SjihB9uB9Bq/59yT9QYBQIWW9lHNYs2ExEbVkAM9Amm7iSX2MKUSeFzHdqoagzSghrXp95EXNUjuRdjZjGTYoBqzZ7OYyrlcfRHCQkpjevRqJYjU6Xn35VeMObEoVyEAy0vdfsl2XjT6wqZU5YE8qu9RAMaa8Ie4EPaD7mScQ7Y43zgpzC/KnkpZRAM9shNXqS7ghIY2tr3VuGikgzeXvzkJsw5TVs24l2fv/tK4TFeUqW7OKogde8ycM9Nk3TavX+mVd71bfzFjkrj3xgnPzAgRD/zy6/KNiBiWaIp5JfVo35VX0JdU58FZbR+4j9ZixECxv9o7/OfwdcDlmltUig==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=cAlryCAnvhgNvgpNd+u0VS2zd625GQEVcnkDdBxH1i7S85ksM1gtdCREsc7vJaStnS2b3iLWk8uyrxDVcwro2kZpXe+pyCcg/lCGTIFseOP7H0eR/YW20Szot0FDXvtLzXtTlRYcWGhpIYlBm1HcSr8BFx+DfhJiiiTmnkIlgwhm2x2j9q/unLFs/upml0T2IWoCzW6e8meDxmyvVxk1DTaWNEqZllwFdLgpk/DXhKRNURHOMK1VY5WcfsdpWqYSt/x04F8sxfafzrsXotjs2iLFt/oKPxzdSkGibodjn7Fc5l4dPJLbVLKHfqgQ+E8byz4s/bZWmCgutlBZSkxagQ==
  • Authentication-results-original: suse.com; dkim=none (message not signed) header.d=none;suse.com; dmarc=none action=none header.from=arm.com;
  • Cc: Xen-devel <xen-devel@xxxxxxxxxxxxxxxxxxxx>, nd <nd@xxxxxxx>, Stefano Stabellini <sstabellini@xxxxxxxxxx>, "committers@xxxxxxxxxxxxxx" <committers@xxxxxxxxxxxxxx>
  • Delivery-date: Fri, 31 Jul 2020 12:48:13 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Nodisclaimer: true
  • Original-authentication-results: suse.com; dkim=none (message not signed) header.d=none;suse.com; dmarc=none action=none header.from=arm.com;
  • Thread-index: AQHWZhCqcVqKiEQuVU6MZpfTy49dJakhj62AgAAV1gA=
  • Thread-topic: kernel-doc and xen.git

> On 31 Jul 2020, at 13:29, Jan Beulich <jbeulich@xxxxxxxx> 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.


> Jan



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.