7

コードドキュメントに使用例を配置するためのベストプラクティスは何ですか？標準化された方法はありますか？@usageまたは@notesで？ドキュメントジェネレータはこれをサポートする傾向がありますか？

この質問はドキュメントジェネレータに依存する必要があることを私は知っています。ただし、各ジェネレーターの特異性に入る前に、ドキュメント生成にコメントスタイルを使用する習慣を身に付けようとしています。違いよりも類似点が多いようです。

私はDoxygenを試し、AS3、JS、PHP、Obj-C、C++をよく使用します。

例えば：

/**
 * My Function
 * @param object id  anObject 
 * @usage a code example here... 
 */
function foo(id) {

}

また

/**
 * My Function
 * @param object id  anObject 
 * @notes a code example here, maybe?
 */
function foo(id) {

}

ありがとう

4

1 に答える 1

4

Doxygenにはコマンド@exampleがあり、サンプルソースパスを構成するための多くのオプションがあります。

Doxygenと他のドキュメンテーションツールの間には共通のコマンドセットがあると思いますが、それらは適切なドキュメンテーションには少なすぎます。特定のツールを最大限に活用するには、具体化する必要があります。Doxygenはオープンソースであり、高度に構成可能であるため、私はDoxygenが好きです。しかし、それは私の意見にすぎません。

たぶん、@ xrefitemエイリアスを使用してdoxygenを構成し、他のドキュメントツールで定義されたドキュメントコメントを解析できるようにすることができます。

于 2010-03-09T20:35:06.900 に答える