如何让Raku的Pod::To模块识别Pod::Block::Declarator元素？

问题场景 #

测试代码 #

#!/usr/bin/env raku
use v6.d;

sub MAIN (
    :$foo = 42, #= A test
) {
    run $*EXECUTABLE, '--doc', $*PROGRAM;
}

=begin pod

=head1 Bar

blah, blah, blah

=head2 Baz

yadda, yadda, yadda

=end pod

运行输出 #

class Mu $
A test

Bar

blah, blah, blah

  Baz

yadda, yadda, yadda

疑问 #

1. 输出开头的class Mu \nA test是什么？使用doc=HTML和doc=Markdown时同样会出现这段内容。
2. 使用doc=Man格式时直接报错，错误信息如下：

Unknown POD element of type 'Pod::Block::Declarator': Pod::Block::Declarator.new(WHEREFORE => Mu $, config => {}, contents => [])
  in method pod-node at /usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329 (Pod::To::Man) line 134
  in block  at /usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329 (Pod::To::Man) line 71
  in method para-ctx at /usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329 (Pod::To::Man) line 55
  in method pod-node at /usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329 (Pod::To::Man) line 64
  in method pod2man at /usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329 (Pod::To::Man) line 140
  in method render at /usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329 (Pod::To::Man) line 148
  in block <unit> at ./usage-pod.raku line 21

The spawned command '/usr/local/Cellar/rakudo-star/2023.02/bin/rakudo' exited unsuccessfully (exit code: 1, signal: 0)
  in block <unit> at ./usage-pod.raku line 1

问题解析与解决方法 #

关于class Mu输出的原因 #

这段内容是Raku编译器自动生成的Pod元素：Pod::Block::Declarator。当你在MAIN子例程的参数后用#=添加注释时，编译器会自动将参数声明和注释转换为Pod节点，其中Mu是该参数的默认类型（Raku的根类型，所有类型的父类），A test就是你添加的参数注释。

让Pod::To模块识别Pod::Block::Declarator的方法 #

1. 升级对应模块

你的Pod::To::Man版本过旧，未支持Pod::Block::Declarator类型。使用Raku的包管理器zef执行升级命令即可解决：

zef upgrade Pod::To::Man

升级后模块会自动处理该类型的Pod元素，不再报错，同时输出格式也会更规范。

2. 手动扩展模块支持

如果无法升级模块，可以修改Pod::To::Man的代码，在pod-node方法中添加对Pod::Block::Declarator的处理分支。找到模块文件（错误信息中已给出路径：/usr/local/Cellar/rakudo-star/2023.02/share/perl6/site/sources/12D9BFFD82AD93CF4CA5996422D1B5A175300329），打开后找到method pod-node，添加如下处理逻辑：

when Pod::Block::Declarator {
    # 按需格式化输出，示例为输出类型声明和注释
    my $comment = .contents.join('');
    self.emit(.WHEREFORE ~ "\n" ~ $comment ~ "\n");
}

修改后保存，重新运行即可正常生成man格式文档。

3. 避免自动生成Declarator元素

如果不需要自动生成的参数文档，可以将参数后的#=改为普通的#注释，这样编译器就不会生成Pod::Block::Declarator节点，输出中也不会出现class Mu相关内容。但此方法会丢失参数的自动文档生成功能。

内容的提问来源于stack exchange，提问作者Jim Bollinger