Add cosmetic fixes to the API documentation

Some more comments are added to the source code, and the automatic API
documentation has been fixed and tested.