perlxs.pod clarification

Just reading through perlxs.pod when I came across a seeming inconsistency
in the description of the MODULE and PACKAGE keywords. The MODULE keyword
is defined as (in bleedperl):


       The MODULE keyword is used to start the XS code and to
       specify the package of the functions which are being
       defined.  All text preceding the first MODULE keyword is
       considered C code and is passed through to the output
       untouched.  Every XS module will have a bootstrap function
       which is used to hook the XSUBs into Perl.  The package
       name of this bootstrap function will match the value of
       the last MODULE statement in the XS source files.  The
       value of MODULE should always remain constant within the
       same XS file, though this is not required.

       The following example will start the XS code and will
       place all functions in a package named RPC.

            MODULE = RPC

       <snip>

Now this suggests to me that if you do the above you will end up with
functions that exist in PACKAGE RPC. ie equivalent to:

            MODULE = RPC PACKAGE = RPC

unfortunately this doesn't seem to be the case. If I just use the MODULE
keyword I end up with something like this from xsubpp:

       newXS("myfunc", XS__myfunc, file);

whereas if I add the PACKAGE keyword I get:

       newXS("MyPackage::myfunc", XS__MyPackage_myfunc, file);

These are obviously not the same. Either the MODULE description is being
deliberately confusing by using the word "package" in a sense different
from the perl "package" function and the XS PACKAGE keyword or xsubpp
needs to be changed to default package name from the module name (or I
just need some sleep!).

I am happy to provide a patch to either the documentation or to xsubpp if
I can get some clarification on this.

To further add to the problem this is the documentation for PACKAGE:

       <snip>
       Although this keyword is optional and in some cases
       provides redundant information it should always be used.
       This keyword will ensure that the XSUBs appear in the
       desired package.

So it is optional yet should always be used????? Let's not sit on the
fence here! Currently, MODULE without PACKAGE does not seem to do anything
useful.

-- 
Tim Jenness
JCMT software engineer/Support scientist
http://www.jach.hawaii.edu/~timj

• perlxs.pod clarification by Tim Jenness