update docs for new methods and behavior