Mailing List Archive: Catalyst: Dev

visit() and go() doc patch

Index | Next | Previous | View Threaded

emazep at gmail

Dec 28, 2011, 9:11 PM

Post #1 of 3 (411 views)
Permalink

visit() and go() doc patch

Though formally correct, the visit() and go() documented signatures can
be misleading, since they say (e.g. for visit):

$c->visit( $action [, \@captures, \@arguments ] )
...

while visit() can be called also with a single arrayref argument, with
the following /unexpected/ semantics:

$c->visit( $action, \@arguments );

This is a small doc patch to clarify that (well, unless there is some
reason to keep it undocumented - but this way the user can easily be
misled).

It should also close the #59601 RT ticket:
https://rt.cpan.org/Public/Bug/Display.html?id=59601

Cheers
-Emanuele

Attachments:

visit-go-doc.patch (1.00 KB)

diment at gmail

Dec 28, 2011, 9:35 PM

Post #2 of 3 (398 views)
Permalink

Re: visit() and go() doc patch [In reply to]

On 29/12/2011, at 4:11 PM, Emanuele Zeppieri wrote:

> Though formally correct, the visit() and go() documented signatures can be misleading, since they say (e.g. for visit):
>
> $c->visit( $action [, \@captures, \@arguments ] )
> ...
>
> while visit() can be called also with a single arrayref argument, with the following /unexpected/ semantics:
>
> $c->visit( $action, \@arguments );
>
> This is a small doc patch to clarify that (well, unless there is some reason to keep it undocumented - but this way the user can easily be misled).
>
> It should also close the #59601 RT ticket:
> https://rt.cpan.org/Public/Bug/Display.html?id=59601

Thanks, applied in git commit hash: 8431b9cc52d1
_______________________________________________
Catalyst-dev mailing list
Catalyst-dev [at] lists
http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev

pagaltzis at gmx

Dec 29, 2011, 4:17 PM

Post #3 of 3 (401 views)
Permalink

Re: visit() and go() doc patch [In reply to]

* Emanuele Zeppieri <emazep [at] gmail> [2011-12-29 06:15]:
> +=head2 $c->visit( $action [, \@arguments ] )
> +
> =head2 $c->visit( $action [, \@captures, \@arguments ] )
>
> +=head2 $c->visit( $class, $method, [, \@arguments ] )
> +
> =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )

If you are going to expand one case, why not expand the no-ref case
also, and drop the confusing/misleading [ ] metasyntax entirely?

+=head2 $c->visit( $action )
+
+=head2 $c->visit( $action, \@arguments )
+
=head2 $c->visit( $action, \@captures, \@arguments )

+=head2 $c->visit( $class, $method )
+
+=head2 $c->visit( $class, $method, \@arguments )
+
=head2 $c->visit( $class, $method, \@captures, \@arguments )

Just a thought. It does get a bit long that way, so I’m not sure which
evil I prefer.

Regards,
--
Aristotle Pagaltzis // <http://plasmasturm.org/>

_______________________________________________
Catalyst-dev mailing list
Catalyst-dev [at] lists
http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads