On Thu, Nov 10, 2016 at 05:08:03AM -0500, Paolo Bonzini wrote: > > > ----- Original Message ----- > > From: "Fam Zheng" <f...@redhat.com> > > To: "Stefan Hajnoczi" <stefa...@gmail.com> > > Cc: "John Snow" <js...@redhat.com>, "Peter Maydell" > > <peter.mayd...@linaro.org>, "QEMU Developers" > > <qemu-devel@nongnu.org>, "Stefan Hajnoczi" <stefa...@redhat.com>, "Paolo > > Bonzini" <pbonz...@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/ :|
