Как использовать PHPdoc в Eclipse - PullRequest
Новая
       20

Как использовать PHPdoc в Eclipse

3 голосов
/ 21 февраля 2010

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

Я попытался выяснить, как лучше всего использовать phpDoc в Eclipse, но с довольно скудными результатами.

Можете ли вы поделиться своими лучшими практиками и приемами использования phpDoc для комментирования вещей в Eclipse?

Ответы [ 2 ]

9 голосов
/ 21 февраля 2010

Не существует "реального стандарта" в отношении того, что следует комментировать и как, но некоторые теги используются в значительной степени теми, кто комментирует его код.

Например, я обычно использую по крайней мере:

  • краткое описание
  • опционально, длинное описание
  • @param type name description: для параметров функций / методов
  • @returns type: для возвращаемого значения функций / методов
  • @throws ExceptionType: если функции / методы выдают исключение при некоторых обстоятельствах
  • @see ... : когда я хочу сделать ссылку либо на другой файл, либо на URL, который дает больше информации
  • в зависимости от структуры проекта, я также могу использовать @package и @subpackage
  • Еще одно замечательно, когда у вас есть магические свойства в классе (они не могут быть видны вашей IDE, поскольку они написаны в коде) - это @property type $name: это позволяет Eclipse PDT делать авто - даже на магические свойства - например, Doctrine использует это.

Большинство из них используются Eclipse PDT, чтобы помочь вам при кодировании (особенно @param) ; но не стесняйтесь добавлять некоторые, которые не используются Eclipse PDT: если вы генерируете документацию из своего кода, это всегда может быть полезно; -)


Лучший совет, который я могу вам дать, это взглянуть на исходный код некоторых крупных приложений и / или фреймворков (Zend Framework, Doctrine, ...) , чтобы увидеть, как комментируется их код. - Скорее всего, они используют что-то, что хорошо принято.

Например, если вы посмотрите на код Zend Framework, вы можете найти такие вещи для класса: 

/**
 * @package    Zend_Cache
 * @subpackage Zend_Cache_Backend
 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license/new-bsd     New BSD License
 */
class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface

И вот так для метода: 

/**
 * Test if a cache is available for the given id and (if yes) return it (false else)
 *
 * WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend
 *
 * @param  string  $id                     cache id
 * @param  boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested
 * @return string cached datas (or false)
 */
public function load($id, $doNotTestCacheValidity = false)


В любом случае, самое важное - быть последовательным: каждый член вашей команды должен комментировать одинаково, придерживаться тех же правил.

1 голос
/ 26 февраля 2010

Как минимум, я бы хотя бы придерживался того, какие минимальные теги phpdoc автоматически вставляются Eclipse на основе вашего кода.

Вторым минимальным уровнем, к которому я бы стремился, было бы удовлетворение самого PhpDocumentor. Как только вы запустите PhpDocumentor для своего кода, поищите страницу errors.html в корневом каталоге ваших документов. Это перечислит все, что не нравится PhpDocumentor, например, отсутствие докблоков на уровне файлов. Вы можете попытаться свести этот список ошибок к нулю.

Третий уровень, к которому вы могли бы стремиться, - это удовлетворение любого из стандартов кодирования, включенных в приложение PHP_CodeSniffer в PEAR [1]. Недостатком здесь является то, что эти стандарты более конкретно ориентированы на сам код, но все стандарты включают в себя правила, касающиеся документации кода.

[1] - http://pear.php.net/package/PHP_CodeSniffer

...