php - 保護された属性をphpdocで変更するメソッドを文書化する方法は?

Question

保護された属性をphpdocで変更するメソッドを文書化する最良の方法は何ですか?

たとえば、次の setVar() メソッドを文書化する正しい方法は何ですか?

class Test {
  protected $variables = array();

  public function setVar($name, $value) {
    $this->$variables[$name] = $value;
  }
}

前もって感謝します、

.L.

Answer 1

メソッドがその保護された属性に影響を与えることを強調したい理由に依存すると思います...

単に「言いたい」場合は、インライン @link タグを使用するかどうかに関係なく、説明でそのように言ってください。

/**
 * Setter for $variables or {@link Test::$variables}
 * ...

インライン @link を使用すると、$variables ドキュメントへのハイパーリンクがメソッドの説明に生成されます。

@see タグを使用して、属性へのスタンドアロン参照にすることができます。

/**
 * Setter
 * @see Test::$variables 
 * ...

これにより、属性のドキュメントへのハイパーリンクも作成されますが、独自のタグを持つことでより目立ちます。

メソッドから属性への「ポインター」を作成する場合は、 @uses タグを使用します。

/**
 * Setter
 * @uses Test::$variables
 * ...

メソッド内の @uses タグは、$variables プロパティのドキュメントに @usedby タグを自動的に配置します。結果は、メソッドからメソッドのドキュメント内の属性へのハイパーリンクと、属性からのハイパーリンクになります。属性のドキュメントのメソッドに。コーナールームと反対側のコーナールームをつなぐクルーボードゲームの「秘密の通路」に似ていると考えてください。

@uses タグを介して満たすことができるもう 1 つの意図は、$variables のドキュメントが、属性に影響を与えるすべてのメソッドを示す @usedby タグのリストを表示することです...もちろん、@ を配置することについて良心的であると仮定しますこれらのメソッドでタグを使用します。

Answer 2

私は通常、次のようなものを使用しますが、おそらくもっと良い方法があります。

class Test {
  protected $variables = array();

 //**
   * Setter for $this->variables
   *
   * @var string
   * @var string
   * @returns void
   */
  public function setVar($name, $value) {
    $this->$variables[$name] = $value;
  }
}