Профессиональное программирование на PHP

Страница 41 из 591


Документация 43

Ниже перечислены основные цели API-документации.

Документация должна предоставлять введение, которое позволяет пользователям быстро определить подходит ли пакет или библиотека для решения конкретных задач.

В документации должен быть представлен перечень всех общедоступных классов и функций, а также описание входных и выходных параметров. В документации должны присутствовать учебные материалы или примеры использования, явно демонстрирующие, как использовать данный код.

Полезно также включать в документацию для пользователей следующую информацию:

 Документация защищенных методов;

 Примеры расширения класса в целях добавления функциональности.

Наконец, система API-документации должна предоставлять разработчику, пишущему документируемый код, ряд функций.

 Документация должна быть внутренней для кода. Это полезно для поддержания актуальности документации, а также гарантирует, что документация всегда присутствует.

 Система документации должна иметь простой и удобный синтаксис. Написание документации редко является увлекательным занятием, поэтому его облегчение, насколько это возможно, позволяет гарантировать, что данная работа будет сделана.

 Должна быть система для создания форматированной документации. Это означает, что документация должна легко отображаться в профессиональном и простом для чтения формате.

Можно выбрать создание собственной системы для управления АР1-документаиией, а можно использовать существующий пакет. Центральная тема в данной книге — научить не изобретать колесо. В случае внутренней документации проект phpDocumentor выполнил значительную работу по созданию инструмента, который удовлетворяет всем перечисленным требованиям, поэтому нет причины искать другое подобное средство. Прообразом проекта phpbocumentor в значительной степени послужил пакет JavaDoc, система автоматического документирования для Java-проектов.

Использование phpDocumentor

Пакет phpDocumentor выполняет свои функции путем синтаксического анализа специальных комментариев в коде. Все блоки комментариев принимают следующую форму:

/**

* Краткое описание *

* Подробное описание

* ©теги

*/




  Hostland.Ru

 «Бесплатный хостинг Hostland.Su» © 2006