Perlコードを文書化する方法について何か提案はありますか?何を使用し、どのツールを使用して私を支援できますか?
ポッドをHTMLに変換するためにどのモジュールを使用しますか?
Perlコードを文書化する方法について何か提案はありますか?何を使用し、どのツールを使用して私を支援できますか?
ポッドをHTMLに変換するためにどのモジュールを使用しますか?
ほとんどすべての Perl モジュールの内部を見ると、Plain Old Documentation (POD)形式が表示されます。CPAN Searchでは、モジュールを見るときに生のソースを表示するオプションがあるため、生のポッドを見る方法の 1 つですが、コマンド ラインからperldocを使用することもできます。-m
スイッチはファイルを表示します
perldoc -m Foo::Bar
または、ファイルを見つけてお気に入りのエディターで表示できるようにする場合は、-l
スイッチを使用して見つけます。
perldoc -l Foo::Bar
プログラムのドキュメント化を開始したら、Pod をコードと一緒にファイルに配置します。コードと織り交ぜてドキュメントを関連部分の隣に配置するか、最初、中間、または最後に 1 つの大きなチャンクとして配置します。
Pod は、Perl に付属のトランスレーター (pod2latex、pod2ps、pod2html) を使用して、LaTeX、Postscript、HTML などの他のいくつかの形式に簡単に変換できます。InDesign に接続するポッド トランスレータもあります。Pod::Simpleを使用すると、独自の Pod トランスレーターを簡単に作成できるため、お気に入りの最終フォームのトランスレーターが見つからない場合は、自分で作成してください。
Pod をチェックするためにテスト スイートに追加できるツールもいくつかあります。Test::Podモジュールはフォーマット エラーをチェックし、Test::Pod::Coverageモジュールは各サブルーチンの文書化などをチェックします。私のPerl ドキュメント documentationにも興味があるかもしれません。
私は間違いなくPODをお勧めします。
POD はコードとインラインで使用することもできますが、私は __END__ の後にプログラムの一番下に配置することを好みます (Damian Conway がPerl Best Practicesで推奨しているように)。
すべての POD に Web フロントエンドを提供するPOD ::Serverと POD::Webserverを見てください。
これは、MozillaがPerlを文書化する方法です。
極端にひっくり返してはいけませんが、Perl コードを文書化する最良の方法は、他の言語でコードを文書化するのと同じ方法です。
特定のツールに関しては、標準のインライン コメント、 manに似た形式が適切な大量のドキュメントの場合は pod、より自由な形式にする必要があるドキュメントの最終的なフォールバックとして TeX を組み合わせて使用します。(そして、「他の言語と同じ」という精神で、はい、非 Perl コードの文書化にも pod を使用します。)
ポッドをHTMLに変換するためにどのモジュールを使用しますか?
Pod::ProjectDocsをチェックしてください-PerlプロジェクトのすべてのPODをsearch.cpan.orgに表示されているものと同じように見えるHTMLページのセットに変換するシンプルなコマンドラインユーティリティを入手できます。
Smart::Commentsについて誰も言及していませんか?それは常にあなたが望むものではありませんが、コメントにもっと力が必要な場合は良いことです.
また、DamianConwayによるPerlのベストプラクティスも確認することをお勧めします。いくつかのヒントを使用して、継承した小さなPerlコードベースをクリーンアップしました。
ユーザードキュメントとコーダードキュメントを分けてください。おそらく、ユーザー ドキュメント (tuts、faq、リファレンス) をそこのディレクトリ (/doc) に置き、コーダーをコードと同じ場所に置きます。残念ながら、慣例により、モジュール自体で概要を説明することが期待されています。これは、すでにレイアウトされているように、 ENDの後に POD を実行できます。コメントに入れることができるmaneコーディングドキュメント。コーディングスタイルや貢献方法などの追加事項は、コードベース内の個別の .pod ファイルに入れます (ルートディレクトリ?)