官方手册: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

友情链接
KaDraw流程图
API参考文档
OK工具箱
云服务器优惠
阿里云优惠券
腾讯云优惠券
华为云优惠券
站点信息
问题反馈
邮箱:[email protected]
QQ群:637538335
关注微信