From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:56688) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3kBZ-0008Ca-L8 for qemu-devel@nongnu.org; Mon, 07 Nov 2016 08:42:06 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3kBV-0002BZ-PP for qemu-devel@nongnu.org; Mon, 07 Nov 2016 08:42:05 -0500 Received: from mx1.redhat.com ([209.132.183.28]:39694) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c3kBV-0002B9-Ji for qemu-devel@nongnu.org; Mon, 07 Nov 2016 08:42:01 -0500 Date: Mon, 7 Nov 2016 13:41:55 +0000 From: "Daniel P. Berrange" Message-ID: <20161107134155.GK6316@redhat.com> Reply-To: "Daniel P. Berrange" References: <20161107133045.GM5036@stefanha-x1.localdomain> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <20161107133045.GM5036@stefanha-x1.localdomain> 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 Cc: Peter Maydell , Paolo Bonzini , QEMU Developers , Stefan Hajnoczi On Mon, Nov 07, 2016 at 01:30:45PM +0000, 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. For shared internal infrastructure code I very much disagree. If I'm writing something (like a new block driver), I'm relying on a bunch of existing code that I'm calling. Some of the methods I'm consuming may be in a library like GLib, other methods may be QEMU internal infrastructure (like util/*, io/*, cryto/*). Regardless of whether those methods are internal or from a library, the API docs are very important / valuable in ensuring I'm understanding the required usage contract of the method. The lack of API docs for the QEMU block layer was a major cause of pain for me when writing the LUKS driver. Regards, Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://entangle-photo.org -o- http://search.cpan.org/~danberr/ :|