Для ActionScript 2 я использовал NaturalDocs. Однако у него довольно слабая поддержка PHP. Я до сих пор смотрел на doxygen и phpDocumentor, но их вывод довольно уродлив, на мой взгляд. У кого-нибудь есть опыт автоматической генерации документации на PHP? Я бы предпочел использовать теги в стиле javadoc, они короткие и легко запоминаются.
Автоматическое создание документации PHP?
Ответ 1
ApiGen
ApiGen имеет поддержку пространств имен, пакетов, связей между документами, перекрестных ссылок на стандартные классы PHP и общей документации, создания выделенного исходного кода и экспериментальной поддержки для характеристик PHP 5.4.
DocBlox
http://www.docblox-project.org/
PHP 5.3 совместимый генератор документации API, предназначенный для проектов любого размера и непрерывной интеграции.
способен полностью анализировать и преобразовывать Zend Framework 2
Ответ 2
Есть два хорошо известных и часто используемых инструмента, которые могут генерировать API doc из docblocks:
- phpDocumentor, который специфичен для PHP, и, вероятно, является одним из наиболее используемых инструментов для проектов PHP.
- и Doxygen, что больше для C, но используется некоторыми PHP для PHP.
О "руководящих принципах": я бы сказал, это зависит от ваших проектов, но, по крайней мере, я бы ожидал увидеть:
- описание того, что делает метод/функция
-
@param type name description of the parameter - возвращаемое значение,
@return type description of the return value - с
@throws type description of the exception that can be thrown
Замечательно, что недавняя IDE (например, Annotations.
Ответ 3
PHPDoc, вероятно, так же хорош, как вы его получите с точки зрения встроенного комментария Javadoc. Вы также можете посмотреть PHPXRef.
Ответ 4
Да, phpDocumentor (http://www.phpdoc.org/) является приемлемым стандартным инструментом для автодоков PHP. Это де-факто стандарт.
Допустимо следовать общим правилам JavaDoc для кода при документировании кода PHP. Однако вы столкнетесь с ситуациями, когда этого недостаточно, потому что PHP и Java - это разные языки.
Например, функции PHP не имеют типа возврата и неизбежно (а иногда и желательно) для функции возвращать один тип с одним контекстом, а другой тип - во втором контексте. Рекомендации JavaDoc не помогут в этом, потому что это невозможно сделать на Java.
Ответ 5
phpDocumentor может выводиться в стиле, подобном документации php.net(и встроен в нее как с малым, так и с немасштабированным макетом)
Ответ 6
Откроется PHPDoctor http://peej.github.com/phpdoctor/, простые, но полные функции Javadoc clone для PHP.
Ответ 7
Кодовая база Wordpress документирована с использованием тегов phpdoc (см. this), и это в целом довольно хорошо - оно получило здесь, используя phpDocumentor.
Большая часть кода, который я пишу настолько существенным, что мне нужно подумать об автогенерирующих документах, выполняется в .Net, поэтому я не могу дать большую часть документации, связанной с документацией, хотя
Ответ 8
Если уродливая проблема, я бы просто переключил таблицу стилей для пользовательской. Если вы не хотите перезаписывать сгенерированный, вы можете использовать плагин Firefox, например Стильный.
Ответ 9
Вы можете отредактировать файл шаблона, чтобы добавить свою собственную таблицу стилей, чтобы переопределить существующую.