documented randomness and added an example. fixes #45