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

LanX has asked for the wisdom of the Perl Monks concerning the following question:

After meditating about Re^4: Screencapture with Perl on Linux I'm still confused about the widespread POD-habit to denote optional parameters in pseudo-code by enclosing them in brackets

    $mech->content_as_png [TAB, COORDINATES]
[download]

(I'm don't know where this notation stems from, C, Fortran or just BNF? Where is it defined?)

Anyway it conflicts with concrete perl notation where brackets either denote

a reference to a literal array of parameters (often used when mixed with named parameters)
or alternatively accepted types in Prototypes

and can cause confusion.

According to the documentation for prototypesą, optional parameters are denoted by a preceding semicolon, which would lead to:

    $mech->content_as_png (;TAB,COORDINATES)
[download]

other CPAN authors prefer to denote the type of arguments by indicating the sigil and avoid upper case:

    $mech->content_as_png ($tab,@coordinates)
[download]

(and for completeness, some authors skip the parens around parameters others don't.)

I'm no CPAN-author yet and don't intend "to be more catholic than the pope"˛ but I'm wondering

if there is a best practice or even standard for function signatures in pseudo code???

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

Cheers Rolf

(1) yes I know that prototype syntax is rather "restricted" for defining signatures

(2) sure I'm mathematician but still pragmatic ;)

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

Replies are listed 'Best First'.
Re: Function signatures in POD-headlines/pseudo code! Is there a standard? by ikegami (Patriarch) on Dec 07, 2009 at 17:53 UTC
I avoid the need for a meta notation by simply spelling out the alternatives like in Perl's docs. `=head3 C<< $mech->content_as_png() >> =head3 C<< $mech->content_as_png($tab, @coordinates) >> Returns the ...` [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:00 UTC
Ok, but being precise this would lead to `=head3 C<< $mech->content_as_png() >> =head3 C<< $mech->content_as_png( $tab ) >> =head3 C<< $mech->content_as_png( $tab, $x0, $y0, $x1, $y1 ) >>` [download] Hmm ... IMHO a meta-syntax can be shorter though precise, but this needs a common consensus... Cheers Rolf	[reply] [d/l]
Re^3: Function signatures in POD-headlines/pseudo code! Is there a standard? by ikegami (Patriarch) on Dec 07, 2009 at 18:03 UTC
Occasionally, you'll get three alternatives and that's fine. If you have more than three alternatives, your function's parameter list is probably too complex and needs a redesign anyway.	[reply]
Re^4: Function signatures in POD-headlines/pseudo code! Is there a standard? by LanX (Saint) on Dec 07, 2009 at 18:09 UTC
Re^3: Function signatures in POD-headlines/pseudo code! Is there a standard? by moritz (Cardinal) on Dec 07, 2009 at 18:33 UTC
You can list the empty and the full signature, and mention in the prose text that they are optional, and leaving out some of them at the end is allowed too. but this needs a common consensus No. The Perl community is far too big to always reach an consensus, especially not for a topic that's subject to personal taste as much as this topic.	[reply]
Re^2: Function signatures in POD-headlines/pseudo code! Is there a standard? by Anonymous Monk on Dec 08, 2009 at 07:42 UTC
`=head3 C<< $mech->content_as_png >> $mech->content_as_png() $mech->content_as_png($tab, @coordinates)` [download]	[reply] [d/l]
Re: Function signatures in POD-headlines/pseudo code! Is there a standard? by moritz (Cardinal) on Dec 07, 2009 at 18:07 UTC
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.	[reply] [d/l]
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
Re^4: Function signatures in POD-headlines/pseudo code! Is there a standard? by Anonymous Monk on Dec 09, 2009 at 08:00 UTC
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]
Re: Function signatures in POD-headlines/pseudo code! Is there a standard? by Anonymous Monk on Dec 08, 2009 at 07:45 UTC
It is Backus–Naur Form Docs notation	[reply]
Re^2: Function signatures in POD-headlines/pseudo code! Is there a standard? by LanX (Saint) on Dec 08, 2009 at 12:11 UTC
thx, Extended_Backus–Naur_Form to be precise. Well at least! It's not clear if Niklaus Wirth invented the bracket notation for optional syntax, or if he got it from somewhere else. Cheers Rolf	[reply]