Documentation errors and shortcomings

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

--
Libvir-list mailing list
Libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list

[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]