Question

我很长一段时间都是Perl程序员，但我在POD中的文档总是有问题。

当我在代码中使用POD注释时，代码很难阅读。当我在文件末尾使用POD注释时，存在文档与代码不同步的危险。

我想念一种类似于Java的文档样式。

/**
 * @description
 * ...
 */

我寻找更简单，更直观的文档样式。有这样的事吗？

Answer 1

快速搜索Doxygen Filter，声称允许您使用Doxygen样式注释（非常接近Javadoc）来记录Perl代码。

Answer 2

嗯，POD是发布Perl文档的公认标准。

我觉得维护也很烦人;我最近尝试使用Pod::Weaver维护文档并在发布时将其构建到Pod中。它有点棘手，因为它在过滤和构建POD方面非常灵活，可以使用更多文档（在POD或其他方面）。但似乎很有希望。对我来说，提供更多的判断还为时尚早，但似乎很有希望。

希望这有帮助

Answer 3

为什么你认为使用Pod难以阅读代码？代码难以与周围的其他代码一起阅读吗？也许你在代码的某个特定部分投入太多，而不是编写小方法等。你确定你的代码不是很难读的吗？

您不必将所有文档放在代码的末尾。 Pod与代码完全一致，允许您将子例程或方法的文档放在子例程或方法旁边。

你对Pod有其他问题吗？

Answer 4

我唯一遇到POD问题的时候是使用不能正确突出显示的文本编辑器。

就像Java this中的一切似乎过于冗长：

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute  

{@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 *  

@param  url  an absolute URL giving the base location of the image
 *  

@param  name the location of the image, relative to the url argument
 *  

@return      the image at the specified URL
 *  

@see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

与等效的Perl相比。

=item getImage( url, name )

This method always returns immediately, whether or not the 
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives 
that draw the image will incrementally paint on the screen. 

url must be an absolute URL giving the base location of the image

name is the location of the image, relative to the url argument

=cut

sub getImage{
  my ($url,$name) = @_;

  ...
}

Answer 5

您可能需要查看Rinci。使用此功能的应用程序示例：File::RsyBak，Git::Bunch，App::OrgUtils。

以下是您记录模块的方式。您在模块中声明％SPEC并将文档放入其中。每个函数都有自己的密钥。有预定义的字段。支持本地化。格式化在Markdown中完成。一个例子：

$SPEC{':package'} = {
    summary => 'Module to do foo',
    "summary.alt.lang.id_ID" => "Modul untuk melakukan foo",
    description => <<EOT,
Blah...
...
EOT
    links => [...],
};
$SPEC{func1} = {
    summary => '...',
    description => '...',
    args => {
        arg1 => {
            schema => ...,
            summary => ....,
            description => ...,
        },
    },
    examples => [...],
    links => [...],
    ...
};

它不使用Java或Perl 5样式将文档放在“注释”中，而是使用可直接用于程序的数据结构。（注意Perl 6也是这样的。）把它想象成Python文档字符串变得疯狂（或结构化）。

有些工具可以从元数据（规范）生成POD，文本，HTML。除了文档之外，元数据还可用于其他参数，如参数验证，命令行界面等。

披露：我是开发者。

Answer 6

我自己，我经常发现想要将代码条目复制到文档中。然而，找到我如何欺骗POD在播放时读取代码，同时让代码在解析时执行。我真的要满足于此：

=head1 Variables

use vars (%V &C)

=cut

use vars (%V %C)

=head2 Constants

$C{hashConstant1} = "/path/to/file"

=cut

$C{hashConstant1} = "/path/to/file";

=head2 Variables

$V{strVar1} = undef

=cut

$V{strVar1} = undef;

然后，大多数语言都要求双重输入才能记录。

记录perl代码真的没有比POD更好的方法吗？

6 个答案: