Re: [libvirt] RFC version information in API docs

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.

> 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?