如何在Perl代码中简明地记录方法？

Question

我赞成一种文字编程风格,在他们记录的代码旁边有POD注释.不幸的是,这膨胀了代码,这不是非常Perlish ;-)我现在能找到的最好的方法是使用Dist :: Zilla和Pod :: Weaver一样:

package Foo;
#ABSTRACT: Foobar helper module for Foos

=method foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

=cut

sub foo {
   ...
}

人们可能会争论删除空行,但这也会降低可读性.有没有办法写更简洁,没有任何重复和不必要的语法,如下所示:

package Foo;
#ABSTRACT: Foobar helper module for Foos

#METHOD: Lorem ipsum hopladi and hoplada.
sub foo { # $bar, $doz
   ...
}

并将此扩展到完整的POD:

=head1 NAME 

Foo - Foobar helper module for Foos

=head1 METHODS

=head2 foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

我认为它可能应该是一个Pod :: Weaver插件,但试图理解Pod :: Weaver结合Dist :: Zilla和PPI的架构让我的大脑受伤:-(

Answer 1

我使用了两种不同的实现（对于 Perl 项目）Natural Docs和OODoc，它们接近您的要求。我不推荐其中任何一个，只是因为我不喜欢自动生成的文档，无论语言如何。好的文档需要时间和精力，否则你最终会得到一个毫无用处的文档框架。