PHP: PHPDoc
PHPDoc - это стандарт документирования PHP кода; специальные многострочные комментарии DOC-блоки (от англ. "DocBlock").
! ЗАПОМИНАЕМ !
Doc-блок (от англ. DocBlock comments) — это многострочные комментарии (в стиле языка C), которые располагаются перед документируемым элементом.
Плюсы при использовании:
- Автоматическое дополнение от IDE (в случае, если IDE поддерживает работу с PHPDoc);
- Документация "на месте";
- Предотвращение ошибок (IDE подсветит, если, например, передать не тот тип);
- Автоматическая генерация документации (средствами инструмента типа phpDocumentor создается HTML-документация).
Инструменты, которые используют PHPDoc:
- PhpStorm;
- Visual Studio Code;
- Eclipse PDT;
- Komodo IDE;
- и другие.
Существует специальный инструмент, позволяющий на основе PHPDoc вести документацию: phpDocumentor.
phpDocumentor - это система документирования исходных текстов на PHP, имеющая встроенную поддержку генерации документации в форматах HTML, LaTeX, man, RTF и XML. Она может использоваться как из командной строки, так и с помощью Web-интерфейса. Понимает синтаксис 4-й и 5-й версий языка PHP. Система парсит логическую структуры PHP кода (классы, функции, переменные, константы) и привязки к ней комментариев, написанных по стандартам PHPDoc.
Основные правила:
// Пример одной строки:
/** <...> */
// Многострочный пример:
/**
* <...>
*/
Формат записи следующий:
- Резюме
- Описание
- Теги
/**
* Это резюме.
*
* Это Описание. Оно может занимать несколько строк или
* содержать примеры «кода» с использованием языка разметки _Markdown_.
*
* @see Markdown
*
* @param int $parameter1 Описание параметра.
* @param \Exception $e Описание другого параметра.
*
* @\Doctrine\Orm\Mapper\Entity()
*
* @return string
*/
function test($parameter1, $e) {
...
}
Описание можно упускать.
Резюме:
- должно содержать краткое описание «Структурного элемента», определяющего цель (не более 1-2 строки);
- должно заканчиваться двумя последовательными разрывами строк (если только оно не является единственным содержимым в PHPDoc);
- если написано описание, то перед ним обязательно должно быть резюме.
- не является обязательным (можно упускать);
- рекомендуется Markdown.
Теги:
- каждый тег начинается с новой строки, за ним следует знак @ и имя тега, за которым следует пробел и метаданные (включая описание);
- если метаданные указаны, то они могут занимать несколько строк.
Пример записи тега:
@param string $argument1 Это параметр.
Тег выше состоит из:
- имя («param»);
- метаданные («строка $argument1. Это параметр».; где метаданные разделены на тип "string", имя переменной "$argument" и описание "Это параметр").
Имена тегов указывают на тип информации представляемый тегом.
Пример с функцией:
/**
* Отправляет персональное системное уведомление пользователю через модуль IM Битрикс
*
* Функция выполняет проверку корректности входных параметров, экранирует текст и отправляет системное
* уведомление через CIMMessenger::Add(). В случае успеха возвращает true.
*
* @param int|string $ToUser ID пользователя-получателя (будет преобразован в int)
* @param int|string $FromUser ID пользователя-отправителя (будет преобразован в int)
* @param string $msgTxt Текст уведомления (не должен быть пустым)
*
* @return bool Возвращает true при успешной отправке уведомления, false в случае:
* - невозможности подключить модуль 'im'
* - если ID получателя или отправителя <= 0
* - если текст сообщения пуст
* - если метод CIMMessenger::Add() вернул false
*/
function SendPersNotif_CIMMessenger($ToUser, $FromUser, $msgTxt) {
if (!CModule::IncludeModule('im')) return false;
// Проверка входящих параметров
$ToUser = intval($ToUser);
if ($ToUser <= 0) return false;
$FromUser = intval($FromUser);
if ($FromUser <= 0) return false;
if (empty($msgTxt)) return false;
$safeMsgTxt = htmlspecialcharsbx($msgTxt); // Экранируем текст (на всякий случай)
$messenger = new \CIMMessenger();
$fields = [
"TO_USER_ID"=> $ToUser, // Получатель
"FROM_USER_ID"=> $FromUser, // Отправитель
"MESSAGE_TYPE"=> IM_MESSAGE_SYSTEM, // Тип сообщения
"NOTIFY_MESSAGE"=> $safeMsgTxt, // Текст сообщения
"NOTIFY_MODULE" => "fusion.sigma", // ID модуля
];
// Возвращаем результат отправки
$result = $messenger->Add($fields);
return ($result !== false);
}
— Бесплатные Сайты и CRM.