Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question)

["Daniel P. Berrange" <berrange@redhat.com>]

On Thu, Nov 10, 2016 at 05:08:03AM -0500, Paolo Bonzini wrote:
> 
> 
> ----- 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).

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/ :|