Статьи

Нет причин не переходить на DocBlox

Январь 7, 2019
Алессандро Надалин сообщает об этих трех вариантах генерации документации Api, процессе извлечения информации Api о классах и методах из папки, полной исходного кода:

  • phpDocumentor основан на PHP 4 и больше не разрабатывается (последний выпуск был в 2008 году). Это старая добрая команда phpdoc .
  • doxygen — это зрелый выбор, который поддерживает многие языки, и он не написан на PHP (с некоторыми взломами он поддерживает даже JavaScript).
  • DocBlox — активно разработанный PHP-совместимый инструмент. Он уже используется в Zend Framework и Agavi. Это было сделано Mike Van Riel, голландским разработчиком PHP, с которым я познакомился на последнем DPC, где он проводил доклад DocBlox на Uncon.

Инструмент PHP, более быстрый, чем doxygen в реализации новых функций, и активно развивающийся: именно эти факторы заставили меня выбрать DocBlox в качестве моей новой документации по API Api по умолчанию.

Установка

Требования к DocBlox — это PHP 5.3 с включенным расширением XSL. Дополнительные расширения потребуются для дополнительных функций, таких как графики.

sudo apt-get install php5-xsl   # in Debian-based Linux distributions
sudo pear channel-discover pear.docblox-project.org
sudo pear channel-discover pear.michelf.com    # some dependencies
sudo pear install docblox/DocBlox-beta

На момент написания этой статьи DocBlox 0.13.3 будет установлен этими командами.

Особенности (из документов)

Производительность — одно из ключевых преимуществ DocBlox. Он анализирует Zend Framework (версия 1.1 в этом тесте) менее чем за 90 секунд; он имеет низкое использование памяти (<50 МБ) и реализует инкрементальный анализ, получая доступ только к измененным файлам с момента последнего выполнения. На небольшом проекте это невероятно быстро.

DocBlox поддерживает PHP 5.3: пространства имен распознаются; области видимости и другие конструкции PHP 5 используются по умолчанию.

Пользовательский интерфейс, созданный DocBlox, содержит поиск JavaScript и позволяет создавать независимые темы и шаблоны: несколько скинов и несколько макетов. Он имеет поддержку пользовательских реализаций Writer для преобразования синтаксической структуры XML в нечто отличное от HTML.

демонстрация

Демонстрация DocBlox’s own показывает, что пользовательский интерфейс более продвинутый и современный, чем старый шаблон phpDocumentor earthli .

Вы также можете увидеть пример реального кода, взглянув на документацию Api Zend Framework .

Пробовать

mkdir apidocs
docblox run -d . -t apidocs

Для базового варианта использования вот оно: проанализируйте текущую папку, выбрав только файлы PHP, и получите результат в папке apidocs /.

Вы можете сохранить команду в цели Phing или ввести файл docblox.dist.xml для хранения конфигурации:

<?xml version="1.0" encoding="UTF-8" ?>
<docblox>
    <parser>
        <target>apidocs</target>
    </parser>
    <transformer>
        <target>apidocs</target>
    </transformer>
    <files>
        <directory>.</directory>
    </files>
</docblox>

Имея этот файл на месте, вы можете просто запустить docblox в папке, в которой он находится.

Пользовательский интерфейс

Тема по умолчанию, которая, кстати, будет использоваться большинством проектов, достаточно удобна и красива. Это показывает:

  • список классов и файлов слева.
  • C / I иконки разных цветов для классов и интерфейсов.
  • п / м иконки для свойства и методы.
  • Круги разного цвета (от зеленого до красного) для сферы от частного до публичного

Навигация по JavaScript работает, даже если она не подается с HTTP-сервера, а просто как папка, загруженная в браузер. Однако для поиска JavaScript требуется, чтобы документы Api загружались через HTTP с веб-сервера с поддержкой PHP (виртуальный хост в вашей локальной конфигурации Apache сделает это).

Без каких-либо докблоков, методы списка DocBlox организованы по логике и физическому расположению (класс и файл), их именам и параметрам.

При наличии докблоков все метаданные извлекаются: поля перечисляются с типом и значением по умолчанию; методы со всем их прототипом (параметры с типом и значением по умолчанию, если применимо, и тип возвращаемого самого метода):

Интерфейс имеет складные описания методов для экономии места; одни и те же классы для пакета перечислены на одной странице, загруженной во фрейм, и перемещаются с помощью якорей, что ускоряет время загрузки. Однако из документации Zend Framework я вижу, что это поведение можно изменить, чтобы разбить классы на разных страницах.

Выводы

Нет причин не выбирать docblox в качестве проекта по умолчанию и отказываться от phpDocumentor. Это все еще PHP-инструмент, написанный на PHP и распространяемый с открытой лицензией MIT.

Поддерживаемые теги docblocks абсолютно одинаковы, поэтому единственное, что меняется, — это команда для генерации; поддержка даже улучшена, так как пространства имен правильно определены. Установка доступна через PEAR и проще, чем для phpDocumentor, как для ваших машин разработки, так и для вашего сервера непрерывной интеграции.

DocBlox на GitHub

Документация DocBlox (это документация по инструменту, а не по синтаксису docblock.)

38
Share: