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

Re: kernel-doc and xen.git

  • To: Stefano Stabellini <sstabellini@xxxxxxxxxx>
  • From: George Dunlap <George.Dunlap@xxxxxxxxxx>
  • Date: Thu, 30 Jul 2020 11:13:09 +0000
  • Accept-language: en-GB, en-US
  • Authentication-results: esa1.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none
  • Cc: "xen-devel@xxxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxxx>, Committers <committers@xxxxxxxxxxxxxx>, "Bertrand.Marquis@xxxxxxx" <Bertrand.Marquis@xxxxxxx>
  • Delivery-date: Thu, 30 Jul 2020 11:13:24 +0000
  • Ironport-sdr: HLXkWDxgOvLKURf//whfEZ1QG0TsypSbBRPGutWNghswsf+WA/18+OIq4445vyO2rafVZYTEcK BEoizpzip0vrBz6Y7YVNDpYTdZEJtvDMEg0G/PkKtOS40kx+y5Grm8BeOKX3rKdigammz+hS2l YDtBwRPbZxDAWlaQgTZyQ1UTpCPM1+lgUVk3mZEv2H0Bx9lBhxltVaehorPYeodHzq4X8dUtcr OAt/dZOl0y7j+6bVoelLfy4Upc+0v32PwgjKSfe+PVYF8M82BSVcFYk4IKr6s6btMqRfspkVWc YuE=
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Thread-index: AQHWZhCpvoHj9qYsqUS/BmcPWnpp8Kkf1yeA
  • Thread-topic: kernel-doc and xen.git

> On Jul 30, 2020, at 2:27 AM, Stefano Stabellini <sstabellini@xxxxxxxxxx> 
> 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.

`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




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