From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:56738) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c4GFq-0002lp-8g for qemu-devel@nongnu.org; Tue, 08 Nov 2016 18:56:39 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c4GFm-000545-DD for qemu-devel@nongnu.org; Tue, 08 Nov 2016 18:56:38 -0500 Received: from mail-wm0-x22a.google.com ([2a00:1450:400c:c09::22a]:34537) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c4GFm-00053v-59 for qemu-devel@nongnu.org; Tue, 08 Nov 2016 18:56:34 -0500 Received: by mail-wm0-x22a.google.com with SMTP id u144so40506002wmu.1 for ; Tue, 08 Nov 2016 15:56:33 -0800 (PST) Sender: Paolo Bonzini References: <20161107133045.GM5036@stefanha-x1.localdomain> From: Paolo Bonzini Message-ID: <9575bf1d-b097-1503-a1c8-48f3e1882e80@redhat.com> Date: Wed, 9 Nov 2016 00:56:30 +0100 MIME-Version: 1.0 In-Reply-To: <20161107133045.GM5036@stefanha-x1.localdomain> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit 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: Stefan Hajnoczi , Peter Maydell Cc: QEMU Developers , Stefan Hajnoczi On 07/11/2016 14:30, Stefan Hajnoczi wrote: > On Sat, Nov 05, 2016 at 06:42:23PM +0000, Peter Maydell wrote: >> In particular I think we could: >> * set up a framework for our in-tree docs/ which gives us a >> place to put new docs (both for-users and for-developers) -- >> I think having someplace to put things will reduce the barrier >> to people writing useful new docs >> * gradually convert the existing docs to rst >> * use the sphinx extension features to pull in the doc-comments >> we have been fairly consistently writing over the last few years >> (for instance a converted version of docs/memory.txt could pull >> in doc comments from memory.h; or we can just write simple >> wrapper files like a "Bitmap operations" document that >> displays the doc comments from bitops.h) > > You are suggesting Sphinx for two different purposes: > > 1. Formatting docs/ in HTML, PDF, etc. > > 2. API documentation from doc comments. > > It's a good idea for #1 since we can then publish automated builds of > the docs. They will be easy to view and link to in a web browser. > > I'm not a fan of #2. QEMU is not a C library that people develop > against and our APIs are not stable. There is no incentive for pretty > doc comments. It might be cool to set it up once but things will > deterioate again quickly because we don't actually need external API > docs. I don't think pretty doc comments matter, but accurate doc comments do. If we cannot have accurate doc comments, we might not have them at all, but this is actually not the case. There are some areas where we actually go to great(er) lengths to have up-to-date documentation and up-to-date doc comments, and it's a pity to only provide half of the information in an easily consumable format. It doesn't really have to be perfect, but it's a nice thing to have. I'm not entirely sure that it's interesting to format bitops.h's doc comments, but for memory.h or aio.h I'm pretty sure it's worth it. Paolo