7

私は、POD コメントが文書化されたコードの横にある、一種のリテラル プログラミング スタイルを好みます。残念ながら、これはコードを肥大化させますが、これはあまり Perlish ではありません ;-) 今のところ私が見つけることができる最良の方法は、次のようにPod::WeaverでDist::Zillaを使用することです:

package Foo;
#ABSTRACT: Foobar helper module for Foos

=method foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

=cut

sub foo {
   ...
}

空行を削除することを主張することもできますが、これは可読性も低下させます。次のような繰り返し不要な構文を使用せずに、より簡潔に記述する方法はありませんか。

package Foo;
#ABSTRACT: Foobar helper module for Foos

#METHOD: Lorem ipsum hopladi and hoplada.
sub foo { # $bar, $doz
   ...
}

そして、これを完全な POD に拡張します。

=head1 NAME 

Foo - Foobar helper module for Foos

=head1 METHODS

=head2 foo ( $bar, $doz )

Lorem ipsum hopladi and hoplada.

おそらく Pod::Weaver プラグインを使用する必要があると思いますが、Pod::Weaver と Dist::Zilla および PPI を組み合わせたアーキテクチャを理解しようとすると、頭が痛くなりました :-(

4

2 に答える 2

3

あなたの要件に近い(Perl プロジェクト用の) Natural DocsとOODocの 2 つの異なる実装を使用しました。言語に関係なく、自動生成されたドキュメントが好きではないという理由だけで、それらのいずれもお勧めしません。優れたドキュメントには時間と労力が必要です。

于 2012-08-28T21:29:42.200 に答える
1

まず、なぜそれほど簡潔なドキュメントステートメントが必要なのかを尋ねます。

私はNaturalDocsを使用しましたが、とても気に入っています。私のドキュメントのスタイルは簡潔ではありませんが、読みやすいと思います。例：

=begin nd

Check if a document name is available.

A name is available iff the name is not used by any other document related to the same study
excepted if it is another version of the same document.

Params:
    name        - Proposed document name to be checked : Str.
    study       - the study related to the document
    parent      -  parent document or undef if none : <Document>
    current_instance - the curretn document instance in case of an update


Returns:
    true iff the proposed name is valid

Exception:
    Dies on bad args or errors.

=cut

Natural Docsは、関数名またはメソッド名を自動的に選択できます。さらに、JavaScriptソースとグローバルドキュメントを文書化するために使用し、それらの間にクロスリンクを挿入できます。

于 2012-09-03T12:13:38.180 に答える