added some documentation for the current API