Из-за простоты обслуживания и автоматического завершения класса IDE и подсказок участников я использовал PHPDoc в своем проекте. Учитывая этот пример класс:
class my_class { public $id; public $name; public $number; public function __construct() { //Do something } public function Rename($name) { $this->name = $name; } } Я бы предпочел документировать все свойства ( $id , $name и $number ) самой документацией класса, которая выше объявления класса, а затем размещать документацию по методам (если необходимо) над каждым методом. Вот что я в конечном итоге хочу, чтобы мой класс выглядел так:
/** * Represents an example class for Stackoverflow * * @property int $id The id of the object * @property string $name The name of the object * @property int $number The number of the object */ class my_class { public $id; public $name; public $number; public function __construct() { //Do something } /** * Renames the object * @param string $name Name to rename object */ public function Rename($name) { $this->name = $name; } }
Это именно то, что я предпочитаю иметь в качестве документации, однако автозаполнение Netbeans не работает правильно, так как оно перечисляет каждое свойство дважды. Например, если я начну вводить $my_class_object->i автозаполнение перечислит два свойства $ id: один, как описано в моем PHPDoc, а другой описан как неизвестная переменная с «PHPDoc Not Found».
Существует решение, которое @var решить проблему Netbeans – добавьте блок @var PHPDoc над каждым свойством, однако я думаю, что он излишне загромождает мой класс, особенно некоторые из моих классов, которые имеют 10+ свойств.
Есть ли [хорошее] решение для обеих моих проблем (чистый документ, правильный подсчет Netbeans), или я об этом неправильно?
Тег «property» специально и явно предназначен для «волшебных» свойств, то есть любых, которые на самом деле не отображаются в самом коде. Это ключевая причина, по которой тег встречается только в классе docblock. Таким образом, я предполагаю, что IDE, которые распознают тег «property», делают это с точки зрения «это не видно в коде». Конечно, я мог понять, что автозаполнение должно признать существование такого имущества и, следовательно, сделать его доступным для вас. Тем не менее, моя ставка заключается в том, что IDE будут придерживаться только самого кода для создания модели и использовать только информацию docblock для дополнения элементов, которые она уже видит в коде.
Использование тега «var» – это единственный способ документировать ваши «закодированные» свойства. Если вы хотите минимизировать строки, необходимые для использования этого тега для всех свойств, используйте однострочный док-блок:
/** @var int */ public $id;
Кроме того, вы можете использовать шаблон docblock для сокращения докблоков, где сходство тегов соответствует вашему коду:
/** @var string */ public $name; /**#@+ @var int */ public $id; public $number; /**#@-*/
Это не похоже на экономию в этом коротком списке, но это помогает, когда есть много свойств. Кроме того, он отлично работает с методами.
Я предпочитаю использовать @var над каждым свойством и вообще не @property. Я чувствую, что это позволяет вам более тесно связывать комментарии с тем, что прокомментировано. Т.е. комментарии для свойства всегда находятся рядом с свойством. Если вы используете стиль @property, и у вас есть большой класс с множеством свойств, вполне возможно, что комментарий, который описывает свойство, – это страницы от него.
Я не уверен в точном синтаксисе, но я уверен, что netbeans будет придерживаться стандартной документации php.
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html http://www.phpdoc.org/