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

我喜欢在他们记录的代码旁边有POD注释的一种文字编程风格。不幸的是这腌的代码，这是不是非常Perl ;-)我现在找到的最好的方法是使用Dist::Zilla与Pod::Weaver这样的：如何在Perl代码中简洁地记录方法？

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.

我觉得应该有一个吊舱可能:: Weaver插件，但试图了解Pod :: Weaver与Dist :: Zilla和PPI相结合的体系结构使我的大脑受到伤害:-(

来源

2012-08-28 Jakob

我已经使用了两种不同的实现（对于Perl项目）Natural Docs和OODoc靠近你的r equirement。我不推荐其中的任何一个，只是因为我不喜欢自动生成的文档而不管语言。良好的文档需要时间和精力，否则最终会产生无用的文档骨架。

来源

2012-08-28 21:29:42 chansen

谢谢。我将以解释和示例的形式区分文档（通常可以在Perl的'DESCRIPTION'和'SYNOPSIS'部分找到）以及方法目的和调用语法的文档。前者对于良好的文档很重要，后者只是方便而且可以自动生成。 – Jakob

对于自动生成的文档，+1往往没用。 – tripleee

我会先问你为什么需要如此简洁的文档语句？

我已经使用了自然文档，我非常喜欢它。我的文档风格不简洁，但我觉得它很可读。实施例：

=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

天然文档能够自动拾取功能或方法的名称。此外，我用它来记录我的JavaScript来源和全球文档，并可以在它们之间插入交叉链接。

来源

2012-09-03 12:13:38

如果我详细记录方法，简洁并不重要，但在某些情况下，一个句子和一个参数列表就足够了。我只要求这个案子。 – Jakob

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

回答

相关问题