[Top][All Lists]

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

Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation

From: Paolo Bonzini
Subject: Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation
Date: Fri, 24 May 2019 22:02:40 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1

On 24/05/19 21:08, Eduardo Habkost wrote:
> On Fri, May 24, 2019 at 08:34:23PM +0200, Paolo Bonzini wrote:
>> On 23/05/19 14:20, John Snow wrote:
>>> OK, if that's where we're at! I just saw the RFC from Peter Maydell and
>>> assumed we were a little further along the decision making process, but
>>> maybe not. I'll stay tuned.
>> For the decision making, yes; I think there's consensus to use
>> kerneldoc.  For the "debugging and seeing if anything has changed in 2.5
>> years", no.
>> Testing the patch that Eduardo posted will help Gabriel, Eduardo and
>> everyone else decide whether to patch kerneldoc or rather change the API
>> doc comments style.  (Personally I am in favor of patching; the
>> different coding conventions make using vanilla kerneldoc awkward, and
>> there are several thousands of lines of existing doc comments which
>> would require a transition.)
> I'd prefer to fix our doc comments instead of patching kerneldoc,
> whenever possible.  We don't even have a consistent doc comment
> style in QEMU.

I think we *mostly* do, at least as far as the @/#/% sigils are
concerned.  In particular, only "#" separates the QEMU doc comment style
from the kernel and it has 200+ instances vs. 6 for the kernel's
'&struct foo' (all in accel/tcg/translate-all.c), so it's clear that our
standard is different from the kernel in this respect.

The rest of the patch is to handle typedefed structs, which again is
more or less a necessity.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]