Правильный способ документировать класс в Netbeans PHP - PullRequest
Новая
       52

Правильный способ документировать класс в Netbeans PHP

5 голосов
/ 24 января 2012

Из-за простоты обслуживания и автозаполнения класса 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».

Тамэто решение, которое работает для решения проблемы Netbeans - добавьте блок @var PHPDoc над каждым свойством, однако я думаю, что он излишне загромождает мой класс, особенно некоторые из моих классов, которые имеют свойства 10+.

Isесть [хорошее] решение обеих моих проблем (чистый документ, правильные подсказки Netbeans), или я ошибаюсь?

Ответы [ 3 ]

6 голосов
/ 25 января 2012

Тег «property» специально и явно предназначен для «магических» свойств, то есть любых, которые на самом деле не появляются в самом коде. Это основная причина, по которой тег встречается только в классе docblock. Таким образом, я предполагаю, что IDE, которые распознают тег «property», делают это с точки зрения «это НЕ видно в коде». Конечно, я мог понять ожидание, что автозаполнение должно признать существование такого свойства и, следовательно, сделать его доступным для вас. Тем не менее, я держу пари, что IDE будут использовать только сам код для построения модели и использовать только информацию о docblock для дополнения элементов, которые она уже видит в коде.

Использование тега «var» является единственным способом документировать ваши «закодированные» свойства. Если вы хотите минимизировать количество строк, необходимых для использования этого тега во всех свойствах, используйте однострочный докблок: 

/** @var int */
public $id;

Кроме того, вы можете использовать шаблон docblock для сокращения docblocks, где сходство тегов соответствует вашему коду: 

/** @var string */
public $name;

/**#@+ @var int */
public $id;
public $number;
/**#@-*/

Это не похоже на большую экономию в этом коротком списке, но это помогает, когда есть много свойств. Кроме того, он хорошо работает вокруг методов.

3 голосов
/ 24 января 2012

Я предпочитаю использовать @var над каждым свойством, а не @property вообще. Я чувствую, что это позволяет вам более тесно связать комментарии с тем, что комментируется. То есть, комментарии к недвижимости всегда находятся рядом с собственностью. Если вы используете стиль @property и у вас большой класс с кучей свойств, вполне возможно, что комментарий, описывающий свойство, находится на расстоянии от него страниц.

1 голос
/ 24 января 2012

Я не уверен в точном синтаксисе, но уверен, что netbeans будет придерживаться стандартной документации php.

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html http://www.phpdoc.org/

...