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

Question

长期以来，我一直是一名 Perl 程序员，但我总是遇到 POD 中的文档问题。

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

我怀念类似于 Java 的文档风格。

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

我寻找一种更简单、更直观的文档风格。有这种事吗？

Answer 1

快速搜索找到了Doxygen Filter，它声称允许您使用Doxygen 样式的 cmets（非常接近 Javadoc）来记录 Perl 代码。

Answer 2

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

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

希望对你有帮助

Answer 3

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

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

Pod 还有其他问题吗？

Answer 4

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

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

/**
 * 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 风格将文档放在“cmets”中，而是使用程序直接可用的数据结构。 （请注意，Perl 6 也是如此。）将其视为 Python 文档字符串变得疯狂（或结构化）。

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

披露：我是开发者。

Answer 6

我自己，经常想将代码条目复制到文档中。 还没有找到如何欺骗 POD 在 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;

再说一次，大多数语言都需要双打才能记录。