Tweak public API argument ordering. Improve documentation