updating docs to be in-line with the latest API