难道真的没有比 POD 更好的记录 Perl 代码的方法了吗？

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中的一切这个 似乎过于冗长：

/**
 * 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 在 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;

话又说回来，大多数语言都需要双重打字来记录。