27

Perlコードを文書化する方法について何か提案はありますか？何を使用し、どのツールを使用して私を支援できますか？

ポッドをHTMLに変換するためにどのモジュールを使用しますか？

4

8 に答える 8

48

ほとんどすべての 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にも興味があるかもしれません。

于 2008-10-10T11:29:35.077 に答える
25

私は間違いなくPODをお勧めします。

POD はコードとインラインで使用することもできますが、私は __END__ の後にプログラムの一番下に配置することを好みます (Damian Conway がPerl Best Practicesで推奨しているように)。

すべての POD に Web フロントエンドを提供するPOD ::Serverと POD::Webserverを見てください。

于 2008-10-10T11:43:56.923 に答える
21

Perlポッド。

これは、MozillaがPerlを文書化する方法です。

于 2008-10-10T10:43:24.623 に答える
10

極端にひっくり返してはいけませんが、Perl コードを文書化する最良の方法は、他の言語でコードを文書化するのと同じ方法です。

特定のツールに関しては、標準のインライン コメント、 manに似た形式が適切な大量のドキュメントの場合は pod、より自由な形式にする必要があるドキュメントの最終的なフォールバックとして TeX を組み合わせて使用​​します。(そして、「他の言語と同じ」という精神で、はい、非 Perl コードの文書化にも pod を使用します。)

于 2008-10-10T11:28:48.183 に答える
6

ポッドをHTMLに変換するためにどのモジュールを使用しますか？

Pod::ProjectDocsをチェックしてください-PerlプロジェクトのすべてのPODをsearch.cpan.orgに表示されているものと同じように見えるHTMLページのセットに変換するシンプルなコマンドラインユーティリティを入手できます。

于 2008-10-17T18:39:35.660 に答える
4

Smart::Commentsについて誰も言及していませんか？それは常にあなたが望むものではありませんが、コメントにもっと力が必要な場合は良いことです.

于 2008-12-25T19:46:22.873 に答える
3

また、DamianConwayによるPerlのベストプラクティスも確認することをお勧めします。いくつかのヒントを使用して、継承した小さなPerlコードベースをクリーンアップしました。

于 2008-10-21T16:02:44.323 に答える
3

ユーザードキュメントとコーダードキュメントを分けてください。おそらく、ユーザー ドキュメント (tuts、faq、リファレンス) をそこのディレクトリ (/doc) に置き、コーダーをコードと同じ場所に置きます。残念ながら、慣例により、モジュール自体で概要を説明することが期待されています。これは、すでにレイアウトされているように、 ENDの後に POD を実行できます。コメントに入れることができるmaneコーディングドキュメント。コーディングスタイルや貢献方法などの追加事項は、コードベース内の個別の .pod ファイルに入れます (ルートディレクトリ?)

于 2011-11-12T17:30:42.463 に答える