From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([2001:4830:134:3::10]:55185)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <pbonzini@redhat.com>) id 1c4mHD-0004yD-Cg
	for qemu-devel@nongnu.org; Thu, 10 Nov 2016 05:08:15 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <pbonzini@redhat.com>) id 1c4mH8-0007PO-Uw
	for qemu-devel@nongnu.org; Thu, 10 Nov 2016 05:08:11 -0500
Received: from mx4-phx2.redhat.com ([209.132.183.25]:36107)
	by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)
	(Exim 4.71) (envelope-from <pbonzini@redhat.com>) id 1c4mH8-0007PA-Mz
	for qemu-devel@nongnu.org; Thu, 10 Nov 2016 05:08:06 -0500
Date: Thu, 10 Nov 2016 05:08:03 -0500 (EST)
From: Paolo Bonzini <pbonzini@redhat.com>
Message-ID: <1281860074.11905116.1478772483799.JavaMail.zimbra@redhat.com>
In-Reply-To: <20161110033914.GE8422@lemon>
References: <CAFEAcA8ff=cEz-MrWFAFm2=8zWkJy=cbRpErQEBkwigaoVm67g@mail.gmail.com>
	<20161107133045.GM5036@stefanha-x1.localdomain>
	<bf3151dc-1236-c738-c473-d427996713e4@redhat.com>
	<20161108162044.GE11274@stefanha-x1.localdomain>
	<e0354262-92dc-de5b-b3b1-94e4eb462396@redhat.com>
	<20161109113226.GD4682@stefanha-x1.localdomain>
	<20161110033914.GE8422@lemon>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format
 question)
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel/>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: Fam Zheng <famz@redhat.com>
Cc: Stefan Hajnoczi <stefanha@gmail.com>, John Snow <jsnow@redhat.com>, Peter Maydell <peter.maydell@linaro.org>, QEMU Developers <qemu-devel@nongnu.org>, Stefan Hajnoczi <stefanha@redhat.com>



----- Original Message -----
> From: "Fam Zheng" <famz@redhat.com>
> To: "Stefan Hajnoczi" <stefanha@gmail.com>
> Cc: "John Snow" <jsnow@redhat.com>, "Peter Maydell" <peter.maydell@linaro.org>, "QEMU Developers"
> <qemu-devel@nongnu.org>, "Stefan Hajnoczi" <stefanha@redhat.com>, "Paolo Bonzini" <pbonzini@redhat.com>
> 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).

Paolo