develooper Front page | perl.perl5.porters | Postings from August 1999

perlfunc annonations or OOB enhancements?

Thread Next
Tom Christiansen
August 27, 1999 16:13
perlfunc annonations or OOB enhancements?
Message ID:
Currently, the entries in perlfunc look like

   localtime EXPR

or like

    substr EXPR,OFFSET,LEN
    substr EXPR,OFFSET

or like 


And certain people want more semantic information either
there or else in an out-of-band document.  

For example, that summary for substr() doesn't say that it's got an
assignable return value, nor does it indicate what should go in EXPR (a
string, not a number or an object reference), nor that the REPLACEMENT is
also a string.  vec() is similar, but the values of OFFSET are completely

localtime(), on the other hand, does not therein by its perlfunc header
alone indicate both a list and scalar return value, nor does it say
what should go in EXPR (a non-negative integer, not a string nor an
object reference), nor does it explain what the various list return
value elements mean semantically, including their valid ranges?

The primary motivation for this kind of thing that I could discern is
that ActiveState wants to do some kind of GUI hand-holding programming
tool for people who can't remember the legal input or output values and
contexts for functions, nor who can be bothered to look it up in the
full description.  They'd like to codify this so they can build their
products.  Dick seems to consider this kind of thing something which
"all modern programmers expect", which shocks me.

I'm not sure how much support for those efforts should be in perlfunc, or
perhaps even in the distribution at all (personally, I use and
the source code).  Can anyone supply some non-commercial motivation for
doing anything in this arena?  And if so, what is your proposed syntax?

    "If ease of use is the highest goal, we should all be driving golf carts."
    	--Larry Wall

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About