Docblox — система документирования, совместимая с PHP 5.3+

[@zvirusz]

0.14 уже выпущена: www.docblox-project.org/2011/09/release-of-v0-14-0/

Интересный инструмент, спасибо. Попробую у нас внедрить.

[@vaniaPooh]

Я все ждал выхода 0.14, потому что там был счетчик дней, который двигался в обратную сторону. Когда он дошел до нуля я подождал еще несколько часов и опубликовал статью со старой версией. Видимо она вышла чуть позже…

[@demongloom]

Лучше doxygen развивали бы.

[@liaren]

В статье очень не хватает скриншотов.
Ваш К.О.

[@Ceiceron]

И еще не хватает примеров документированного кода. В документации не сразу найти можно.

[@vaniaPooh]

Мне показалось, что фразы «Представляю вам Docblox — новую систему документирования PHP-приложений, развивающую идеи, заложенные во всем известном PHP Documentor'е.» достаточно для того, чтобы читатель понял, что синтаксис абсолютно такой же, как у PHPDocumentor. Разница примерно такая же, как между C и С++ — одно является надмножеством другого.

[@Ceiceron]

Нет проблем. Я не часто работаю с PHP и про автодокументацию кода проекта в на нем только задумывался (в стиле: а как бы хорошо, если бы можно было прокомментировать функцию так же как в MS VS). Т.е. я впервые от вас слышу про PHP Documentor. Естественно желание увидеть в каком стиле это выполнено.

[@ilyaplot]

Вот нашел

[@taliban]

Вам не хватает скриншотов документированного кода?

[@liaren]

Мне не хватает скриншотов в самой статье.

[@taliban]

Скриншотов чего? там про код и его документирование пишут.

[@liaren]

Ну ёмаё…

6. Двухступенчатая генерация документации через промежуточный XML-файл, на основе которого могут генерироваться HTML-страницы.
8. Поддержка тем и шаблонов отображения содержимого
10. Возможность генерирования PDF (требуется дополнительная библиотека wkhtmltopdf, написанная с использованием WebKit для конвертации HTML → PDF)
11. Возможность генерирования UML-подобного графа для каждого класса (требуется Graphviz)

Вот скриншоты всего это дело было бы очень интересно посмотреть в контексте статьи.

[@taliban]

demo.docblox-project.org/

[@vaniaPooh]

На самом деле это моя первая статья, за которую я получил приглашение на Хабр, поэтому при ее написании я пытался более менее следовать правилам из раздела помощь. В частности, там написано что не стоит засорять статью исходным кодом, поэтому я не стал включать слишком много исходников. Генерированный UML, действительно, можно посмотреть на демонстрационной странице. Остальные возможности могу осветить в следующей статье…

[@liaren]

Я не понимаю, что сложно скрины добавить? Чего все должны их сами рученьками искать? Это очень важная информация, куда важнее того же «Примера файла конфигурации».

[@vaniaPooh]

Постараюсь учесть ваши замечания в следующей статье.

[@ilyaplot]

В списке тегов NetBeans давно есть @property-read, @property-write. Видимо из JavaDoc унаследовано.

[@vaniaPooh]

По крайней мере их нет в документации по PHPDocumentor, поэтому я их включит в список.

[@LastDragon]

Есть, они упоминаются в примерах для @property:

/**
* show off @property, @property-read, @property-write
*
* @property mixed $regular regular read/write property
* @property-read int $foo the foo prop
* @property-write string $bar the bar prop
*/

[@2fast4rabbit]

Возможность наследования описания методов в дочерних классах (при добавлении пустого docblock'а описания копируются из родительского класса\интерфейса)

Было бы хорошо если бы описания наследовались без необходимости добавлять пустые блоки.

[@Ar2r]

root@santa:~# pear channel-discover pear.docblox-project.org
Adding Channel "pear.docblox-project.org" succeeded
Discovery of channel "pear.docblox-project.org" succeeded
root@santa:~# pear channel-discover pear.michelf.com
Adding Channel "pear.michelf.com" succeeded
Discovery of channel "pear.michelf.com" succeeded
root@santa:~# pear install DocBlox/DocBlox-beta
No releases available for package "pear.docblox-project.org/DocBlox"
Cannot initialize 'channel://pear.docblox-project.org/DocBlox-beta', invalid or missing package file
Package "channel://pear.docblox-project.org/DocBlox-beta" is not valid
install failed


Что не так?

[@vaniaPooh]

Возможно дело в установленной у вас версии PEAR. Нотацию -beta в конце названия пакета понимают только свежие версии PEAR. У меня стоит версия PHP 5.3.5 из бинарного пакета Ubuntu:

vania-pooh@vania-pooh:~$ pear version
PEAR Version: 1.9.4
PHP Version: 5.3.5-1ubuntu7.2
Zend Engine Version: 2.3.0

[@vaniaPooh]

Если нотация -beta не поддерживается, то можно использовать ключ:

# pear config-set preferred_state beta

[@vaniaPooh]

Я кстати написал новую статью про все, о чем просили, но мне не хватает кармы, чтобы опубликовать ее из черновиков.