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