more doc comments reviewed
rest of the docsrings
fix example for constructor from random