[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format questio
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question)
Mon, 7 Nov 2016 17:20:43 +0000
On 7 November 2016 at 17:04, Paolo Bonzini <address@hidden> wrote:
> On 07/11/2016 16:03, Peter Maydell wrote:
>> The overall organisation structure needs some thought --
>> I think we should at least separate into user/ for user
>> docs and dev/ for internals docs
> Yes, the complicated part is establishing a structure for the
> documentation (this should be done collaboratively on the wiki, I think).
> Ultimately we should have three manuals: user, developer and hardware
> specifications, but docs/ is currently a hodge-podge of the first two.
User and developer, sure, but what's "hardware specifications" for?
>> 3) the most awkward part of kernel-doc syntax is that it bakes
>> in the kernel's style choice of always using "struct foo"
>> for types -- I don't think there's any way to document
>> 'MemoryRegion' and 'AddressSpace' without the 'struct'
>> coming out in the documentation output.
> I actually like having struct in the name, even if the code then
> doesn't use it.
I think it would be good to at least be able to have '&MemoryRegion'
in a doc comment hyperlink to the documentation of the type --
currently that only works for '&struct MemoryRegion'.
Also it seems a bit odd for our coding style and documentation
style to be divergent, since it suggests to new developers
that they should be using 'struct' in their code.
Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question), Emilio G. Cota, 2016/11/08