Re: [Libvir] Documentation errors and shortcomings
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
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.
Sounds like its a bug - will let Daniel debug that one.
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.
Yes, that's a bug in the docs from previous iteration of the patches for
that API. Will remove it.
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.
Well the struct definition is in the header file - you don't need a typedef
to be able to access the fields.
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)
Yes, anything you see in libvirt.h is fair game for applications to use.
Private stuff is simply not installed into /usr/include
I think the right way to fix this would be simply to typedef them as
typedef struct _virDomainBlockStats virDomainBlockStats;
typedef struct _virDomainInterfaceStats DomainInterfaceStats;
For the sake of consistency with other structs, yes we should add these
typedefs - they're not required for sake of accessing the fields in the
struct though.
Dan.
--
|=- Red Hat, Engineering, Emerging Technologies, Boston. +1 978 392 2496 -=|
|=- Perl modules: http://search.cpan.org/~danberr/ -=|
|=- Projects: http://freshmeat.net/~danielpb/ -=|
|=- GnuPG: 7D3B9505 F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 -=|