POD(Plain Old Documentation)の書き方

Perl
構文
here

Perlはソースコードの中にドキュメントを埋め込むことができます。このソース内ドキュメントのことをPODといい独自の記述方法があります。

Perlにはモジュールを公開できるCPANというサイトがありますが、CPANに公開されるモジュールのドキュメントはすべてPODで書かれています。

感覚的にはPODはHTMLを簡易に記述できて、自動的にHTMLに変換されると考えましょう。

文字コード

英数字以外をドキュメントに含める場合は文字コードを設定する必要があります。「UTF-8」で記述する場合はドキュメントの先頭に以下のように書きます。

=encoding utf8

ヘッダ

HTMLのh1からh6に対応します。

=head1 ヘッダ1

=head2 ヘッダ2

=head3 ヘッダ3

=head4 ヘッダ4

=head5 ヘッダ5

=head6 ヘッダ6

PODを書くときの注意点ですが、必ず次の行には改行を入れる必要があります。たとえば次の記述はうまくいきません。

=head1 ヘッダ1
=head2 ヘッダ2

ソースコード

ソースコードを記述するにはソースコードに対して、先頭に空白を設定します。これはHTMLのpreに該当します。

  use DBIx::Custom;
  my $dbi = DBIx::Custom->connect(...);

空白は1でも2でも4でも、自由な幅でかまいません。

書式

PODで書式を設定する方法です。

太字

太字を設定するには「B<>」という記述を使います。

B<あいうえお>

斜体

斜体を設定するには「I<>」という記述を使います。

I<あいうえお>

プログラムテキスト

テキストの中の関数名などをそれとわかる形でフォーマットしたい場合は「C<>」が使えます。

C<select>

ハイパーリンク

ハイパーリンクの記法を解説します。

他のCPANモジュール

他のCPANモジュールへのリンクを記述するには「L<>」を使って以下のように書きます。Object::Simpleのページへのリンクになります。

L<Object::Simple>

一般のURLへのリンク

一般のURLは「L<テキスト|URL>」のように記述します。

L<サンプルコードPerl入門|http://d.hatena.ne.jp/perlcodesample>

PODの開始と終わり

PODの開始は「=pod」でPODの終わりは「=cut」で終わります。

=pod

ドキュメント

=cut

一般的には「=head1」などのPODの記述が一つでも出現するとPODが開始されるので「=pod」と書くことはあまりありません。ただしソースコードの中で複数行コメントを使うときは、この記述方法が利用されます。

文字エスケープ

PODで利用される記号を使いたい場合はエスケープする必要があります。エスケープは「」を使って行うことができます。

E<lt> <
E<gt> >

FAQ

PODに関するFAQです。

PODでテーブルを記述することはできますか。

PODでテーブルを記述することはできません。

PODで画像を利用することはできますか。

PODで画像を利用することはできません。

CPANモジュールにおける慣習的な書き方を教えてください

CPANモジュールのドキュメントは一般的に次のような書き方になっています。

=head1 NAME

モジュール名 - モジュールの簡単な解説

=head1 SYNOPSIS

  ソースコードのサンプル
  
=head1 DESCRIPTION

モジュールの解説

=head1 METHODS

=head2 メソッド1

=head2 メソッド2

=head1 AUTHOR

著者名

=head1 COPYRIGHT & LICENSE

著作権表示

=cut

PODの詳細なドキュメント

PODの詳細なドキュメントについては、PerlのPODに関するドキュメントを見てください。

perlpod - PODのドキュメント

Perl入門ゼミ