On Wed, Apr 19, 2017 at 08:32:06AM -0500, Eric Blake wrote:
> 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.

Fair enough.

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

Okay.