Урок - Знакомство с документированием phpDoc

Главная » Курсы » Курс Документирование PHP-кода » Урок - Знакомство с документированием phpDoc

Обучающий онлайн курс
Документирование PHP-кода

Лицензия: Копирование запрещено.
↑ Документирование PHP-кода
  Урок - Знакомство с документированием phpDoc  
Текущий урок - первый.   Следующий урок →
Урок - Создание документации

Комментарии – важная часть PHP кода. Комментарии должны быть:

  • Полными
  • Точными
  • Актуальным

PHPDoc (он же PHPDocumentor) — приложение(точнее скрипт) позволяющие генерировать документацию основанную на PHPDoc-комментариях. PHPDocumentor предложил формальный стандарт для комментирования PHP кода, который используется для автоматической генерации документации в HTML, man, RTF и XML, CHM, PostScript, PDF. Сайт PHPDoc.

PHPDoc-комментарий (или Doc-комментарий, илиDoc-блок) - специальный многострочный комментарий, информация из которого будет использоваться для формирования документации.

В php есть два вида комментариев:

  • // - однострочный коментарий.
  • /* .. */ - многострочный коментарий.

Однострочные комментарии имеет смысл оставлять внутри кода. Однострочне комментарии ставятся на строке перед комментируемым блоком кода.

// проверка на действительность
// пользователя
if ($user->is_active && $user->registered_at == '01-01-2001') {
	...
}

Знакомство с PHPDoc

В основе работы phpdocumentor лежит разбор логической структуры PHP кода (классов, функций, переменных, констант) и привязка к ней комментариев, написанных по определенным стандартам.

Для начала приведем пример Doc-комментария:

/**
 * Это блок комментариев PHPDoc
 */
function f1(){
	//...
}

Обратите внимание, что в начале идет /** наклонная черта и две звездочки. Это важно. Таким образом генераторы документации понимают, что далее идет DOC-комментарий а не просто комментарий заключенный в /* .. */

Хотя это и не обязательно, каждую строку в блоке комментариев /** ... */ обычно начинают с сим­вола звездочки (*), иногда пробел и символ звездочки. В основном это делается для улучшения читаемости.

Внутри DOC-комментария некоторые слова приобретают дополнительное специальное значение. Такие слова называются тегами и начинаются с символа "@" (комерческое а). Пример нескольких тегов: @access, @author, @package, @param, @return, @since, @var, @version... Теги позволяют указать дополнительную информацию: какие параметры принимает функция и какого типа переменную она возвращает, но и связать комментарии и другие полезные данные с объектами, функциями и переменными.

В первой строке DOC-комментария дается краткое описание.

Если нужно дополнительное описание функционала - делается отступ в одну строку.

Следующий раздел DOC-комментария (необязательно) — это более развернутое описание. Здесь необходимо описать комментируемый элемент с точки зрения их внешнего использования, — т.е. не как они устроен, а что кон­кретно делает. Подробные описания устройства должны вестись внутри кода, а не в DOC-комментарии.

Добавляем пустую строку и далее описание ведем с помощью PHPDoc-тегов.

PHPDoc-комментарии могут содержать HTML-разметку из тегов:

  • <b> — жирное начертание;
  • <code> — код;
  • <br> — разрыв строки;
  • <i> — курсив;
  • <kbd> — сочетание клавиш;
  • <li> — элемент списка;
  • <ol> — нумерованный список;
  • <p> — абзац;
  • <pre> — форматированный текст;
  • <samp> — пример;
  • <ul> — маркированный список;
  • <var> — имя переменной.
/**
 * Краткое описание
 * 
 * Полное описание
 * <ul>
 * 	<li>Пункт 1
 * 	<li>Пункт 2
 * </ul>
 */

и Wiki-разметку:

/**
 * Краткое описание
 * 
 * Полное описание
 * * Пункт 1
 * * Пункт 2
 */

PHPDoc-комментариями необходимо сопровождать:

  • Файлы
  • Классы
  • Свойства классов
  • Константы классов
  • Методы классов
  • Константы
  • Функции
↑ Документирование PHP-кода
  Урок - Знакомство с документированием phpDoc  
Текущий урок - первый.   Следующий урок →
Урок - Создание документации