Perl はコメント以外にもドキュメントをソースに直接書くことが出来ます。
ソースとドキュメントが一体となっていて、コードを修正したらドキュメントもすぐ変更しやすく、よくあるコードとドキュメントの乖離が防ぎやすくなっているのが利点です。
（まぁそれでも、面倒なものは面倒なので、ドキュメントが嘘になってることもままあるけどね）
例えばこんな感じ。
=head1 NAME モジュールの名前 - このモジュールの簡単な説明だよ =cut
こうやって、=head1 とか書くと =cut までをドキュメントとして扱われるので、プレーンなテキストを書くことが出来ます。
Perl では、行頭に = と書くとドキュメントのコマンドとして認識されるんだね。
コメントで複数行書くときはこんな感じだよね。
# コメントで # 複数行 # 書いてみた
POD だと、複数行書くのもいちいち行頭に # 書かなくて済むよ
=head1 複数行書きたい ここは何行でも かけるよ！ =cut
もうお気づきの人はいるかもしれませんが、POD には =head1 みたいなコマンドがいくつか用意されていて、それぞれにちゃんと意味があるよ。
さっきから書き続けてる =head1 は見出し的な意味なんだ。HTML で言うところの h1 とかと同じ。
スペースで区切って内容を書くと、見出しのテキストとしてとらえられるよ。
=head1 見出しレベル1
HTML に例えるとこんな感じ。
<h1>見出しレベル1</h1>
その他にもリストとか文字を装飾したりするコマンドがあるよ。
興味のある人はこっちが詳しいので参照してね。
- hio さんの perlpod 和訳
- hippo2000 さんの Perl ドキュメントの読み方
- Wikipedia にも載ってたよ！
- プログラミング Perl Volume2 の p745 にも詳しく載ってるね
そうそう、「これ全部コメントで書いてもいいじゃん」と思った人もいるかもしれないんだけど、POD で書いておくと変換ツールで様々な形式のファイルに変換出来るので便利ですよ！
- pod2html POD を HTML に変換するよ！
- ほかにも PDF にしたりするのもあったと思う。
- CPAN は POD を解釈して HTML 表示してるね！
- CPAN モジュールインストールするときに man 形式へ変換したりもしてるよ！
Leave a comment