From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:53241) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3o4A-0002LB-Df for qemu-devel@nongnu.org; Mon, 07 Nov 2016 12:50:43 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3o47-0006GB-BK for qemu-devel@nongnu.org; Mon, 07 Nov 2016 12:50:42 -0500 Received: from mx1.redhat.com ([209.132.183.28]:42696) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c3o47-0006G2-5x for qemu-devel@nongnu.org; Mon, 07 Nov 2016 12:50:39 -0500 References: From: Paolo Bonzini Message-ID: Date: Mon, 7 Nov 2016 18:50:34 +0100 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Peter Maydell Cc: QEMU Developers , Stefan Hajnoczi , "Daniel P. Berrange" On 07/11/2016 18:20, Peter Maydell wrote: > On 7 November 2016 at 17:04, Paolo Bonzini 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 >=20 >> Yes, the complicated part is establishing a structure for the >> documentation (this should be done collaboratively on the wiki, I thin= k). >> >> Ultimately we should have three manuals: user, developer and hardware >> specifications, but docs/ is currently a hodge-podge of the first two. >=20 > 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. >=20 > 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. >=20 > thanks > -- PMM >=20