phpDocumentor
v3.5.3
phpDocumentor является де-факто инструментом документации для PHP-проектов, предлагая надежное решение для легкого создания полной документации. Анализируя исходный код PHP и комментарии DocBlock, phpDocumentor генерирует полный набор документации API, что делает его незаменимым инструментом для разработчиков, стремящихся к понятным и хорошо документированным базам кода.
Помимо своего мастерства в документации API, phpDocumentor идет дальше, предоставляя дополнительные функции. Он оснащен возможностью создания UML-диаграмм, что делает его универсальным инструментом для визуализации структуры кода. Кроме того, phpDocumentor предлагает полнофункциональный анализатор языка разметки, поддерживающий синтаксис RestructuredText и Markdown. Эта гибкость позволяет вам документировать свой проект, используя язык разметки, который лучше всего соответствует вашим предпочтениям.
Примечательной особенностью phpDocumentor является его способность включать части документации API непосредственно в документацию RestructuredText. Такая интеграция гарантирует синхронизацию вашей документации и кода, что экономит ваше время и усилия по поддержанию точной и актуальной проектной документации.
Вдохновленный своими предшественниками, phpDocumentor 1 и JavaDoc, phpDocumentor продолжает внедрять инновации, оставаясь в курсе новейших технологий и функций языка PHP. Это обязательство гарантирует разработчикам доступ к наилучшей документации, соответствующей современным практикам разработки.
В этом руководстве мы рассмотрим различные функции phpDocumentor, от его основных функций по созданию документации API до расширенных возможностей анализа языков разметки. Независимо от того, являетесь ли вы новичком или опытным разработчиком, phpDocumentor — ваш союзник в создании хорошо документированных, удобных в сопровождении и понятных PHP-проектов.
v3 — последняя стабильная версия.
Для получения более подробной информации вы можете просмотреть нашу онлайн-документацию по адресу https://docs.phpdoc.org/.
phpDocumentor поддерживает следующее:
Совместимость с PHP 7.0+ , полная поддержка пространств имен, замыканий и многого другого.
Docblock по типам , docblocks может быть более подробным в отношении типов, не все форматы поддерживаются собственным php.
Показывает любой тег , некоторые теги добавляют дополнительные функции в phpDocumentor (например, @link).
Низкое использование памяти . Пиковое использование памяти для небольших проектов составляет менее 20 МБ, для средних проектов — 40 МБ, для больших платформ — 100 МБ.
Инкрементный анализ : если вы сохранили файл структуры из предыдущего запуска, вы получаете дополнительный прирост производительности до 80% помимо упомянутого выше увеличения скорости обработки.
Легкое создание шаблона , если вы хотите сделать брендинг, вам нужно всего лишь вызвать 1 задачу и отредактировать 3 файла.
Двухэтапный процесс : phpDocumentor сначала генерирует кеш со структурой вашего приложения, прежде чем создавать выходные данные. Если хотите, вы можете использовать это для создания своих собственных инструментов или форматтеров!
Поддержка дженериков , статический анализ типов php стал более сложным. phpDocumentor понимает эти типы. И будет отображать их как первоклассные типы.
Для работы PhpDocumentor требуется PHP 8.1 или выше. Однако код более ранних версий PHP можно проанализировать.
Все шаблоны, поставляемые с phpDocumentor, поддерживают диаграммы классов на основе прочитанной базы кода. Для этого потребуется установить приложение [PlantUml] на компьютере, на котором работает phpDocumentor. Отрисовка диаграмм классов с использованием [PlantUml] не является обязательной, а предупреждения об отсутствии [PlantUml] можно игнорировать. Однако в этом случае ваша документация будет содержать несколько неработающих ссылок. Диаграмма классов будет создана с опцией --setting=graphs.enabled=true .
Существует 4 способа установки phpDocumentor:
Использование phive (рекомендуется)
Использование PHAR (установка вручную)
Через Докер
Через композитор
$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42
Для получения дополнительной информации о phive посетите их веб-сайт. Теперь у вас установлен phpDocumentor, его можно запустить следующим образом:
php tools/phpDocumentor
Загрузите файл phar с https://github.com/phpDocumentor/phpDocumentor/releases.
Вы можете выполнить phar следующим образом: php phpDocumentor.phar
$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc
Но подождите? А что насчет композитора?
Ах, вы открыли нашу тайну. Существует пакет композитора phpdocumentor, который вы можете использовать для установки phpDocumentor.
Однако: phpDocumentor — сложное приложение, и его библиотеки используются в бесчисленном множестве других библиотек и приложений (каждая из двух наших библиотек имеет более 150 миллионов загрузок); а это означает, что вероятность конфликта между одной из наших зависимостей и вашей высока. И когда я говорю «высоко», это действительно высоко.
Итак, из-за вышесказанного: мы не одобряем и не поддерживаем установку phpDocumentor с помощью Composer.
Самый простой способ запустить phpDocumentor — выполнить следующую команду:
$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>
Эта команда проанализирует исходный код, предоставленный с использованием аргумента -d , и выведет его в папку, указанную аргументом -t .
phpDocumentor поддерживает целый ряд опций для настройки вывода вашей документации. Вы можете выполнить следующую команду или посетить наш веб-сайт для получения более подробного списка доступных параметров командной строки.
$ phpdoc run -h
phpDocumentor также поддерживает использование файлов конфигурации (по умолчанию называемых phpdoc.xml или phpdoc.dist.xml). Пожалуйста, обратитесь к документации, чтобы увидеть формат и поддерживаемые параметры.
PhpDocumentor не выпускает ночные выпуски. Однако в ходе каждого конвейера создается артефакт phar. Если вы хотите протестировать новейшую версию phpDocumentor, загляните в раздел действий этого репозитория. Внизу каждого успешного рабочего процесса контроля качества есть раздел «Артефакты», в котором создан артефакт phar.
Обратиться к нам легко и это можно сделать с помощью:
Твиттер: @phpDocumentor
Сайт: https://www.phpdoc.org.
GitHub: https://www.github.com/phpDocumentor/phpDocumentor
Электронная почта: [email protected].
