Если вы когда-нибудь пытались прочитать код, написанный кем-то, кроме вас (у кого нет?), Вы знаете, что это может быть сложной задачей. Беспорядочный «код спагетти», смешанный с множеством странно названных переменных, заставляет вашу голову кружиться. Эта функция ожидает строку или массив? Эта переменная хранит целое число или объект? После бесчисленных часов следования за нитями кода и попытки понять, что делает каждый бит, нередко отказаться и просто переписать все с нуля — задача, которая тратит слишком много вашего драгоценного времени.
PhpDoc, сокращение от PhpDocumentor, является мощным инструментом, который позволяет легко документировать ваш код с помощью специально отформатированных комментариев. Документация будет доступна не только в исходном коде, но и в профессиональной документации, извлеченной с использованием веб-интерфейса или интерфейса командной строки. Результат может быть в различных форматах, таких как HTML, PDF и CHM. Кроме того, многие IDE, которые обеспечивают завершение кода, могут анализировать комментарии PhpDoc и предоставлять полезные функции, такие как подсказки типов. Используя PhpDoc, вы можете позволить другим (и вам самим) легко понять ваш код — через недели, месяцы и даже годы после его написания.
Самый простой способ установить PhpDoc — это PEAR. Конечно, прежде чем вы сможете это сделать, у вас должна быть установлена PEAR. Если вы этого не сделаете, следуйте инструкциям на pear.php.net/manual/en/installation.php .
В этой статье я покажу вам, как использовать PhpDoc для создания великолепной и удобной документации от начала до конца.
DocBlocks
DocBlock — это многострочный комментарий в стиле C, используемый для документирования блока кода. Он начинается с /** и имеет звездочку в начале каждой строки. Вот пример:
<?php /** * Calculates sum of squares of an array * * Loops over each element in the array, squares it, and adds it to * total. Returns total. * * This function can also be implemented using array_reduce(); * * @param array $arr * @return int * @throws Exception If element in array is not an integer */ function sumOfSquares($arr) { $total = 0; foreach ($arr as $val) { if (!is_int($val)) { throw new Exception("Element is not an integer!"); } $total += $val * $val; } return $total; }
DocBlocks состоит из трех разделов: краткое описание, длинное описание и теги. Все три раздела являются необязательными.
Краткое описание — это краткое описание, оканчивающееся либо новой строкой, либо точкой. Процедуры синтаксического анализа PhpDoc’а умны; короткое описание заканчивается только в том случае, если точка находится в конце предложения.
Длинное описание — это то, куда уходит основная часть документации; это может быть многострочно и сколько угодно времени.
Как длинные, так и короткие описания могут содержать определенные элементы HTML для форматирования. HTML-теги, которые не поддерживаются, будут отображаться в виде простого текста. Однако PhpDoc может генерировать документацию в нескольких форматах, поэтому теги HTML не обязательно отображаются так же, как в файле HTML; фактическое форматирование зависит от сгенерированного формата файла. Если вам нужно отобразить HTML-тег в виде текста, используйте двойные скобки. Например:
<?php /** * Here an example of the italics tag: <<i>>Hello, world!<<i>> */
Раздел тегов DocBlock содержит любое количество специальных тегов, обозначаемых символом @ . Теги используются для указания дополнительной информации, такой как ожидаемые параметры и их тип. Большинство тегов должны быть в отдельной строке, за исключением определенных тегов, которые могут быть встроенными. Встроенные теги окружены фигурными скобками и могут быть как в длинном, так и в коротком описании. Полный список тегов можно найти в соответствующей документации PhpDoc .
Если вам нужно начать строку с символа @ но вы не хотите, чтобы она интерпретировалась как тег, вы можете экранировать ее обратной косой чертой.
PhpDoc автоматически распознает текстовые списки в длинных и коротких описаниях и анализирует их. Тем не менее, он не будет правильно анализировать вложенные списки. Если вы хотите использовать вложенные списки, используйте теги HTML. Вот пример, чтобы проиллюстрировать, что я имею в виду:
<?php /** * Example of using lists * * PhpDoc will parse this list correctly: * - Item #1 * - Item #2 * - Item #3 * * But not this list: * - Item 1 * - Item 1.1 * - Item 1.2 * - Item 2 * * Use this instead for a nested list: * <ul> * <li>Item 1</li> * <ul> * <li>Item 1.1</li> * <li>Item 1.2</li> * </ul> * <li>Item 2</li> * </ul> */
пакеты
Пакеты PhpDoc используются для группировки связанных элементов кода в сгенерированной документации. Вы можете указать пакеты для файлов и классов, и документированный код, который они содержат, унаследует пакет от них. Чтобы указать пакет, установите тег @package в @package на уровне файлов или на уровне класса (DocBlocks на уровне файлов и на уровне класса будут обсуждаться далее в следующем разделе). Имя пакета может содержать буквы, цифры, тире, подчеркивания и квадратные скобки («[» и «]»).
Вот пример определения пакета файла:
<?php /** * This is a file-level DocBlock * * @package Some_Package */
Если у вас есть несколько уровней пакетов и @subpackage , вы можете определить @subpackage тегом @subpackage . Вот пример:
<?php /** * This is a class-level DocBlock * * @package Some_Package * @subpackage Other */ class SomeClass { }
Если файл или класс не указывает пакет, для него будет установлен пакет по умолчанию, «по умолчанию». Вы можете указать другой пакет, который будет использоваться по умолчанию при создании документации с помощью -dn командной строки -dn .
Что я могу зарегистрировать?
Не все элементы кода могут быть документированы с помощью DocBlocks. Вот список элементов кода, которые могут быть документированы:
- файлы
- Классы
- Функции и методы
- Свойства класса
- Глобальные переменные
-
include()/require() -
define()
Все эти элементы могут использовать определенные общие теги, но у каждого есть теги, специфичные для этого элемента. Я рассмотрю некоторые элементы и теги, которые обычно используются для их документирования.
файлы
Файловые DocBlocks используются для документирования содержимого файла. Настоятельно рекомендуется включать DocBlock на уровне файлов в каждый файл, который вы документируете, и на самом деле PhpDoc будет отображать предупреждение, если оно не найдено при создании документации.
Большинство элементов документируются путем помещения DocBlock перед элементом, но файлы являются исключением (так как вы ничего не можете написать перед файлом). Файловые DocBlocks помещаются в первую строку файла.
DocBlock на уровне файлов обычно содержит теги @package , @subpackage , @license и @author . @package и @subpackage обсуждались ранее. Тег @license используется для указания URL-адреса внешней лицензии, охватывающей ваш код. Тег должен содержать URL-адрес лицензии и, необязательно, заголовок. Тег @author используется для указания автора файла. Он должен содержать имя автора и, возможно, адрес электронной почты в угловых скобках.
В отличие от большинства элементов, файл DocBlock на уровне файла должен содержать тег @package для правильного анализа.
Вот полный пример DocBlock на уровне файлов:
<?php
Классы
DocBlock уровня класса помещается перед определением класса и должен описывать значение класса. Как и DocBlocks на уровне файлов, DocBlocks на уровне класса обычно содержат теги @package , @subpackage и @author . Вот пример:
<?php class Example { }
Функции и методы
Функции и методы задокументированы одинаково в PhpDoc. (Для тех, кто не знаком с терминологией, метод — это просто функция внутри класса.) Функции и методы обычно содержат @param и @return в своих DocBlocks. Тег @param используется для документирования ожидаемого типа параметра. Он содержит три раздела: параметр, тип данных и необязательное описание. Тег @return используется для документирования возвращаемого типа. Он содержит два раздела: тип данных и необязательное описание. В обоих тегах тип данных может быть допустимым типом данных PHP, именем класса или «смешанным». Он также может содержать несколько параметров, разделенных конвейером.
<?php /** * Finds and returns user by ID or username * * @param int|string $user Either an ID or a username * @param PDO $pdo A valid PDO object * @return User Returns User object or null if not found */ function getUser($user, PDO $pdo) { // ... if ($isFound) { return new User(...); } return null; }
Генерация документации
После того, как вы задокументировали свой PHP-код, вы захотите сгенерировать удобную для него документацию. Для этого запустите инструмент командной строки PhpDoc.
moteutsch @ vivaldi: ~ $ phpdoc -d / path / to / files / -t / path / to / docs / -ti 'Заголовок документации' -dn 'Пакет по умолчанию' -o HTML: frames: default
Опция -d указывает разделенный запятыми список каталогов, содержащих файлы для документа, и -t путь к сгенерированным документам. -ti используется для указания заголовка проекта, а -dn для имени пакета по умолчанию. Наконец, -o указывает формат документации. PhpDoc имеет широкий выбор форматов на выбор. Полный список доступен на сайте PhpDoc .
Вы можете узнать больше об инструменте командной строки, выполнив команду help следующим образом:
moteutsch @ vivaldi: ~ $ phpdoc -h
После запуска команды указанный путь к документации должен содержать сгенерированные документы.
Для тех из вас, кому неудобно использовать интерфейс командной строки, PhpDoc также имеет веб-интерфейс. Обсуждение этого вопроса выходит за рамки данной статьи, но вы можете прочитать об этом подробнее на официальном сайте PhpDoc , phpdoc.org .
Резюме
В этой статье я впервые ознакомился с PhpDoc и его многочисленными мощными функциями. Я объяснил назначение DocBlocks и их компонентов; Я показал вам, как организовать вашу документацию, используя пакеты; Я объяснил, какие элементы кода могут быть задокументированы, и некоторые распространенные примеры этого; наконец, я показал вам, как генерировать документацию из вашего исходного кода. Я настоятельно рекомендую вам начать использовать PhpDoc в ваших собственных проектах, хотя бы только для документирования наиболее важных частей. Это очень просто и спасет вас и ваших коллег бесчисленные часы грызть ногти и волосы.
Изображение через Задорожного Виктора / Shutterstock