The story of a good API and a bad documentation

I said before that for my current job I’m using libxml2, as it has a nicer interface than the ATL interface to MSXML, and it is licensed under a quite permissive license, which allows me to use it for proprietary software (long story).

Unfortunately, its documentation leaves a lot to desire. The API documentation really only provides a very shallow description of the parameters, and the example only cover some quite simple cases, which happens to barely cover my use of libxml2.

For instance, I’m unable to find how I’m supposed to validate a given XML “document” (loaded from a string) against a DTD that is not explicitly written with the document (this is for copy-paste of data, for what it’s worth). Right now I’m just doing the validation through assertions and exceptions, but I’d find it better for me if I could leave the validation directly to libxml2.

You know my motto “delegate everything to other libraries”, no? 🙂 The less tasks I have to code specifically for, the less code I can make mistakes on! Of course this expects that the libraries behave just like I want them to.

So, as the documentation is lacking, I’ll try to come up with some improvements to it. I’ll probably post a few more blogs in the next weeks about it, trying to cover for instance this particular need of mine, and others. I should also probably contact upstream about it.