PHPDocumentor — это инструмент, написанный на PHP. Для программ PHP со стандартными аннотациями он может быстро генерировать документы API с перекрестными ссылками, индексированием и другими функциями. Старая версия — phpdoc.
1. Что такое phpDocumentor?
PHPDocumentor — это инструмент, написанный на PHP. Для программ PHP со стандартными аннотациями он может быстро генерировать документы API с перекрестными ссылками, индексированием и другими функциями. Старая версия — phpdoc. Начиная с версии 1.3.0, она была переименована в phpDocumentor. В новой версии добавлена поддержка синтаксиса php5. В то же время документы можно создавать, работая в клиентском браузере, и документы можно конвертировать в другой формат. PDF, HTML, Существует несколько форм CHM, которые очень удобны.
Когда PHPDocumentor работает, он сканирует исходный код PHP в указанном каталоге, сканирует ключевые слова, перехватывает комментарии, которые необходимо проанализировать, затем анализирует специальные теги в комментариях, генерирует XML-файл, а затем на основе информации анализируемые классы и модули, устанавливают соответствующие индексы, генерируют XML-файлы и используют настроенные шаблоны для вывода файлов в указанном формате для сгенерированных XML-файлов.
2. Установите PHPДокументор.
Как и другие модули под грушу, установка phpDocumentor также делится на два метода: автоматическая установка и ручная установка. Оба способа очень удобны:
а. Автоматически установить через грушу и ввести в командной строке
груша установить PhpDocumentor
б. Вручную установите последнюю версию PhpDocumentor (теперь 1.4.0) по адресу http://manual.phpdoc.org/ и разархивируйте содержимое.
3． Как использовать PhpDocumentor для создания командной строки документации:
В каталоге, где находится phpDocumentor, введите
Php-h
Вы получите подробный список параметров, среди которых есть несколько важных параметров:
-f Имя анализируемого файла, несколько файлов через запятую.
-d Каталог для анализа, несколько каталогов, разделенных запятыми
-t путь хранения сгенерированного документа
-o Формат выходного документа, структура: формат вывода: имя конвертера: каталог шаблона.
Например: phpdoc -o HTML:frames:earthli -f test.php -t docs
Веб-интерфейс создается в новом phpdoc. Помимо создания документов в командной строке, вы также можете создавать документы в браузере клиента. Конкретный метод заключается в том, чтобы сначала поместить содержимое PhpDocumentor в каталог Apache, чтобы его можно было использовать. доступ через браузер, после доступа отобразится следующий интерфейс:
Нажмите кнопку «Файлы», чтобы выбрать файлы или папки PHP для обработки. Вы также можете игнорировать обработку определенных файлов, указав файлы, которые нужно игнорировать в этом интерфейсе.
Затем нажмите кнопку вывода, чтобы выбрать путь хранения и формат созданного документа.
Наконец, нажмите «Создать», и phpdocumentor автоматически начнет генерировать документы. В случае успеха они будут отображаться внизу.
Общее время документирования: 1 секунда
сделанный
Операция завершена!!
Затем мы можем просмотреть сгенерированный документ. Если он в формате PDF, имя по умолчанию — document.pdf.
4. Добавляем стандартные комментарии в php-код
PHPDocument генерирует документы из комментариев в исходном коде, поэтому процесс комментирования вашей программы одновременно является процессом составления документации.
С этой точки зрения PHPdoc поощряет вас развивать хорошие навыки программирования и стараться использовать спецификации и открытый текст для аннотирования вашей программы. В то же время он более или менее позволяет избежать некоторых проблем рассинхронизации между подготовкой документа и самим документом. обновления после этого.
В phpdocumentor комментарии делятся на комментарии к документации и комментарии, не относящиеся к документации.
Так называемые комментарии к документации представляют собой многострочные комментарии, помещаемые перед определенными ключевыми словами. Определенные ключевые слова относятся к ключевым словам, которые могут быть проанализированы phpdoc, например class, var и т. д. Подробности см. в Приложении 1.
Комментарии, которые не предшествуют ключевым словам или не стандартизированы, называются комментариями, не относящимися к документации. Эти комментарии не будут анализироваться phpdoc и не будут отображаться в генерируемом вами тексте API.
3.2 Как писать комментарии к документации:
Все комментарии к документации представляют собой многострочные комментарии, начинающиеся с /**, которые в phpDocumentor называются DocBlock и относятся к справочной информации об определенном ключевом слове, написанной разработчиками программного обеспечения, чтобы другие могли узнать об этом. Конкретное назначение ключевых слов. и как их использовать. PhpDocumentor указывает, что DocBlock содержит следующую информацию:
1. Область краткого описания функций
2. Область подробного описания
3. Тег
Первая строка комментария к документации — это область описания функции. Текст обычно кратко объясняет функцию этого класса, метода или функции. Текст описания функции будет отображаться в области индекса в сгенерированном документе. Содержимое области описания функции может заканчиваться пустой строкой или. После области описания функции следует пустая строка, за которой следует область подробного описания. Если возможно, в этой части подробно описываются функции и назначение вашего API. вы также можете Примеры использования и т. д. В этом разделе вам следует сосредоточиться на разъяснении общего назначения и использования ваших функций или методов API, а также указать, являются ли они кроссплатформенными (если таковые имеются). К информации, связанной с платформой, следует относиться иначе, чем к общей информации. обычный подход состоит в том, чтобы начать новую строку, а затем написать меры предосторожности или специальную информацию для конкретной платформы. Этой информации должно быть достаточно, чтобы ваши читатели могли написать соответствующую тестовую информацию, такую как граничные условия, диапазоны параметров, точки останова и т. д.
После этого также идет пустая строка, а затем тег документа, указывающий некоторую техническую информацию, в основном тип параметра вызова, возвращаемое значение и тип, отношения наследования, связанные методы/функции и т. д.
Подробную информацию о маркировке документов см. в Разделе 4: Маркировка документов.
Такие теги, как <b> <code>, также можно использовать в комментариях к документу. Подробности см. в Приложении 2.
Ниже приведен пример комментария документации
/**.
* Функция add, реализует сложение двух чисел
*
* Простое сложение: функция принимает два числа a и b и возвращает их сумму c.
*
* @param int дополнение
* @param целое слагаемое
* @return целое число
*/
функция Add($a, $b) {
вернуть $а+$б;
}
Сгенерированный документ выглядит следующим образом:
Добавлять
целое число Add(int $a, int $b)
[строка 45]
Функция add, реализует сложение двух чисел
Константы — это простое сложение. Функция принимает два числа a и b и возвращает их сумму c.
Параметры
• int $a — добавить
• int $b — слагаемое
5. Теги документа:
Область использования тега документа относится к ключевым словам или другим тегам документа, которые этот тег можно использовать для изменения.
Все теги документации начинаются с символа @ после * в каждой строке. Если знак @ появляется в середине абзаца, он будет рассматриваться как обычное содержимое и игнорироваться.
@доступ
Область использования: класс, функция, переменная, определение, модуль.
Этот тег используется для указания прав доступа ключевого слова: частный, публичный или защищенный.
@автор
Укажите автора
@авторское право
Область использования: класс, функция, переменная, определение, модуль, использование.
Укажите информацию об авторских правах
@устарело
Область использования: класс, функция, переменная, определение, модуль, константа, глобальный, включение.
Укажите неиспользуемые или устаревшие ключевые слова
@пример
Этот тег используется для анализа части содержимого файла и выделения ее. Phpdoc попытается прочитать содержимое файла по пути к файлу, указанному в этом теге.
@const
Область использования: определить
Используется для обозначения констант, определенных в php.
@финал
Область использования: класс, функция, переменная.
Указывает, что ключевое слово является конечным классом, методом или атрибутом и его производное или изменение запрещено.
@filesource
Аналогично примеру, за исключением того, что этот тег будет напрямую читать содержимое анализируемого в данный момент файла php и отображать его.
@global
Указывает глобальные переменные, на которые ссылается эта функция.
@ingore
Используется для игнорирования указанных ключевых слов в документе.
@лицензия
Эквивалент <a> в теге html: сначала указывается URL-адрес, затем отображаемый контент, например <a href="http://www.baidu.com">Baidu</a>
Вы можете написать @license http://www.baidu.com Baidu
@связь
похоже на лицензию
Но вы также можете указать любое ключевое слово в документе по ссылке.
@имя
Укажите псевдоним для ключевого слова.
@упаковка
Область использования: уровень страницы -> определить, функцию, включить
Уровень класса->класс, var, методы
Используется для логической группировки одного или нескольких ключевых слов в группу.
@abstrcut
Указывает, что текущий класс является абстрактным классом.
@парам
Укажите параметры функции
@возвращаться
Указывает указатель возврата метода или функции.
@статический
Указывает, что ключевое слово является статическим.
@вар
Укажите тип переменной
@версия
Укажите информацию о версии
@тодо
Укажите области, которые следует улучшить или не реализовать
@бросает
Указывает исключение ошибки, которое может выдать эта функция. В крайних случаях, как упоминалось выше, обычные теги документа должны быть помечены знаком @ в начале каждой строки. Кроме того, существует также тег, называемый встроенным тегом, который означает использование {@ }. , в частности, включая следующее:
{@связь }
Использование такое же, как @link
{@источник }
Отображение содержимого функции или метода
6． Некоторые характеристики аннотаций
а. Комментарий должен быть
/**
* ХХХХХХХ
*/
форма
б. Для функций, ссылающихся на глобальные переменные, необходимо использовать тег glboal.
c. Для переменных их тип должен быть отмечен var (int, string, bool...).
d. Функция должна указывать свои параметры и возвращаемое значение через теги param и return.
д. Для ключевых слов, которые встречаются дважды или более, игнорируйте лишние и оставляйте только одно.
f. При вызове других функций или классов следует использовать ссылку или другие теги для ссылки на соответствующую часть для облегчения чтения документа.
g. Используйте комментарии, не относящиеся к документации, где это необходимо, чтобы улучшить читаемость кода.
h. Описательное содержание должно быть кратким и по существу, по возможности используя фразы, а не предложения.
i. Глобальные переменные, статические переменные и константы должны быть объявлены с соответствующими тегами.
7. Резюме
phpDocumentor — это очень мощный инструмент автоматического создания документов. Он может помочь нам писать стандартизированные комментарии и создавать простые для понимания, четко структурированные документы, что очень полезно для обновления кода, обслуживания, передачи и т. д.
Более подробное описание phpDocumentor можно найти на его официальном сайте.
http://manual.phpdoc.org/Просмотр
8. Приложение Приложение 1:
Ключевые слова, распознаваемые phpdoc:
Включать
Требовать
include_once
require_once
определять
функция
глобальный
сорт
Приложение 2
Теги, которые можно использовать в документах
<б>
<код>
<br>
<кдб>
<ли>
<предварительно>
<ул>
<самп>
<вар>
Приложение 3:
Кусок php-кода с каноническими комментариями:
<?php
/**
* Пример файла 2, Краткое руководство по phpDocumentor.
*
* Этот файл демонстрирует обширную информацию, которую можно включить в
* документация в коде через DocBlocks и теги.
* @author Грег Бивер < [email protected] >
* @версия 1.0
* @образец пакета
*/
// пример файла №1
/**
* Фиктивное значение включения, чтобы продемонстрировать возможности синтаксического анализа phpDocumentor.
*/
include_once 'sample3.php';
/**
* Специальное объявление глобальной переменной DocBlock.
* @global целое число $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*Константы
*/
/**
* первая константа
*/
определить('тестирование', 6);
/**
* вторая константа
*/
define('anotherconstant', strlen('привет'));
/**
* Пример докблока функции.
* @global string документирует тот факт, что эта функция использует $_myvar
* @staticvar целое число $staticvar именно это и возвращается
* @param string $param1 имя для объявления
* @param string $param2 значение имени
* @return целое число
*/
function firstFunc($param1, $param2 = 'необязательно') {
статический $staticvar = 7;
глобальный $_myvar;
вернуть $staticvar;
}
/**
* Первый пример класса, он находится в том же пакете, что и
*процедурные детали в начале файла
* @образец пакета
* классы @subpackage
*/
класс мойкласс {
/**
* Пример частной переменной, ее можно скрыть с помощью --parseprivate.
*вариант
* @accessprivate
* @var целое число|строка
*/
вар $firstvar = 6;
/**
* @link http://www.example.com Пример ссылки
* @см. мой класс()
* @uses тестирование, другая константа
* массив @var
*/
вар $секундвар =
множество(
'вещь' =>
множество(
6,
17,
'броненосец'
),
тестирование => другая константа
);
/**
* Конструктор настраивает {@link $firstvar}
*/
функция мойкласс() {
$this->firstvar = 7;
}
/**
* Возвращает штуковину на основе $paramie
* @param boolean $paramie
* @return целое|детскийкласс
*/
функция родительская функция ($ paramie) {
если ($paramie) {
возврат 6;
} еще {
вернуть новый бэби-класс;
}
}
}
/**
* @образец пакета1
*/
класс babyclass расширяет myclass {
/**
* Ответ на вопрос «Жизнь, Вселенная и все остальное»
* @var целое число
*/
вар $секундвар = 42;
/**
* Значения конфигурации
* массив @var
*/
вар $третьявар;
/**
* Вызывает родительский конструктор, затем увеличивает {@link $firstvar}
*/
функция babyclass() {
родитель::myclass();
$this->firstvar++;
}
/**
* Это всегда возвращает myclass
* @param игнорирует $paramie
* @return мой класс
*/
функция родительская функция ($ paramie) {
вернуть новый myclass;
}
}
?>