[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
are:
- 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.
Paolo
- [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/20
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, John Snow, 2019/05/20
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Daniel P . Berrangé, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Peter Maydell, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Markus Armbruster, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Daniel P . Berrangé, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Peter Maydell, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation,
Paolo Bonzini <=
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, John Snow, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/22
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, John Snow, 2019/05/23
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/24
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/24
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/24
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Eduardo Habkost, 2019/05/21
- Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Paolo Bonzini, 2019/05/21
Re: [Qemu-devel] Introducing GSoC project: API Documentation Generation, Peter Maydell, 2019/05/21