Libid3tag documentation, again

I have started writing a little program that uses libid3tag to read id3 
tags, add a few tags, and write the result back to the mp3 file. This 
seemed trivial, but it took me about 2 days and tons of segfaults and 
weird behavior to come up with something that starts to go in the right 
direction. Google sent me to about 10 different websites during my quest 
for information, with each site giving a small piece of the puzzle. At 
many times I suspected id3tag to be full of bugs, but I soon realized 
that the 'bugs' were just due to the way I (mis)interpreted the functions.

If someone has the time for it, I would really suggest to write some 
documentation, and bundle it with the software. A few well-documented 
simple demo programs which read, modify, and write tags would already be 
incredibly useful.
It would also be nice if the id3tag.h file would be a bit more 
'verbose', i.e. if the function prototypes would use actual argument 
names which make sense, and a short description and caveats for each 
function.

It seems like libid3tag is not widely used, although it has a lot of 
potential. I think the lack of documentation is a major cause of this...

Alexander