4

メソッドを持つPHPクラスがあります。基本クラス (プロトタイプに似ていますが、下位互換性が必要なのでプロトタイプは使用していません) では、パラメーターとメソッドの説明を文書化します。

今、私はそのクラスを拡張します。この新しいメソッド (実装) では、パラメーターと説明を再文書化する必要がありますか、空白のままにする必要がありますか、それともその特定の実装に適用される関連するメモのみを残す必要がありますか?

私の目標は、PhpDoc によって作成された読み取り可能な API ドキュメントを作成し、規則に従うことです。

4

2 に答える 2

3

PhpDocumentor は、文書化されているメソッドが親クラスのメソッドの再定義であるかどうか、およびメソッドが子クラスでオーバーライドされているかどうかを示します。したがって、メソッドの docblock に入力したすべての情報に加えて、現在のメソッドに関連付けられた親メソッドおよび/または子メソッドがあることもわかります。これは、メソッドの docblock で何かを言うことがあなたの利益になることを意味します。

私がよく行うのは、キーとなるジェネリック言語を親メソッドに向けて浮かせることですが、現在の子のメソッドと孫のメソッドについてはまだ何か言いたいことがあります。子メソッドを親メソッドと区別するもの、および/またはこの子メソッドを同じ親からのピアである他の子メソッドと区別するものはすべて、この子メソッド docblock が必要とする情報です。

親から子に何かをコピー/貼り付けするつもりはありません...代わりに、親および/または兄弟に関して、子供が誰であるかをさらに明確にするつもりです。また、親の docblock 内の子については何も言わないようにしています。典型的な親子関係は、子の詳細を知る必要性を抽象化する方法として行われるからです。

于 2010-03-24T14:44:35.767 に答える
1

Zend Framework のいくつかの例を見ると、ほとんどのコメントがコピー アンド ペーストされているように見えますが、これが別のコメントにつながることもあります。

最初の例はで、次のようにZend_Http_Client_Adapter_Interface::connect宣言されています。

/**
 * Connect to the remote server
 *
 * @param string  $host
 * @param int     $port
 * @param boolean $secure
 */
public function connect($host, $port = 80, $secure = false);

そして、このインターフェースを実装するクラスを見ると、次のようZend_Http_Client_Adapter_Curlになります。

/**
 * Initialize curl
 *
 * @param  string  $host
 * @param  int     $port
 * @param  boolean $secure
 * @return void
 * @throws Zend_Http_Client_Adapter_Exception if unable to connect
 */
public function connect($host, $port = 80, $secure = false)

したがって、パラメータをコピーして貼り付けます。および実装の詳細情報。


別の例はZend_Log_Writer_Abstract::_write次のとおりです。

/**
 * Write a message to the log.
 *
 * @param  array  $event  log data event
 * @return void
 */
abstract protected function _write($event);

そして、子クラスでは、次のようになりZend_Log_Writer_Dbます。

/**
 * Write a message to the log.
 *
 * @param  array  $event  event data
 * @return void
 */
protected function _write($event)

ここでも、コピーして貼り付けます。子クラスで再作成されていない、親クラスの小さな変更。


さて、私は一般的に何をしますか？

  • 私は一般的に、開発者はコメントを十分に書いていないと考えています
  • そして、一般的にそれらを更新するのを忘れます
  • だから、私は彼らの生活を楽にするように努めており、コメントを重複させないようにしています
  • 子クラスのコメントが親クラスのコメントと異なる必要がある場合を除きます。
于 2010-03-23T19:29:08.170 に答える