http://qs321.pair.com?node_id=11119931


in reply to Re^2: Coming up with good examples in POD
in thread Coming up with good examples in POD

"I am fairly happy with it as it is now."

If your changes cover all potential use cases, that's good.

As the original question was focused on POD, I thought I'd just point out a couple of discrepancies.

You wrote "... the parameter $split can be ignored for alpha ..."; but, your POD has "C<split_sort> has four required parameters.". As it stands, users won't know what fourth parameter to use for alpha types; an additional example wouldn't hurt.

Also in that paragraph, the last two sentences are back-to-front: it should be, 3rd is 'type' and 4th is 'expr' (cf. "split_sort($a, $b, 'type', 'expr');" which immediately follows that paragraph).

&split_sort contains no implicit return so the return value will be the result of the last expression evaluated; that will be either a <=> or cmp expression, both of which return one of -1, 0 or 1 (see "perlop: Equality Operators"). The sort itself returns a list which you have correctly assigned to an array. The POD immediately afterwards indicates an ARRAYREF is returned: "returns [ ... ]".

How you deal with that one is up to you. I'd probably show split_sort(...) and indicate it returns the same as <=> and cmp, making it useful for sort. Then show usage with sort much as you currently have. Then show that it returns a LIST instead of an ARRAYREF; just changing [...] to (...) should suffice.

For your 'left' and 'right' examples, I'd mix it up a bit to give a clearer indication of how the sorting process works. For instance, here's a couple of arbitrary examples.

IN: 10:ab 21:bb 2:bb 21:bb 2:b OUT: 2:b 2:bb 10:ab 21:ab 21:bb IN: bb:10 b:1 ab:10 ab:2 bb:9 OUT: ab:2 ab:10 b:1 bb:9 bb:10

Including the '2' and '02' in your original examples was I good idea. You may want to point out that they'll keep their original order; by which, I mean:

$ perl -E 'say for sort { $a <=> $b } qw{020 2 02 20}' 2 02 020 20 $ perl -E 'say for sort { $a <=> $b } qw{20 02 2 020}' 02 2 20 020

Finally, as I've not seen the the actual module code, I'm guessing a bit here. The NAME should indicate what the module provides or implements, not what it returns; technically, it should just return a TRUE value — it's common for the last line of code, excluding POD, to be just 1;. Also, it's useful to know whether functions are exported by default or not.

— Ken