documentation and fixed the random method order