Использование Doxygen для документирования PHP кода

 
doxygen.png

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

Элегантное решение этой задачи давно есть. Заключается оно в документировании вашего кода непосредственно в исходном коде - в комментариях.

Doxygen одиз из нескольких программных продуктов, который позволяет на основании комментариев кода выполненных по незамысловатым правилам сгенерировать документацию в нескольких форматах. Для нас интерес представляет документация в формате HTML.

Подготовка

На Ubuntu он устанавливается из репозитория.

sudo apt-get install doxygen

Предположим ваш проект называется project, тогда gecnm он расположен в каталоге project. Создайте в названном каталоге вложенный для документации - docs.
В этом каталоге можно будет находиться сгенерированная документация и конфиг о котором речь ниже.

Конфигурация

Создайте в подготовленном каталоге конфиг Doxyfile.

doxygen -g

Эта команда создаст в текущем каталоге стандартный конфигурационный файл Doxyfile с коммантериями. Если комментарии вам не нужны, то добавьте опцию -s.

Опции конфигурации

PROJECT_NAME           = "My Project"

Название вашего проекта.

PROJECT_NUMBER         = 0.1-beta1

Версия

PROJECT_BRIEF          = "Very flexible and usable utility"

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

OUTPUT_DIRECTORY       =

Каталог для готовой документации (текущий по-умолчанию)

OUTPUT_LANGUAGE        = Russian

Язык неизменного содержимого

FULL_PATH_NAMES        = NO

Указывает на необходимость создания относительных путей в ссылках готовой документации.

JAVADOC_AUTOBRIEF      = YES

Позволяет избегать упоминания наиболее часто используемого символа @brief, а следовать соглашению о том, что первая строка в блоке комментария и есть короткое описание (подробнее ниже в описании символов)

ALWAYS_DETAILED_SEC    = YES

Обычно doxygen если находит в комментарии ф-ции только короткое описание, то он не генерирует подробностей, а только фиксирует эту функцию. Иными словами при наличии только короткого описания вы не получити информации об определении ф-ции, её параметрах и возвращаемого значения.
Установив эту опцию в YES вы заставите doxygen создавать документацию для всех ф-ций без исключения.

EXTRACT_PRIVATE        = YES

Создавать документацию для приватных членов классов

WARN_NO_PARAMDOC       = YES

Предупреждать об отсутствии документации для параметров и возвращаемого значения ф-ции.

INPUT                  = ../

Путь к корневому каталогу исходного кода проекта

RECURSIVE              = YES

Произвести рекурсивный обход каталогов при генерации документации

EXCLUDE                = .git \
                                   .svn

Пути, которые необходимо исключить при обходе

EXCLUDE_PATTERNS       = */.git/* \
                                             */tmp/*

Регулярные выражения, по которым следует исключить пути при обходе

SOURCE_BROWSER         = YES

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

INLINE_SOURCES         = YES

Добавить код определения функции непосредственно к описанию.

STRIP_CODE_COMMENTS    = NO

Указывает следует ли вычищать из копируемого в документацию кода комментарии

GENERATE_LATEX         = NO

Отказаться от документации в формате LaTeX.

Документирование кода

Для документирования кода вам не требуется ничего более кроме следования нескольким простым соглашениям относительно того как строить комментарии к коду. Гораздо сложнее привыкнуть к самой необходимости такие комментарии оставлять =)

Для информирования doxygen о том, что в вашем комментарии относится к той или иной сущности используются специальные ключевые слова. Здесь предлагается вариант принятый среди разработчиков CMF Drupal. Но на самом деле вы можете использовать и другой удобный для вас синтаксис. Предваряются такие ключевые слова некоторым специальным символом. В предложенном варианте это @.

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

Наиболее часто употребляемые ключевые слова

brief — Короткое описание сущности (ф-ции, класса, константы).
При включенной опции JAVADOC_AUTOBRIEF может быть опущена. Тогда описанием считается первая строка в блоке комментария. Далее через пробел может следовать многострочное более подробное описание логики работы функции.
В подробном описании может применяться дополнительная разметка MARKDOWN.
NB: Кратким описанием также считается первое предложение комментария (до первой точки).

  /**
   * Краткое описание ф-ции.
   *
   * Развёрнутое и подробное
   * описание работы
   * ф-ции
   */

  function exampleFunction($example_param) {
    // do something...
  }

