On 7 November 2016 at 17:04, Paolo Bonzini <pbonz...@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? >> 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
