Re: RFC: Proofread POD for my main random module, please? (more)

[hippo]

In your synopsis you have this line:

my $random_thing = random($hash_of_arrays, $list, $options);

but in reading the source it appears that the second argument is expected to be a scalar, not a list. That's confusing.

Also you say several times, "When XXX is selected" but give no clue as to what "selected" means in this context. Again, it is only by reading the source that we can see you mean "passed as a literal value as the second argument to random()".

I think it would help a great deal if in your snippet listing the example random_color() sub you were actually to specify values for the three variables instead of leaving us all to wonder what they might be (or even what form they should take). eg.

  my $key = 'foo';
  my $additions = 'elephant';
  my $color_hash = { a => [qw/ I do not know /], b => [qw/ what should
+ go here /] };
  my $rv = random_color ($key, $additions);

  sub random_color {
    my ($color_key, $color_additions) = @_;
    random($color_hash, $color_key, { caller => 'random_color', additi
+ons => $color_additions});
  }

Finally, I don't see why instant_rand() is so named. Why not list_item_rand()?

HTH.