Документирование PHP, я должен копировать / вставлять, если я расширяю класс? - PullRequest
Новая
       5

Документирование PHP, я должен копировать / вставлять, если я расширяю класс?

4 голосов
/ 23 марта 2010

У меня есть класс PHP с методом. В базовом классе (это больше похоже на прототип, но я не использую прототипы, потому что мы должны быть обратно совместимы), я документирую параметры и описание метода.

Теперь я расширяю этот класс. В этом новом методе (реализации) мне следует заново документировать параметры и описание, оставить его пустым или оставить только соответствующие примечания, относящиеся к данной конкретной реализации?

Моя цель - иметь читаемые документы API, созданные PhpDoc, и следовать соглашениям.

Ответы [ 2 ]

3 голосов
/ 24 марта 2010

PhpDocumentor покажет вам, является ли документируемый метод переопределением метода в родительском классе, а также переопределен ли метод в дочернем классе. Таким образом, помимо всей информации, которую вы помещаете в докблок метода, вы также увидите, что есть родительский метод и / или дочерний метод, связанный с текущим методом. Это означает, что вам выгодно сказать что-то в докблоке метода.

Что я обычно делаю, так это перемещаю ключевой родовой язык вверх по направлению к родительскому методу, но у меня все еще будет что сказать о методе текущего дочернего элемента, а также о методе внука. Независимо от того, что отличает дочерний метод от родительского метода, и / или от того, что отличает этот дочерний метод от других дочерних методов, являющихся его пэрами от того же родителя, это информация, необходимая для этого дочернего блока документации.

Я никогда не собираюсь копировать / вставлять что-то от родителя к ребенку ... Вместо этого я собираюсь дополнительно уточнить, что делает ребенок таким, какой он есть по отношению к родителю и / или его братьям и сестрам. Кроме того, я пытаюсь , а не , чтобы что-то сказать о дочерних элементах внутри докблока родителя, поскольку типичные отношения родитель-ребенок сделаны как способ абстрагироваться от необходимости знать специфику дочерних элементов.

1 голос
/ 23 марта 2010

Глядя на пару примеров в 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)

Здесь опять-таки копировать-вставить; и небольшая модификация в родительском классе, которая не была воссоздана в дочернем классе.


Теперь, что я вообще делаю?

  • Я вообще считаю, что разработчики не пишут комментарии достаточно часто
  • И вообще забудьте чтобы обновить их
  • Итак, я стараюсь сделать их жизнь проще, и не дублирую комментарии
  • Если комментарий в дочернем классе не должен отличаться от комментария в родительском классе.
...