[libvirt] RFC version information in API docs

[Daniel P. Berrange]

On Mon, May 13, 2013 at 03:04:40PM +0200, Claudio Bley wrote:
> At Mon, 13 May 2013 13:39:53 +0100,
> Daniel P. Berrange wrote:
> > 
> > On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote:
> > > Hi.
> > > 
> > > Sometimes, it's a bit hard to determine when exactly a function, flag
> > > or macro appeared in libvirt, ie. whether it will be supported on my
> > > target machine having a specific version of libvirt or not.
> > > 
> > > So, I have created an enriched version of the API docs, using a XSL
> > > stylesheet enumerating the libvirt?-api.xml files of all libvirt
> > > releases.
> > > 
> > > For an example, you can have a look here:
> > > 
> > > http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState
> > > 
> > > Hovering over an enum value displays version information in a tooltip.
> > > 
> > > What do you think? Should this information be included by default in
> > > the API docs?
> > 
> > The version an API appeared is not always that useful - since you
> > typically need to know what version a hypervisor driver supported
> > it in.
> 
> Yeah, maybe it's a special use case, but when wrapping libvirt
> functions in Java, I'm interested in the exact version, e.g. to see
> what's still missing.

FWIW, rather than doing it manually I'd recommend that you create a
script which extracts a list of all APIs currently implemented by
the java bindings, and then match it against the list of APIs
exported in /usr/share/libvirt/api/libvirt-api.xml

That's how I validate that the Perl bindings has 100% coverage of
all current libvirt APIs:

  http://libvirt.org/git/?p=libvirt-perl.git;a=blob;f=t/030-api-coverage.t;hb=HEAD

> > Do you know about this page which shows the version matrix
> > for APIs + drivers:
> > 
> >   http://libvirt.org/hvsupport.html
> 
> Yes, but this list is just to overwhelming, I'm almost getting
> headaches when reading it... ;)
> 
> Having to switch back and forth between html/libvirt-libvirt.html and
> searching in this page is not exactly comfortable by any manner of
> means.
> 
> It's also a lot easier to answer "Which functions where introduced in
> version x.y.z?" querying the (enriched) libvirt-api.xml than looking
> it up in this matrix.
> 
> But, maybe interlinking these two pages would be sufficient.
> 
> On-line filtering by libvirt version and driver support would be even
> better. What do you think?

I think what would be best is to get the full set of driver support
version numbers into the API docs.

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|