Креатив
Верный ход
Качество
Надёжность

phpDocumentoris инструмент документации, который позволяет нам легко создавать документацию из исходного кода PHP. Документация извлекается из источника и из специальных комментариев в источнике; эти комментарии очень похожи на те, что используются JavaDoc.

Этот пример демонстрирует, как мы могли бы задокументировать простую функцию:

/**
 * Adds two integers together
 *
 * @param int $value1 Base value
 * @param int $value2 Value to add
 * @return int Resultant vaue
*/
function addition($value1, $value2)
{
    return ((int)$value1 + (int)$value2)
}

Многострочный комментарий обозначает DocBlock, заметьте, что он использует двойную звездочку в запуске. Первая строка - общее описание функции, это описание может охватить больше чем одну строку. теги @param и @returnare.

Тег @param используется для определения параметра в формате (имя не обязательно):

@param type [$name] description

Тег @return используется, чтобы определить возвращаемое значение в формате:

@return type description

Таким образом, наш начальный пример говорит нам, что у функции addition() есть два целочисленных параметра, названные этим, это добавит togther и возвратит результирующее целочисленное значение.

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

/**
 * Does some complex processing
 *
 * A verbose description of the function that spans more than
 * one line
 *
 * @param int $value1 Base value
 * @param int $value2 Value to add
 * @return int Resultant vaue
*/
function someComplexFunction($value1, $value2)
{
// does some complex processing
}

Функции не единственные элементы, которые могут быть задокументированы. Элементы, которые мы можем задокументировать, включают:

  • методы класса
  • переменные класса
  • классы
  • define()
  • файлы
  • объявления функции
  • глобальные переменные (требует использования тега @global)
  • include() / include_once()
  • require() / require_once()

Этот список определяет некоторые общие теги, с которыми мы, вероятно, встретимся:

  • @access private|protected|public
  • @author name
  • @param type [$name] description
  • @return type description
  • @static

 DocBlocks просто считать, когда они выведены на экран в коде, но что еще более важно мы можем автоматически создать документацию из исходного кода. Для получения дополнительной информации об использовании phpDocumentor обратитесь к http://www.phpdoc.org/.

 Вернуться к оглавлению

Войти на сайт

Запомнить меня

Новости

  • Перевод Mastering Joomla! 1.5

    14.03.2013

    Продолжается перевод книги "Mastering Joomla! 1.5". На данный момент полностью переведено 2 главы. Полностью перевод книги...

    Подробнее...

  • Модернизация сайта

    28.05.2012

    Уважаемые посетители! Мы полностью модернизировали наш сайт и надеемся что сейчас им станет...

    Подробнее...