added API documentation
minor changes to public API