in reply to Docs notation

In the first case, I'd assume option #1. I know it's possible to code:

sub foo {
    my $scalar = shift;
    my ( $arrayref, $hashref );
    if ( UNIVERSAL::isa( $_[0], 'ARRAY' ) {
        $arrayref = shift;
    }    if ( UNIVERSAL::isa( $_[0], 'HASH' ) {
        $hashref = shift;
    }
    ....
}

[download]

Of course, just because it _can_ be coded that way, doesn't mean it actually is. In your second question, I'd agree with the assumption that pashing a hashref requires also passing a second argument.

...

I'm guessing you're intentionally being vague, so that we can see the issues with documentation, but sometimes there is some other context in the documentation ... if you know that there's no reason to pass both an arrayref and a hashref, you could specify:

$ret = foo($scalar, [$arrayref | $hashref] );

...

But in this case, I'm more interested in knowing if you're asking this question because you're trying to understand some documentation (in which case, what documentation, if it's publicly available?), or if you're asking for advice in writing documentation.

Replies are listed 'Best First'.
Re^2: Docs notation
by syphilis (Archbishop) on Jul 28, 2007 at 07:48 UTC
    I saw some documentation the other day: 
    MouseClick($window [,$parent] [,$x_offset] [,$y_offset] [,$button] [,$
+delay])

    [download]
    A few lines further down there were some examples of usage provided, which showed that if you wanted to specify (eg) $delay, but wanted the default value for the other optional args then you had to: 
    MouseClick($window, undef, undef, undef, undef, $delay)

    [download]
    To me, that meant the usage should have been presented as something like: 
    MouseClick($window [,$parent [,$x_offset [,$y_offset [,$button [,$dela
+y]]]]])

    [download]
    Not that it matters greatly in this particular instance (as the author had provided examples of usage that clearly demonstrated what was required), but I have some documentation (that needs fixing up) wrt a function that has optional args. And before I fix it up I wanted to get some sort of idea of what that notation actually meant to people - because the more I thought about it, the less certain I became.

    I think the main message I draw from these replies is "Be explicit".

    Thanks guys.

    Cheers,
    Rob
[reply]
[d/l]
[select]

In Section Seekers of Perl Wisdom