14

我是一名 Perl 程序员很长时间了，但我总是遇到 POD 中的文档问题。

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

我想念一种类似于 Java 的文档风格。

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

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

4

6 回答 6

9

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

于 2011-01-18T09:54:28.213 回答
8

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

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

希望这可以帮助

于 2011-01-18T11:57:32.700 回答
7

Why do you think the code is hard to read with Pod? Is the code hard to read with other code around it? Perhaps you're putting too much into a particular part of the code, instead of writing small methods, etc. Are you sure it's not your code that's hard to read?

You don't have to put all of your documentation at the end of the code. Pod is perfectly fine inline with code, allowing you to put the documentation for a subroutine or method right next to the subroutine or method.

Is there some other problem you have with Pod?

于 2011-01-18T13:09:43.273 回答
3

我唯一一次遇到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) = @_;

  ...
}
于 2012-02-20T15:44:33.000 回答
1

您可能想看看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。除了文档之外，元数据对于参数验证、命令行界面等其他方面也很有用。

披露：我是开发人员。

于 2012-03-16T00:48:40.903 回答
-2

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

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

于 2016-05-13T06:32:41.083 回答