On Dec 7, 2010, at 4:12 PM, David Nicol wrote:
--snip--
Is C<$retry->()> the best way to represent that a coderef is
required there?
In general, I think the C<$retry->()> style is sub-optimal, because I
favor cut-and-pasteable code samples.
If I was documenting an API with only one of two subrefs, I would say
something like C<\&retry_coderef>, then list each of the coderef's
parameters as =item entries below it.
(I renamed the param from retry to retry_coderef to give an extra clue
to the reader, since & is a much rarer sigil than $ or @.)
However, the AnyEvent::Handle API uses many coderefs, including
several nested 2 deep, like the on_connect example you mentioned.
In such a case, the C<$retry->()> style is quite helpful.
It may take a new user a few extra seconds to understand, but that
initial cost pays off over the rest of the document.
--
Hope this helps,
Bruce Gray
