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，它们接近您的要求。我不推荐任何一种，只是因为我不喜欢自动生成的文档而不管语言。好的文档需要时间和精力，否则你最终会得到一些无用的文档框架。

Answer 2

我首先要问你为什么需要如此简洁的文件陈述？

我使用过Natural Docs，我非常喜欢它。我的文档风格不简洁，但我发现它可读。例如：

=begin nd

Check if a document name is available.

A name is available iff the name is not used by any other document related to the same study
excepted if it is another version of the same document.

Params:
    name        - Proposed document name to be checked : Str.
    study       - the study related to the document
    parent      -  parent document or undef if none : <Document>
    current_instance - the curretn document instance in case of an update


Returns:
    true iff the proposed name is valid

Exception:
    Dies on bad args or errors.

=cut

Natural Docs能够自动选择功能或方法名称。此外，我用它来记录我的javascript源代码和全局文档，并可以在它们之间插入交叉链接。

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

2 个答案: