2

ソースコードにPHPDocとJSDocを使用しています。それらのドキュメントからAPIを構築するためのツールがあることを私は知っています。しかし、私が疑問に思っているのは、複雑なコードをどのように説明するのかということです。PHPDoc / JSDocで説明するのではなく、関数内で複数行コメントを使用するだけですか？

たとえば、次のコードについて考えてみます。

/**
 * Lorem ipsum dolor sit amet.
 * @param {Integer} width
 * @return {Boolean}
 */
function setWidth(width) {
 // Very complex code goes here...
}

上記の場合、複雑なコードにコメントするにはどうすればよいですか？JSDocはAPIの構築に使用されるため（「動作方法」ではなく「使用方法」に関するものです）、JSDocではそれができないと思います。

私の仮定は正しいですか：

  • JSDoc / PHPDocは、関数/メソッドを使用する人のためだけに書かれています。
  • 関数内のコメントは、関数/メソッドの背後にあるロジックを理解する必要がある人のために書かれています。
  • ドキュメントはAPIやソースコードのコメントとは別のものであり、（すべてのソフトウェアが提供する必要のある）ドキュメントはソフトウェアを使用したい人のために書かれています。

しかし、私が理解していないのは、アーキテクチャレベルでソフトウェアを説明しているのは何かということです。開発者向けのドキュメントも必要ですか？

ドキュメントを完成させるための戦略は何ですか？

4

2 に答える 2

2

これらのツールを使用してパブリックインターフェイスを文書化し、APIの利用者に実装の詳細を知られたり気にかけたりしたくない場合は、コード自体にこれらのコメントを入れます。また、「完璧な」ドキュメントは実際には良い目標ではありません。最高のドキュメントは、インターフェイスを明白な方法で使用する実用的なサンプルコードです。ほとんどの場合、単体テストはこの要件にうまく適合します。

于 2010-07-17T08:34:12.860 に答える
1

関数の内部動作について何かを文書化する必要があると本当に感じた場合、主にコードの開発者だけが知る必要がある場合、phpDocumentorには@internalタグがあります。

--parseprivateランタイムオプションを使用すると、非公開コード要素（プライベート変数、保護されたメソッドなど）が生成されたドキュメントに表示されます。@internalタグを介して含めたテキストも表示されます。

内部メソッドコードに関して書きたい説明は、そのような@internalの使用法の良い候補になると私には思えます。

于 2010-07-19T17:11:33.890 に答える