Documentation for Cyrus::IMAP::Admin and friends

[Binarus]

Dear all,

as described in my previous messages, I recently had a hard time relocating (i.e. moving) mailboxes and the public namespace from 2.4.16 to a new server running 2.5.10. I would have happily written a Perl script which surely had solved much of my problems, but I couldn't do that due to the lack of documentation for the respective Perl modules.

This is best explained by example:

I have found a Perl script on the 'net which looks trustworthy at the first sight and which contains (among others) the following lines of code:

use Cyrus::IMAP::Admin;

# Connect to Cyrus
$imap = Cyrus::IMAP::Admin->new("my_server") || die "Unable to connect to my_server";

$imap->authenticate(-user => "foo", 
		-mechanism => "LOGIN",
		-password => "password",
		);

I wanted to understand exactly what the script does and thus tried to find Cyrus::IMAP::Admin's documentation. So I issued

man Cyrus::IMAP::Admin

and found that some methods are documented, but not the authenticate() method which is needed first and one of the most important ones. However, the man page states (in the section about the "new()" method):

"Instantiates a cyradm object.  This is in fact an Cyrus::IMAP object with a few additional methods, so all Cyrus::IMAP methods are available if needed.  (In particular, you will always want to use the "authenticate" method.)"

This tricked me into believing that the "authenticate" method would be part of Cyrus::IMAP and would be explained in that module's documentation, so I issued

man Cyrus::IMAP

Well, this man page "documents" the method by exactly one line (identically in two places):

$client->authenticate;

It does not explain anything about it; notably, it does not mention any parameters. But from the example script mentioned above, I knew that there was more to it. So I read the rest of that man page and found:

"The Cyrus::IMAP module provides an interface to the Cyrus imclient library."

So I installed the development files for Cyrus imapd and issued

man imclient

Now, finally, this is a man page a C programmer probably can live with. But when looking more thoroughly into it, I saw that there is no "password" parameter to the authenticate() function although the Perl module's authenticate() method has one:

int imclient_authenticate (struct imclient *imclient, struct sasl_client **availmech, const char *service, const char *user, int protallowed);

Plus, I could not find any hints regarding the relationship between the parameters of the C functions and those of the Perl module methods.

I then headed over to cyrusimap.org and tried to find documentation for the Perl modules. Surprisingly, I couldn't. Not a single word. They don't seem to exist. The tools and helper programs are documented, but the Perl modules are not even mentioned.

The same applies to CPAN: The modules cannot be found there.

To make a long story short:

Where can I find reasonable (in the sense: may be short and bad, but must be *complete*) documentation for Cyrus::IMAP::Admin and Cyrus::IMAP so that I can write my own helper scripts in the future? Do I really have to unpack Cyrus imapd's sources and read the module source code to get some ideas?

Thank you very much in advance,

Binarus