DOCS: Review of all documentation and make sure it is up to date

It would be good to go through the code and make sure the docs are up to date. While undertaking this review we should: 1. check the docstrings to see that they are well formatted and are clear 2. check the docstrings match the function interfaces 3. check if the docs/ are missing any existing documentation in the code 4. see if we can make overall improvements