[Libvir] Documentation errors and shortcomings

Toth Istvan stoty at 3g.co.hu
Fri Sep 7 16:50:23 UTC 2007


Hello!

I am currently working on java bindings for libvirt, and in the process
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.

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.

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.

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. (or if they are, they should have some functions/macros that you
can access their contents with)

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)

best regards

István





More information about the libvir-list mailing list