add some documentation to the random() functions