[Libvir] Documentation errors and shortcomings

[Daniel P. Berrange]

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