On 04/19/2017 08:27 AM, Stefan Hajnoczi wrote:

>>
>> I know we haven't done a good job in the past, but should we start
>> trying to do better at documenting callback constraints of new things
>> added in this header?
> 
> .bdrv_measure() is a 1:1 pass-through of the public bdrv_measure()
> function.  All the public function does is to dereference
> drv->bdrv_measure.
> 
> I think that's why many of the other callbacks also have no
> documentation - they inherit semantics from the public function.  We
> don't need to duplicate the doc comments.

Sometimes, though, there are slightly different semantics (for example,
we guarantee that the parameters to the driver code have already been
validated against image size, properly sliced-and-diced to match block
limits, and so on), so that the drivers don't have to do as much work.
Documenting these contract guarantees would be useful.

But as I said, it's not something we have to solve in this series.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org