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