api: clarify return values in documentation
Merge pull request #871 from jonboulle/api-docs

api: clarify return values in documentation