如何检查Perl函数是否存在POD文档？需集成至构建系统

核心实现思路 #

通过分别解析代码中的函数定义和文件中的POD内容，再做匹配验证，下面是具体的实现方案：

1. 用PPI提取代码中的函数名

你提到的get_functions_with_PPI可以基于PPI::Document实现，遍历代码中的子例程节点：

sub get_functions_with_PPI {
    my ($file) = @_;
    my $doc = PPI::Document->new($file) or die "无法打开文件 $file: $!";
    my @function_names;

    foreach my $sub_node ($doc->find('PPI::Statement::Sub')) {
        push @function_names, $sub_node->name if $sub_node->name;
    }

    return @function_names;
}

2. 实现file_has_POD_for_func函数

借助Pod::Simple解析POD内容，捕获=item条目并匹配目标函数：

use Pod::Simple;

sub file_has_POD_for_func {
    my ($file, $target_func) = @_;
    my $has_pod = 0;

    my $parser = Pod::Simple->new;
    $parser->output_string(\my $dummy_output); # 屏蔽默认输出

    # 注册=item开头的回调处理
    $parser->callbacks->{start_item} = sub {
        my ($parser, $item_type, $item_text) = @_;
        # 匹配形如「func()」或「func($arg)」的条目
        if ($item_text =~ /^\Q$target_func\E\(/ ) {
            $has_pod = 1;
        }
    };

    eval { $parser->parse_file($file) };
    return $has_pod;
}

3. 更便捷的替代方案：使用Pod::Coverage

如果要集成到构建系统做自动化检查，Pod::Coverage是更专业的选择，它能直接检查包内未被POD覆盖的函数：

use Pod::Coverage;

# 检查指定包的POD覆盖情况
my $coverage = Pod::Coverage->new(
    package => 'Your::Module::Name',
    pod_from => '/path/to/your/module.pm'
);

my @uncovered_funcs = $coverage->uncovered // ();
foreach my $func (@uncovered_funcs) {
    print "函数 $func 未添加POD文档！\n";
}

内容的提问来源于stack exchange，提问作者Evan Carroll