Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question)

[Paolo Bonzini <pbonzini@redhat.com>]

On 07/11/2016 18:20, Peter Maydell wrote:
> On 7 November 2016 at 17:04, Paolo Bonzini <pbonzini@redhat.com> 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?

It's docs/specs.

>>> 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'.

Oh, got it now.  Yes, that would be more than just "nice to have".  What
do you think about requiring &struct in the doc comment, but then
omitting the "struct" in the generated documentation?

In any case, kerneldoc doesn't seem too rough to customize and (apart
from the latest flurry) it is touched very little in Linux.  And it also
includes other formats that Linux doesn't quite use, so perhaps Jon
Corbet would accept a patch for Texinfo.  If our changes were limited to
a bunch of changes $type_* at the top, it would be pretty good already.

Paolo

> 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
>