[Libguestfs] [PATCH 02/12] generator: Convert relevant arguments from Device to Mountable

[Matthew Booth]

On Fri, 2013-02-08 at 11:42 +0000, Richard W.M. Jones wrote:
> On Thu, Feb 07, 2013 at 03:57:48PM +0000, Matthew Booth wrote:
> > This change updates the api style of all apis which should take Mountable
> > descriptions rather than block devices. It also updates the documentation
> > accordingly, but doesn't implement any functional changes.
> 
> [...]
> > +=head2 MOUNTABLES
> 
> I don't think we should document Mountable at all, at least not at
> this stage.  The reason is twofold: (a) People shouldn't be trying to
> construct these strings, except for device/partition names which is
> existing practice.  More importantly, (b) we may want to change or
> replace the btrfsvol strings in future if we decide that we got it
> wrong (or if btrfs changes something), and we can only do that if we
> can be sure that people aren't trying to construct them from scratch.
> 
> So I would only ack this patch if we removed two things: the
> 'btrfsvol:' example that appears in one of the function descriptions,
> and the whole MOUNTABLES section in the documentation.

I don't think we should remove it from the documentation. If we include
this patch it will form part of the API, so it should be documented. The
format is also designed to be extensible, so changing it in the future
isn't a problem. btrfsvol need never be removed because it serves an
actual need. If we discover a better way to do this in the future, or a
more general way that solves many needs, we can add new mountables type
without breaking the api.

Matt