Perl Guru Forums: General Discussions: General Questions: Documentation Misses in Scalar::Util

CGI/Perl Guide | Learning Center | Forums | Advertise | Login

Site Search: in


	MAIN INDEX	SEARCH POSTS	WHO'S ONLINE	LOG IN

Home: General Discussions: General Questions:
Documentation Misses in Scalar::Util

vikas.deep
User

May 31, 2009, 10:03 PM

Post #1 of 4 (3222 views)

Documentation Misses in Scalar::Util	Can't Post

Somebody please do tell me why the following statement that appears in documentation
(synopsis section) of Scalar::Util module misses
out the "openhandle" subroutine. Even as (all) other
subroutines (11 in number out of 12 in total) are
enlisted in this statement.

Code

# 
SYNOPSIS 
use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted  weaken isvstring looks_like_number set_prototype);

This (past) saturday I was playing (learning) this module , I copy-pasted above statement from synopsis
section and every time I tried to use "openhandle" I got the following error

Code

#Undefined subroutine &main::openhandle called at  
larr.pl line 28.

Even though the "Description" section of this module
says that

Quote

#By default "Scalar::Util" does not export any
subroutines.

is there any valid reason to enlist 11 subroutines in
qw() statement in the synopsis and leave out one.

Is this not a typing error in the documentation ??

or is there something more to it that I am missing ??

Any idea--

Quote

-For all my suggestions " I am sure someone else can do it in a better or elegant manner!"

KevinR
Veteran

May 31, 2009, 10:56 PM

Post #2 of 4 (3220 views)

Re: [vikas.deep] Documentation Misses in Scalar::Util [In reply to]	Can't Post

This what the synopsis also says:

Quote

# and other useful utils appearing below

The author, for whatever reason, just did not include the openhandle function/method in the synopsis part of the documentation but he did note that there are more "utils".

If you want to use the openhandle function you will have to import it:

Code

use Scalar::Util qw(openhandle)

The author of a module also writes the documentation (usually). Some authors are better than others at documenting the module and sometimes there are errors in the documentation. If you look on CPAN and read the annotated version of a modules documentation you will often find corrections posted by other people or just comments. Scala::Util has one comment in the annoted version.
-------------------------------------------------

vikas.deep
User

Jun 1, 2009, 2:13 AM

Post #3 of 4 (3217 views)

Re: [KevinR] Documentation Misses in Scalar::Util [In reply to]	Can't Post

I am surprised

Code

# and other useful utils appearing below

This line never appeared in my system when I used

Code

perldoc Scalar::Util

This is what I was seeing when using
perldoc Scalar::Util

Code

NAME 
    Scalar::Util - A selection of general-utility scalar subroutines 
 
SYNOPSIS 
        use Scalar::Util qw(blessed dualvar isweak readonly refaddr reftype tainted 
                            weaken isvstring looks_like_number set_prototype); 
 
DESCRIPTION 
    "Scalar::Util" contains a selection of subroutines that people have 
    expressed would be nice to have in the perl core, but the usage would 
    not really be high enough to warrant the use of a keyword, and the size 
    so small such that being individual extensions would be wasteful. 
 
    By default "Scalar::Util" does not export any subroutines. The 
    subroutines defined are

If the "# and other useful utils appearing below"
line had ever appeared on my system I would have thought/reflected for a while before posting this message
Still more surprisingly this means

Quote

The documentation at CPAN is different from what perldoc gives in my system

-For all my suggestions " I am sure someone else can do it in a better or elegant manner!"

KevinR
Veteran

Jun 1, 2009, 9:58 AM

Post #4 of 4 (3213 views)

Re: [vikas.deep] Documentation Misses in Scalar::Util [In reply to]	Can't Post

Scalar::Util is a core module and the documentation on perldoc does not have the extra line I posted in the synopsis nor is it in the documentation of my local install of activeperl 5.8, but it is in the documentation posted on CPAN. I don't know why the documentation on CPAN has it and perldoc doesn't. I can only assume the author (or module maintainer) recently updated the documentation.
-------------------------------------------------

Search for (options)

Web Applications & Managed Hosting Powered by Gossamer Threads
Visit our Mailing List Archives