Peridotは、Perlスクリプト内に埋め込まれたJavadocライクなコメントを抽出して、APIドキュメントを作成するプログラムです。 Perl用のドキュメント生成コマンドでは、Perlスクリプト内にPOD形式で埋め込まれたドキュメントをperldocで抽出するのが 一般的ですが、POD形式のドキュメントは、視覚的にプログラム本体との識別がつきにくく、かえってプログラムの可読性を 低減させることになりかねません。
そこで、Perlスクリプトのコメント領域(#行)に、Javadocライクなタグを用いてAPIドキュメントに必要な情報を 記述しておき、その情報からAPIドキュメントを生成するコマンド(Peridot)を作成することにしました。
Peridotでは、テキスト形式、CSV形式、HTML形式のAPIドキュメントを作成することができます。

APIドキュメントに必要な情報は「#@タグ名」に続けて記述します。 以下はサブルーチンのAPIドキュメントに必要な情報を記述した例です。

□サブルーチン向けに記述したコメント

#@sub add #@proc 引数に指定した値を加算する #@param $input1 変数1 #@param $input2 変数2 #@return $result 加算した値

「#@sub」が「サブルーチン」、「#@proc」が「機能」、「#@param」が「引数」、「#@return」が「返り値」 に変換されて以下の通りのAPIドキュメントが作成されます。

□生成したドキュメント

[サブルーチン] add [機能] 引数に指定した値を加算する [引数] $input1 変数1 $input2 変数2 [返り値] $result 加算した値

• プログラムの中にAPIドキュメントを記述できるため、ドキュメントのメンテナンスが容易になります。
• プログラム本体とコメント部の区別がつき易いため、perldocのPOD形式に比べてプログラムの可読性が高いです。
• ドキュメントは、テキスト形式、HTML形式の他にCSV形式にも対応しているため、WordやExcelのようなOfficeソフトウェア での再利用が容易です。
• 容易に独自のタグを追加することができます。