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

[Paolo Bonzini]

----- 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).

Paolo