qemu-devel
[Top][All Lists]
Advanced

[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


From: Peter Maydell
Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question)
Date: 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.

thanks
-- PMM



reply via email to

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