Perl：写POD文档

官方手册：https://perldoc.perl.org/perlpod.html

POD文档是perl的man文档，能够用perldoc输出，也能够直接用man输出。在开始下面的文章以前，请先粗略浏览一到两篇perldoc文档，或去CPAN找几个模块的文档浏览下大体格式。

例如：

$ perldoc Data::Dumper
$ man Data::Dumper

执行perldoc的时候，perldoc会搜索@INC下的Data/Dumper.pm和Data/Dumper.pod文件。

POD文档能够直接嵌入在程序文件内，perldoc会自动对内部的pod部分进行格式化输出。也能够独立写入一个".pod"文件。在嵌入程序文件内的时候，还能够和代码部分交叉，但并不建议这么作。POD嵌入在程序文件中时，建议的作法是将POD放在代码文件的最尾部(若是程序中包含了__DATA__或__END__，则放在它们的后面)。

当写好pod文档后，可使用podcheck来检查pod文档的语法：

podchecker a.pod
podchecker a.pm

pod文档格式中，有两种内容：段落声明格式和行内格式。

段落声明

段落声明都使用=FLAG表示，=必须顶格写，前面不能有任何空白，FLAG表示开启什么类型的段落，好比是一级标题、二级标题、有序和无序列表等。其中两个特殊的段落声明为：

• =pod表示此处开始的是pod文档部分
  
• =cut表示pod文档到此结束

例如：

sub reciprocal { return 1 / shift }

=pod  # 这里表示pod文档段落今后处开始，下面属于pod文档

This is a paragraph in a POD section. When run through a formatter, the
paragraph text will rewrap as necesseary to fit the needs of your
particular output format.

=cut  # 这里表示pod文档段落到此结束，下面不属于pod文档

sub not_reciprocal { return shift }

常见的段落声明有如下几种：

=pod
=cut
=head1 Heading Text # 标题
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text

=over indentlevel  # 列表
=item stuff
=back

=begin format   # 格式，见官方手册
=end format
=for format text...

=encoding type  # 编码类型

其中列表由=over NUM开始，NUM表示列表的缩进程度，由=back结束列表。有无序列表和有序列表两种形式。例如：

=over 4

=item * This is a list item

=item * This is a second list item.

This is an optional paragraph explaining the second list item.

=back

=over 4

=item 1. This is a list item

=item 2. This is a second list item.

This is an optional paragraph explaining the second list item.

=item 3.

=back

行内格式

行内格式通常是行内代码、加粗、斜体、连接等。

格式               意义
------------     -----------------
C<text>           代码
C<< text >>       代码段中保留大于号和小于号( C<< $age >= 18 >> )
B<text>           加粗
I<text>           斜体
E<text>           转义的HTML，例如可使用E<lt>表示小于号(<)
S<text>           All ‘s’paces are nonbreaking
L<text>           连接

主要解释下生成连接的方式。支持3种连接方式：连接到另外一个文档、连接到另外一个文档的某一小节，链接到本文档的某小节以及连接到某个URL：

• L<name>：链接到另外一个文档。例如L<Scalar::Util>、L<perlunitut>，注意连接的名称中不能有空格
  
• L<name/"sec">或L<name/sec>：链接到另外一个文档的某一小节，例如L<perlpod/"Formatting Codes">
  
• L</"sec">或L</sec>：连接到本文档的某个小节
  
• L<URL>：连接到某个URL，例如L<http://www.overseas-exile.com/>

encoding和注释

若是文档使用非latin-1或ascii写，好比中文，那么要设置encoding，例如设置为utf-8。

=encoding UTF-8

若是要设置pod的注释，即pod渲染的时候会忽略的内容，须要使用：

= for comment

例如：

=pod

=for comment
DO NOT EDIT. This Pod was generated by Swim v0.1.46.
See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

文档的结构

虽然说文档能够随便写，但通常来讲都遵循一些通用的、约定俗成的规则。通常来讲，一个文档中包含如下几项信息：

• NAME: 模块名
  
• SYNOPSIS: 概要，使用简单的代码片断描述用法
  
• DESCRIPTION: 描述，介绍模块用来干什么
  
• EXPORT: 这是可选项。用来展现模块的导标签
  
• FUNCTION/METHODS: 详细描述每一个子程序/方法
  
• BUGS: 列出bug
  
• AUTHOR: 展现模块的做者
  
• LICENSE: 模块的license条款
  
• COPYRIGHT: 版权信息

除此以外，还有一些结构也能够包括进去，好比VERSION、DIAGNOSTICS、SEE ALSO、CONTRIBUTORS(贡献者通常用于列出那些非做者，但提供了补丁和反馈的人)。

pod示例：base.pod

可使用find随意搜索一个Pod文件来参考：

$ find /usr -type f -name "*.pod"

如下是base.pod的内容。

$ cat /usr/share/perl/5.26.1/base.pod
=head1 NAME

base - Establish an ISA relationship with base classes at compile time

=head1 SYNOPSIS

    package Baz;
    use base qw(Foo Bar);

=head1 DESCRIPTION

Unless you are using the C<fields> pragma, consider this module discouraged
in favor of the lighter-weight C<parent>.

Allows you to both load one or more modules, while setting up inheritance from
those modules at the same time.  Roughly similar in effect to

    package Baz;
    BEGIN {
        require Foo;
        require Bar;
        push @ISA, qw(Foo Bar);
    }

When C<base> tries to C<require> a module, it will not die if it cannot find
the module's file, but will die on any other error.  After all this, should
your base class be empty, containing no symbols, C<base> will die. This is
useful for inheriting from classes in the same file as yourself but where
the filename does not match the base module name, like so:

        # in Bar.pm
        package Foo;
        sub exclaim { "I can have such a thing?!" }

        package Bar;
        use base "Foo";

There is no F<Foo.pm>, but because C<Foo> defines a symbol (the C<exclaim>
subroutine), C<base> will not die when the C<require> fails to load F<Foo.pm>.

C<base> will also initialize the fields if one of the base classes has it.
Multiple inheritance of fields is B<NOT> supported, if two or more base classes
each have inheritable fields the 'base' pragma will croak. See L<fields>
for a description of this feature.

The base class' C<import> method is B<not> called.

=head1 DIAGNOSTICS

=over 4

=item Base class package "%s" is empty.

base.pm was unable to require the base package, because it was not
found in your path.

=item Class 'Foo' tried to inherit from itself

Attempting to inherit from yourself generates a warning.

    package Foo;
    use base 'Foo';

=back

=head1 HISTORY

This module was introduced with Perl 5.004_04.

=head1 CAVEATS

Due to the limitations of the implementation, you must use
base I<before> you declare any of your own fields.

=head1 SEE ALSO

L<fields>

=cut