Как документировать метод, который изменяет защищенный атрибут с помощью 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, в описании метода создается гиперссылка на документацию по $ variable.

Youмог бы использовать тег @see, чтобы быть автономной ссылкой на атрибут:

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

Это также делает гиперссылку на документ атрибута, но он более заметен, имея собственный тег.

Если вы хотите создать «указатель» из метода на атрибут, используйте тег @uses:

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

Тег @uses в этом методе автоматически поместит тег @usedby в документацию длясвойство $ variable ... результат - это гиперссылка от метода к атрибуту в документе метода, а также гиперссылка от атрибута к методу в документе атрибута.Думайте об этом как об «секретных проходах» в настольной игре Clue , которая соединяет угловые комнаты с их противоположными угловыми комнатами.

Еще одно намерение, которое может быть удовлетворено с помощью тега @uses, -что документация для переменных $ покажет список тегов @usedby, которые показывают все методы, которые влияют на атрибут ... при условии, конечно, что вы добросовестно добавили теги @uses в эти методы.

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;
  }
}