Автоматическое создание документации PHP?
Для ActionScript 2 я использовал NaturalDocs. Однако у него довольно плохая поддержка PHP. Я до сих пор смотрел на доксиген и phpDocumentor, но их результат, на мой взгляд, довольно уродливый. Есть ли у кого-нибудь опыт автоматической генерации документации для PHP? Я бы предпочел использовать теги в стиле javadoc, они короткие и легко запоминаются.
Ответы 9
Если уродливая проблема, я бы просто переключил таблицу стилей на другую. Если вы не хотите перезаписывать сгенерированный, вы можете использовать плагин Firefox, например Стильный.
phpDocumentor может выводить в стиле, аналогичном документации php.net (и он встроен в макеты smarty и non smarty)
Вы можете отредактировать файл шаблона, чтобы добавить свою собственную таблицу стилей, чтобы заменить существующую.
Есть два хорошо известных и часто используемых инструмента, которые могут генерировать документацию API из docblocks:
- phpDocumentor, который специфичен для PHP и, вероятно, является одним из наиболее часто используемых инструментов для проектов PHP.
- и Doxygen, который больше подходит для C, но используется некоторыми людьми для 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 (например, Затмение PDT) может читать и интерпретировать эти маркеры, чтобы давать подсказки при кодировании ;-)
Кроме того, появляется все больше и больше инструментов PHP, которые используют php docblocks для других целей, кроме документации.
Например, PHPUnit позволяет вам указывать некоторые вещи, связанные с тестами, используя некоторые специальные теги - см. Аннотации.
Спасибо за очень обстоятельный ответ. В частности, это соответствует тому, что я привык писать для JavaScript (динамически типизированные переменные и параметры), поэтому, учитывая, что я не настолько ограничен, я выберу то, к чему я привык.
PHPDoc, вероятно, так же хорош, как и вы, с точки зрения встроенного комментирования в стиле Javadoc. Вы также можете посмотреть PHPXRef.
PHPXRef не обновлялся с 2010 года.
@Moak ответ был дан в 2009 году ...
По-прежнему приятно отметить это для людей, посещающих сегодня, чтобы они знали об этом. @ItrysohardbutIcryharder
Кодовая база Wordpress документируется с использованием тегов phpdoc (см. это), и в целом она довольно хороша - она отображается здесь с использованием phpDocumentor.
Большая часть кода, который я пишу, достаточно существенный, чтобы мне нужно было подумать об автогенерировании документации, сделана в .Net, поэтому я не могу дать большую часть точки зрения автора документации, хотя
Да, phpDocumentor (http://www.phpdoc.org/) - приемлемый стандартный инструмент для автодокументов PHP. Это стандарт де-факто.
При документировании кода PHP допустимо следовать общим руководящим принципам JavaDoc для кода. Однако вы столкнетесь со случаями, когда этого будет недостаточно, потому что PHP и Java - разные языки.
Например, функции PHP не имеют возвращаемого типа, и для функции неизбежно (а иногда и желательно) возвращать один тип с одним контекстом, а другой тип с другим контекстом. Руководства JavaDoc в этом не помогут, потому что это невозможно сделать на Java.
Спасибо за подкрепление. Иногда я ожидаю, что PHP будет немного меньше похож на язык сценариев, но чем больше я его использую, тем больше похоже на серверный компонент сценариев JavaScript, который я обычно пишу.
Хотя ваш пример действителен, вообще говоря, если java что-то не позволяет, а php делает, я бы попытался сопоставить то, что рекомендует java, и не делать этого на php, хотя я мог бы ...
Ознакомьтесь с PHPDoctor http://peej.github.com/phpdoctor/, простым, но полным функционалом клона Javadoc для PHP.
ApiGen
ApiGen поддерживает пространства имен PHP 5.3, пакеты, связь между документацией, перекрестные ссылки на стандартные классы PHP и общую документацию, создание выделенного исходного кода и экспериментальную поддержку особенностей PHP 5.4.
DocBlox
http://www.docblox-project.org/
Генератор документации API, совместимый с PHP 5.3, предназначенный для проектов любого размера и непрерывной интеграции.
способен полностью анализировать и преобразовывать Zend Framework 2
Я хотел бы упомянуть, что DocBlox - это то же самое, что и phpDocumenter в приведенном ниже ответе. Из 3, это единственный, который не перепутал пространства имен, но, возможно, я просто чего-то не понимаю и у меня поздно ночью пукнет мозг. ;)
ApiGen - нет-нет, если вы используете кое-что из php 5.6 или 7. Они собираются выпустить 4.2, поэтому я надеюсь, что они решат проблемы ... потому что мне нравится их макет.
Я никогда раньше не использовал docblox, но я пробовал apigen и phpdocumentor, apigen - единственный (который я когда-либо пробовал), который может генерировать документ без раскрытия исходного кода, и его сгенерированный документ очень прост для понимания.
Это отличный вариант, но имейте в виду, что файлы, содержащие признаки или декларацию типа возврата или аргумента php7, пропускаются текущей версией (2.9.0).