param — Указывает на описание параметра. Сразу после следуют название типа и имя параметра. На следующей строке - описание.

  /**
   * Краткое описание ф-ции.
   *
   * @param int $example_param
   *   Некоторый параметр
   */

  function exampleFunction($example_param) {
    // do something...
  }

return — Возвращаемое значении ф-ции.

  /**
   * Краткое описание ф-ции.
   *
   * @param int $example_param
   *   Некоторый параметр
   * @return string Описание возвращаемого значения
   */

  function exampleFunction($example_param) {
    // do something...
    return "example string";
  }

file — Описание файла исходного кода. Обычно располагается в самом начале файла.

#!/usr/bin/env php
<?php

/**
 * @file
 * Главный файл проекта.
 */

author — Автор кода

  /**
   * Краткое описание ф-ции.
   * @autor Василий Пупкин
   */

  function exampleFunction($example_param) {
    // do something...
  }

todo — Запланированные изменения.
NB: Не стоит пренебрегать этой возможностью так как doxygen упорядочит эти пометки и создаст для них отдельный раздел в категории "Описания". Очень удобно.

  /**
   * Краткое описание ф-ции.
   * @todo Дописать определение функции с учётом параметра.
   */

  function exampleFunction($example_param) {
    // do something...
  }

warning — Важное замечание. В документации особо выделяется и обращает на себя внимание.

  /**
   * Краткое описание ф-ции.
   * @warning Параметр игнорируется
   */

  function exampleFunction($example_param) {
    // do something...
  }

bug — Описание ошибки.
NB: Эта категория описаний тоже получит отдельную страницу

  /**
   * Краткое описание ф-ции.
   * @bug Crash при попытке использовать некоторую библиотеку
   */

  function exampleFunction($example_param) {
    // do something...
  }

note — Заметки. В документации они особо выделятся.

  /**
   * Краткое описание ф-ции.
   * @note
   *   - Обычная заметка
   *   - Ещё одна заметка
   */

  function exampleFunction($example_param) {
    // do something...
  }

code, endcode — Позволяет разместить в теле комментария блок кода с подсветкой синтаксиса.

  /**
   * Краткое описание ф-ции.
   * @code
   *    class FooBar{}
   * @endcode
   */

  function exampleFunction($example_param) {
    // do something...
  }

par — Новый параграф. Этот текст и нижеследующий выделятся.

  /**
   * Краткое описание ф-ции.
   * @par Простой пример кода в комментарии
   * @code
   *    class FooBar{}
   * @endcode
   */

  function exampleFunction($example_param) {
    // do something...
  }

see — Указывает на связанную функцию. Эти ссылки группируются в особом параграфе.

  /**
   * Краткое описание ф-ции.
   * @note
   *   - Обычная заметка
   *   - Ещё одна заметка
   *
   * @see anotherFunction()
   */

  function exampleFunction($example_param) {
    anotherFunction();
    // do something...
  }

defgroup, ingroup — Объявление группы ф-ций.

/**
 * @defgroup examplefunc Тестовые функции
 * @{
 * Функции для демонстрации работы doxygen.
 *
 * Более подробное описание группы
 * на нескольких строках.
 * @}
 */

ingroup — Отношение ф-ции к группе

  /**
   * Краткое описание ф-ции.
   * @ingroup examplefunc
   */

  function exampleFunction($example_param) {
    // do something...
  }

addtogroup — Автоматически добавляет ф-ции в группу

/**
 * @addtogroup examplefunc
 * @{
 */

/**
 * Описание ещё одной функции.
 * Краткое описание ф-ции.
 * @par Описание нижеследующего кода
 * @code
 *    class FooBar{}
 * @endcode
 */

function exampleFunction($example_param) {
  # code...
}

/**
 * @} End of "addtogroup examplefunc".
 */

Генерация документации

Просто запустите doxygen указав файл конфигурации.

doxygen Doxyfile

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