Для ActionScript 2 я использовал NaturalDocs . Однако он очень плохо поддерживает PHP. Я так долго смотрел на Doxygen и phpDocumentor , но их вывод довольно уродлив, на мой взгляд. Есть ли у кого-нибудь опыт создания автоматической документации для PHP? Я бы предпочел использовать ярлыки в стиле javadoc, они короткие, чтобы писать и легко запоминать.
ApiGen поддерживает поддержку пространств имен, пакетов, связей между документацией, перекрестных ссылок на стандартные классы PHP и общей документации, создания выделенного исходного кода и экспериментальной поддержки для PHP 5.4.
http://www.docblox-project.org/
PHP 5.3 совместимый генератор документации API, предназначенный для проектов любого размера и непрерывной интеграции.
способный полностью анализировать и преобразовывать Zend Framework 2
Существует два хорошо известных и часто используемых инструмента, которые могут генерировать API doc из docblocks:
О «руководящих принципах»: я бы сказал, это зависит от ваших проектов, но, по крайней мере, я бы ожидал увидеть:
@param type name description of the parameter @return type description of the return value возвращаемого значения @return type description of the return value @throws type description of the exception that can be thrown Замечательно, что недавняя IDE (например, Eclipse PDT , например) может читать и интерпретировать эти маркеры, чтобы давать подсказки, когда вы кодируете 😉
Кроме того, есть все больше и больше PHP-инструментов, которые используют php docblocks для какой-то другой цели, чем документация.
Например, PHPUnit позволяет вам указать некоторые связанные с тестированием вещи, используя некоторые определенные теги – см. Аннотации .
PHPDoc, вероятно, так же хорош, как вы его получите с точки зрения встроенного комментария Javadoc. Вы также можете посмотреть на PHPXRef .
Да, phpDocumentor ( http://www.phpdoc.org/ ) является приемлемым стандартным инструментом для автодоков PHP. Это де-факто стандарт.
Для документирования PHP-кода допустимо следовать общим правилам JavaDoc для кода. Тем не менее, вы столкнетесь с ситуациями, когда этого недостаточно, потому что PHP и Java – это разные языки.
Например, функции PHP не имеют типа возврата и неизбежно (а иногда и желательно) для функции возвращать один тип с одним контекстом, а другой тип – во втором контексте. Рекомендации JavaDoc не помогут в этом, потому что это невозможно сделать на Java.
Проверьте PHPDoctor http://peej.github.com/phpdoctor/ , простые, но в то же время функциональные возможности Javadoc clone для PHP.
phpDocumentor может выводиться в стиле, подобном документации php.net (и встроенной в нее как с малым, так и с немасштабированным макетом)
Кодовая база WordPress документирована с использованием тегов phpdoc (см. Это ), и это в целом довольно хорошо – она отображается здесь с помощью phpDocumentor .
Большая часть кода, который я пишу, настолько существенна, что мне нужно подумать об автогенерирующих документах, делается в .Net, поэтому я не могу дать большую часть перспективы писателя документации, хотя
Если уродливая проблема, я бы просто переключил таблицу стилей для пользовательской. Если вы не хотите перезаписывать сгенерированный, вы можете использовать плагин Firefox, например Stylish .
Вы можете отредактировать файл шаблона, чтобы добавить свою собственную таблицу стилей, чтобы переопределить существующую.