Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"
 
PerlMonks  

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
documenting that a subroutine returns an array is very ambiguous especially considering the fact that you can have a subroutine detect context and return the contents of the array for list context and an arrayref in scalar context (this is the behavior I actually expect when the documentation says array

Well, if the function returns an array reference in scalar context, the documentation should state that it "returns an array reference in scalar context." Simple as that. An "array" is not an "array reference" and to expect it to become one in scalar context is ridiculous.

Just take these two functions:

sub f1 { return my @x = (33, 42) } sub f2 { return (33, 42) }
To document that the first returns a list and the second returns an array is perfectly acceptable (preferable, imho.) When you see f1() in the code, you know how it is going to act. Number of elements: my $nelts = f1(); ... First element: my ($first) = f1(); ... similarly, when you see f2() in the code, you can know how it will act. Last element: my $last = f2(); ... First element: my ($first) = f2(); (This is exactly why this discussion came up in the first place. Read the first node in this thread to orient yourself.)

Juerd's mumblings (or ravings) about Perl builtins are quite irrelevant. Besides the fact that every single one of them is a special case, they aren't implemented in Perl to begin with; they are implemented in C.

The phrase "returns an array" is a very nice way of explaining exactly what you mean without addressing every context separately. I won't avoid it.

Update: Examples flipped. Thanks jarich for pointing that out. (I actually flipped my description, because I wanted to talk about list values first, and forgot to flip my examples.

-sauoq
"My two cents aren't worth a dime.";

In reply to Re: Re: Re: Re: Re: What should be returned in scalar context? (best practice) by sauoq
in thread What should be returned in scalar context? by tilly

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others imbibing at the Monastery: (7)
    As of 2018-01-16 15:47 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?
      How did you see in the new year?










      Results (182 votes). Check out past polls.

      Notices?