There's a Perl module threads::shared. However, it won't show up as a
completion match to the perldoc command. Why is that?, a colleague
asked me. Now, that obviously is a quirk, so let's debug it.
We start at /usr/share/zsh/functions/Completion/Unix/_perldoc, where
we find this:
_alternative \
'modules:module: _perl_modules -tP' \
'pods:base pod: _perl_basepods' \
'files:module or .pod file:_files -g "*.(pod|pm)(-.)"' &&
ret=0
So, go on to _perl_modules: It searches for paths where Perl would
store modules and their documentation (line 85):
inc=( $( $perl -e 'print "@INC"' ) )
Then, they do some complicated globbing stuff on the directories (line
104), where a loop iterates over $inc and stores each element in
$libdir:
new_pms=( $libdir/{[A-Z]*/***/,}*${~sufpat}~*blib* )
There's the catch: This globbing expression will only recurse into
subdirectories that start with an uppercase letter. Lowercase
modules on the highest level are okay, though. That's why threads
appears (from threads.pm), but threads::shared doesn't (from
threads/shared.pm).
The search for all modules that are missed this way will translate to the following Z-Shell command:
$ print -l ${^=$(perl -e 'print "@INC"')}/[a-z]*/***/*.pm(.N)
/usr/lib/perl/5.10/threads/shared.pm
/usr/share/perl/5.10/encoding/warnings.pm
/usr/share/perl/5.10/warnings/register.pm