[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: Tue, 21 May 2019 19:14:00 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1

On 21/05/19 17:27, Peter Maydell wrote:
>> Anyway.  What's so special about QEMU that justifies coming up with our
>> own doc syntax?  Other than "we made a hash of it, and cleaning it up
>> would be work".
> The major problem as far as kernel-doc is concerned is that
> it somewhat bakes in the kernel's style choice that the
> 'struct' keyword is not hidden behind typedefs, and so it
> gets a bit confused by QEMU's "use typedefs for struct types"
> style. The rest, as you say, is just a matter of fixing up
> our syntax errors.

Exactly, "QEMU's syntax" is supposed to be actually gtkdoc, or inspired
by it, because of the similar typedef conventions.  The basic components

- the head of the doc comment is either a CamelCase type or a function
name followed by parentheses

- @ introduces parameters, e.g. @path

- % introduces types, e.g. %DeviceState

- () terminate functions, e.g. memory_region_init()

- # introduces other C symbols, e.g. #NULL

and they map very well to what kerneldoc tries to parse, IIRC it only
requires some changes to the regular expression at the top of the file.


reply via email to

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