Doc - update doc about the state of the API
Doc - merge comments with docstring