document a lot and fix behaviour of the random generators