Re: Function signatures in POD-headlines/pseudo code! Is there a standard?

Maybe there is some insight which can be taken from perl6-meditations/notations?

Signatures in Perl 6 are so expressive that I just use them unchanged in the documentation.

But I think using them in the documentation of a Perl 5 module is rather confusing. Simple things like optional parameters (indicated by a question mark after the parameter) might work, but there are things that have quiet a mismatch (for example you get checking and binding semantics similar to Perl 5 prototypes, but contrary to prototypes the parsing is not affected).

To return to your original question I'd suggest you take a look at the split documentation. It simply lists all possible call syntaxes, using upper case letters for metasyntactic elements.

I find that much easier to understand than [...] for optional arguments, which I too find confusing. They are a standard in unix man pages, but in Perl I don't like them, for the same reasons as you do.

Perl 6 - links to (nearly) everything that is Perl 6.

Comment on Re: Function signatures in POD-headlines/pseudo code! Is there a standard? Download Code

Replies are listed 'Best First'.
Re^2: Function signatures in POD-headlines/pseudo code! Is there a standard? by ikegami (Patriarch) on Dec 07, 2009 at 18:40 UTC
It simply lists all possible call syntaxes, using upper case letters for metasyntactic elements. I prefer the sigil notation since `\@rows` [download] is much more expressive than `EXPR` [download] or even `ARRAYREF` [download] at no cost. The system works for builtins since they operate on simple inputs, but it doesn't scale well to the more complex requirements of modules and classes.	[reply] [d/l] [select]
Re^3: Function signatures in POD-headlines/pseudo code! Is there a standard? by LanX (Saint) on Dec 07, 2009 at 18:52 UTC
there is another trap... `@coordinates` could either mean a list of 4 scalars (a 4-tuple) (like in Corion's code, where he wanted the clipping rectangle defined) or an array which is taken per reference, because of the prototype (like in shift) How do you solve this? Cheers Rolf PS: I expect you now to say that you always avoid prototypes, right? ;-)	[reply] [d/l]
Re^4: Function signatures in POD-headlines/pseudo code! Is there a standard? by ikegami (Patriarch) on Dec 07, 2009 at 19:26 UTC
I would list the four scalars if I wanted four scalars. You can always define the format of `@coordinates` at the top and use that, but I don't see any gain in doing so. The name of a variable can only tell so much. Extra limitations (e.g. that it must be an array) can be documented below. I expect you now to say that you always avoid prototypes, right? ;-) Close. I tend to write classes, and prototypes don't apply to methods.	[reply] [d/l]
Re^4: Function signatures in POD-headlines/pseudo code! Is there a standard? by Anonymous Monk on Dec 09, 2009 at 08:00 UTC
or an array which is taken per reference, because of the prototype (like in shift) Method calls are not influenced by prototypes `sub Y::Pushy(\@){ warn join ' ', map {"($_)"} @_, ''; } my @blah = 1 .. 2; Y::Pushy @blah; Y->Pushy(@blah); __END__ (ARRAY(0x3d8bbc)) () at - line 2. (Y) (1) (2) () at - line 2.` [download]	[reply] [d/l]
Re^2: Function signatures in POD-headlines/pseudo code! Is there a standard? by LanX (Saint) on Dec 07, 2009 at 18:26 UTC
OK perldoc is for sure a role model. so no parens, no sigils, all parameters are scalars, a final list is denoted as LIST (UPDATE: compare splice)) But is there a perldoc showing the use of named parameters? What about passing references? Maybe the Conway notation with a trailing _REF e.g. `RECTANGLE_REF` Don't you think that something like `\@rectangle` might be better? My ideal is to have a notation that can be used right away (and automatically) for documentation and for testing. Maybe a dry discussion about DRY principles ;-) Cheers Rolf	[reply] [d/l] [select]