Re: Discussion question: what is the best syntax for documenting a coderef parameter?
On Thu, Dec 09, 2010 at 06:16:45AM -0600, David Nicol wrote: On Wed, Dec 8, 2010 at 7:59 PM, Eric Wilhelm enoba...@gmail.com wrote: If you can, avoid the need to document I will pass a callback to your callback. --Eric Continuation-style programming requires that all the time. Which is why CPS.pm documents them thus: =head2 kforeach( \...@items, \body, $k ) CPS version of perl's foreach loop. Calls the body code once for each element in @items, until either the items are exhausted or the body invokes its $klast continuation, then invoke $k. $body-( $item, $knext, $klast ) $knext-() $klast-() $k-() =cut (see http://search.cpan.org/~pevans/CPS-0.10/lib/CPS.pm#kforeach(_...@items,_\body,_$k_) -- Paul LeoNerd Evans leon...@leonerd.org.uk ICQ# 4135350 | Registered Linux# 179460 http://www.leonerd.org.uk/ signature.asc Description: Digital signature
Re: Discussion question: what is the best syntax for documenting a coderef parameter?
On Wed, Dec 8, 2010 at 7:59 PM, Eric Wilhelm enoba...@gmail.com wrote: If you can, avoid the need to document I will pass a callback to your callback. --Eric Continuation-style programming requires that all the time.
Re: Discussion question: what is the best syntax for documenting a coderef parameter?
# from David Nicol
# on Tuesday 07 December 2010 14:12:
on_connect = $cb-($handle, $host, $port, $retry-())
This is confusing. If you're going to illustrate how it is called, take
it out of the context of how it is declared.
on_connect = sub {
my ($handle, $host, $port, $retry) = @;
...
}
As for illustrating I will pass you a subref here, I would say:
$on_connect-($handle, $host, $port, sub {...})
or:
$on_connect-($handle, $host, $port, \retry);
or even just:
$on_connect-($handle, $host, $port, $retry_hook);
But in this particular case, something like a connection object with
handle(), host(), and port() methods seems more appropriate, which then
would allow one to do something like '$c-retry until $c-connected'
(assuming appropriate error handling semantics.)
Alternatively, perhaps the last parameter should be an object where one
would say 'return $knob-retry' and this would result in the on_connect
hook being called again after the next connection was established.
If you can, avoid the need to document I will pass a callback to your
callback.
--Eric
--
Entia non sunt multiplicanda praeter necessitatem.
--Occam's Razor
---
http://scratchcomputing.com
---
Discussion question: what is the best syntax for documenting a coderef parameter?
The pod for AnyEvent::Handle contains SNIP on_connect = $cb-($handle, $host, $port, $retry-()) This callback is called when a connection has been successfully established. The peer's numeric host and port (the socket peername) are passed as parameters, together with a retry callback. SNIP Is C$retry-() the best way to represent that a coderef is required there? It's clear, but I would have written it C\retry. And I would have written something confusing. I think Marc Lehmann has done it the right way.
Re: Discussion question: what is the best syntax for documenting a coderef parameter?
I would have just said $retry and then gone on to document each of the parameters including what type they should be... and of course a croak XXX unless ref($retry) eq 'CODE' before doing any real work. On Tue, Dec 7, 2010 at 2:12 PM, David Nicol davidni...@gmail.com wrote: The pod for AnyEvent::Handle contains SNIP on_connect = $cb-($handle, $host, $port, $retry-()) This callback is called when a connection has been successfully established. The peer's numeric host and port (the socket peername) are passed as parameters, together with a retry callback. SNIP Is C$retry-() the best way to represent that a coderef is required there? It's clear, but I would have written it C\retry. And I would have written something confusing. I think Marc Lehmann has done it the right way. -- Check out my LEGO blog at http://www.brickpile.com/ View my photos at http://flickr.com/photos/billward/ Follow me at http://twitter.com/williamward
Re: Discussion question: what is the best syntax for documenting a coderef parameter?
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
Re: Discussion question: what is the best syntax for documenting a coderef parameter?
On 10-12-07 06:00 PM, Bruce Gray wrote: 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. I use the \ even where it's not valid Perl: =head1 USAGE ( \iterator, \reset ) = create_iterator( $start, $upper_bound, $step ); =cut -- Just my 0.0002 million dollars worth, Shawn Confusion is the first step of understanding. Programming is as much about organization and communication as it is about coding. The secret to great software: Fail early often. Eliminate software piracy: use only FLOSS.
