Full pass at inline API Docs

This is mostly just documentation, with one or two bits of cleanup. Thought I'd PR it so people can see inline docs are considered basically done for the API and so further changes to the API need to update the docs as well :)

closes #2622, ref #2125