Per our documentation convention, we should only document public facing functions in one place.
This helps prevents cases like this where we have multiple contradictory copies of a function's documentation.
Let's do one big sweep of our public API:
- transfer any useful info from comment blocks into the .rst doc page
- remove those comment blocks