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

[Daniel P. Berrange]

On Thu, Nov 10, 2016 at 05:08:03AM -0500, Paolo Bonzini wrote:
> 
> 
> ----- Original Message -----
> > From: "Fam Zheng" <address@hidden>
> > To: "Stefan Hajnoczi" <address@hidden>
> > Cc: "John Snow" <address@hidden>, "Peter Maydell" <address@hidden>, "QEMU 
> > Developers"
> > <address@hidden>, "Stefan Hajnoczi" <address@hidden>, "Paolo Bonzini" 
> > <address@hidden>
> > 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/ :|