From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36196) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c4n1G-0007xe-JD for qemu-devel@nongnu.org; Thu, 10 Nov 2016 05:55:47 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c4n1D-0004FM-HE for qemu-devel@nongnu.org; Thu, 10 Nov 2016 05:55:46 -0500 Received: from mx1.redhat.com ([209.132.183.28]:53136) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c4n1D-0004F6-BM for qemu-devel@nongnu.org; Thu, 10 Nov 2016 05:55:43 -0500 Date: Thu, 10 Nov 2016 10:55:36 +0000 From: "Daniel P. Berrange" Message-ID: <20161110105536.GB31855@redhat.com> Reply-To: "Daniel P. Berrange" References: <20161107133045.GM5036@stefanha-x1.localdomain> <20161108162044.GE11274@stefanha-x1.localdomain> <20161109113226.GD4682@stefanha-x1.localdomain> <20161110033914.GE8422@lemon> <1281860074.11905116.1478772483799.JavaMail.zimbra@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <1281860074.11905116.1478772483799.JavaMail.zimbra@redhat.com> 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: Paolo Bonzini Cc: Fam Zheng , Stefan Hajnoczi , John Snow , QEMU Developers , Stefan Hajnoczi , Peter Maydell On Thu, Nov 10, 2016 at 05:08:03AM -0500, Paolo Bonzini wrote: > > > ----- Original Message ----- > > From: "Fam Zheng" > > To: "Stefan Hajnoczi" > > Cc: "John Snow" , "Peter Maydell" , "QEMU Developers" > > , "Stefan Hajnoczi" , "Paolo Bonzini" > > Sent: Thursday, November 10, 2016 4:39:14 AM > > Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) > > > > On Wed, 11/09 11:32, Stefan Hajnoczi wrote: > > > No doc comments -> error. > > > > I'm not sure that is a good idea. For example all .bdrv_co_flush_to_disk > > implementations have the same semantics and signature, requiring doc comments > > everywhere might be too much. > > The check would be only on specific files. However, I find it hard to > implement it if we place doc comments for types in headers and those for > functions in .c files (with automatically generated docs, most of the > advantages of doc comments in headers go away). Another reason for using .h file for all API docs - we have APIs declared for crypto impls in .h files, but there are 3 separate implementation files chosen between at build time, so no single .c file is "right" for holding the docs. 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/ :|