Why is "package" keyword sometimes separated by a comment from the package name?

Question

Analyzing sources of CPAN modules I can see something like this:

...
package # hide from PAUSE
   Try::Tiny::ScopeGuard;
...

Obviously, it's taken from Try::Tiny, but I have seen this kind of comments between package keyword and package identifier in other modules too.

Why this procedure is used? What is its goal and what benefits does it have?

Answer 1

It is indeed a hack to hide a package from PAUSE's indexer.

When a distribution is uploaded to PAUSE, the indexer will examine each file in the upload, looking for the names of packages that are included in the distribution. Any indexed packages can show up in CPAN search results.

There are many reasons for not wanting the indexer to discover your packages. Your distribution may have many small or insignificant packages that would clutter up the search results for your module. You may have packages defined in your t (test) directory or some other non-standard directory that are not meant to be installed as part of the distribution. Your distribution may include files from a completely different distribution (that somebody else wrote).

The hack works because the indexer strictly looks for the keyword package and an expression that looks like a package name on the same line.

Nowadays, you can include a META.yml file with your distribution. The PAUSE indexer will look for and respect a no_index specification in this file. But this is a relatively new capability of the indexer so older modules and old-timer CPAN contributors will still use the line break hack.

Here's an example of a no_index spec from Forks::Super

no_index:
    directory:
        - t
        - inc
    package:
        - Sys::CpuAffinity
        - Signals::XSIG
        - Signals::XSIG::Default
        - Signals::XSIG::TieArray56

Sys::CpuAffinity and Signals::XSIG are separate distributions that are also packaged with Forks::Super. Some of the test scripts contain package declarations (e.g., Arbitrary::Test::Package) that shouldn't be indexed.