Merge pull request #508 from jonboulle/master

Various cleanup to API documentation