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