[Libvir] Documentation errors and shortcomings

[Daniel Veillard]

On Fri, Sep 07, 2007 at 06:52:21PM +0200, Tóth István wrote:
> Hello!
> 
> I am currently working on java bindings for libvirt, and in the process

  Interesting, so you're using JNI direct access to the C library, right ?
I looked at this a few weeks ago, but it was looking like accessing using the
remote access would have made the Java bindings more platform independant
but I had troubles with the RPC/TLS support, and didn't go very far. Maybe
a JNI based solution is good enough for most potential Java users.

> I have found a few bugs with the documentation, and also what I believe
> to be a design problem in the API.
> 
> 1. The parameterized C macros do not have their arguments listed either
> on libvirt.org, or in the docs folder in the distribution list, even
> though there is a a documentation block in the actual source file. I
> guess it's some kind of problem with the tool used for generating the docs.

  Yes that's a problem in the generator. Also it's rather hard for it 
to distinguish #define foo (bar) from #define foo2 (16+1) , the first one 
is a parametrized macro, the second is not, and we use both ATM.

> 2. The virConnectGetCapabilities function docs says that it returns an
> opaque pointer to a struct, when in fact it returns an XML string
> describing the capabilities.

  Right, fixed in CVS, thanks !

> 3. I have found no sanctioned way to actually get the data from
> DomainBlockStats and DomainInterfaceStats.
> The strucures are defined as _virDomainBlockStats and struct
> _virDomainInterfaceStats, and there is only an *Ptr type typedef-ed on
> them, as in the case of, say virConnectPtr, which IS really meant to be
> opaque.

  That's a generator problem because the stats structure were defined in a
slightly different way than usual.

> I believe that the fields of these structs ARE meant to be read by the
> applications linking the library,  and are not really meant to be
> opaque.
>
  yes

> I think the right way to fix this would be simply to typedef them as
> typedef struct _virDomainBlockStats virDomainBlockStats;
> typedef struct _virDomainInterfaceStats DomainInterfaceStats;
> 
> expose their fields in the documentation, and not call them opaque (
> i.e. treat them just like virSchedParameter)

 Yes except virDomainBlockStats and DomainInterfaceStats are the name
of the associated functions, I had to pick different names but this is
now fixed:

  http://libvirt.org/html/libvirt-libvirt.html#virDomainBlockStatsStruct

  thanks !

Daniel

-- 
Red Hat Virtualization group http://redhat.com/virtualization/
Daniel Veillard      | virtualization library  http://libvirt.org/
veillard at redhat.com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine  http://rpmfind.net/