7

我喜欢一种文字编程风格，在他们记录的代码旁边有 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 相结合的架构让我的大脑受伤:-(

4

2 回答 2

3

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

于 2012-08-28T21:29:42.200 回答
1

我将首先问您为什么需要如此简洁的文档声明？

我用过 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 源代码和全局文档，并且可以在它们之间插入交叉链接。

于 2012-09-03T12:13:38.180 回答