I updated the docs for random(). Let me know if you think I should tweak it further, or understand it differently.
I think most users will see it my way.
humbly,
Paul Badger
Thank you for clarifying and explaining the various cases. I edited the page, trying to preserve your explanations while making them a bit more concise and "reference-like". See what you think, and feel free to change it again.