in reply to RFC: Proofread POD for my main random module, please? (more)
- $color_hash magically appears in your random_color() example usage, and you give no indication of where it comes from (it's not a parameter to your example sub) or what it should look like (other than an arbitrary "hash(ref) of arrays")
- It takes multiple readings of the POD for me to guess that the data, keys, by keys, ... under the random() function refer to string values of the $color_key argument. Make sure you put quotes around each of the strings, but not around the undef.
- For tiny_rand(), you might want to mention "a coin flip", and give an example, like tiny_rand("HEADS", "TAILS");. The name is not helpful; maybe rename (or alias) to random_from_two()
- For instant_rand(), give an example, like instant_rand("HEADS", "TAILS", "EDGE", "EMBED IN CEILING");. Maybe rename (or alias) to random_from_list().