Каков предпочтительный способ отметить методы в комментариях?

Question

Иногда нужно ссылаться на другой метод при комментировании. Вот несколько примеров в PHP:

class A
{
    /**
     * @see B::bar
     */
    public function foo()
    {
        B::bar();
    }
}

class B
{
    public static function bar()
    {
        // ...
    }
}

Так что, если в классе B будет нестатический метод bar? Как лучше всего назвать другие методы в комментариях?

Редактировать

В руководстве по PHP, похоже, используется mysqli->affected_rows, а также PDO::beginTransaction. Но он не включает в себя скобки после имени метода. Что здесь за и против? Я имею в виду, что совершенно очевидно, что за методом следуют круглые скобки, так почему бы не оставить их?

Спасибо заранее!

Answer 1

Вы можете использовать оператор -> для ссылки на метод экземпляра / объекта, а не на метод класса. PHP.net также делает это в своем руководстве (см. MySQLi class ).

Answer 2

На мой взгляд, вашего примера достаточно. Вы должны ссылаться на B :: bar как B :: bar ().

Возможно, вы захотите использовать @, использующий тег php-doc , который автоматически создаст ссылку @usedby в документации, сгенерированной для B :: bar (), указывая на класс A.

/**
 * @uses B::bar()
 */

Что касается документации, то метод, который является статическим, не относится к @uses, @usedby или @see, только к @static. Статическая нотация в теге @uses просто сообщает область, в которой нужно искать метод bar (), а не обозначает @ static.

Answer 3

Я бы написал:

class A {
    // see B::bar()
    public function foo() {
        B::bar();
    }
}

Мое самое решительное мнение относительно моих различных изменений заключается в том, что комментарии к почтовому ящику - работа Дьявола. Что касается ваших статических и нестатических вещей, я понимаю и использую B::bar() для ссылки на определение функции в диалоговых целях, независимо от того, является ли bar() статическим.

Приведенный выше пример, конечно, только для иллюстративных целей, потому что если бы на самом деле была функция A::foo(), которая ничего не делала, кроме вызова B::bar(), я бы не включил комментарий, потому что, если человек, читающий мой код, идиот, я не хочу ему помогать.

Answer 4

Документация для phpDocumentor, кажется, подразумевает, что вы можете использовать что-то вроде

class A
{
  /**
   * @see B
   * @see function bar()
   */
  public function foo()
  {
    // ...
  }
}

Также из руководства phpDocumentor :

@ использует очень похоже на @see, см. документация для @ смотри подробности формат и структура. Тег @uses отличается от @see в двух отношениях. @ см. односторонняя связь, означающая документация, содержащая тег @see содержит ссылку на другие документация. Тег @uses автоматически создает виртуальный тег @usedby в другой документации что ссылки на документацию содержащий тег @uses. В других слова, это точно так же, как @see, за исключением обратная ссылка добавляется автоматически.