Php документация по коду

# PHPDoc

The @var keyword can be used to describe the type and usage of:

class Example  /** @var string This is something that stays the same */ const UNCHANGING = "Untouchable"; /** @var string $some_str This is some string */ public $some_str; /** * @var array $stuff This is a collection of stuff * @var array $nonsense These are nonsense */ private $stuff, $nonsense; . > 

The type can be one of the built-in PHP types, or a user-defined class, including namespaces.

The name of the variable should be included, but can be omitted if the docblock applies to only one item.

# Adding metadata to files

File level metadata applies to all the code within the file and should be placed at the top of the file:

 /** * @author John Doe (jdoe@example.com) * @copyright MIT */ 

# Inheriting metadata from parent structures

If a class extends another class and would use the same metadata, providing it @inheritDoc is a simple way for use the same documentation. If multiple classes inherit from a base, only the base would need to be changed for the children to be affected.

abstract class FooBase  /** * @param Int $a First parameter to add * @param Int $b Second parameter to add * @return Int */ public function sum($a, $b) > > class ConcreteFoo extends FooBase  /** * @inheritDoc */ public function sum($a, $b)  return $a + $b; > > 

# Describing parameters

 /** * Parameters * * @param int $int * @param string $string * @param array $array * @param bool $bool */ function demo_param($int, $string, $array, $bool) < >/** * Parameters - Optional / Defaults * * @param int $int * @param string $string * @param array $array * @param bool $bool */ function demo_param_optional($int = 5, $string = 'foo', $array = [], $bool = false) < >/** * Parameters - Arrays * * @param array $mixed * @param int[] $integers * @param string[] $strings * @param bool[] $bools * @param string[]|int[] $strings_or_integers */ function demo_param_arrays($mixed,$integers, $strings, $bools, $strings_or_integers) < >/** * Parameters - Complex * @param array $config * 
* $params = [ * 'hostname' => (string) DB hostname. Required. * 'database' => (string) DB name. Required. * 'username' => (string) DB username. Required. * ] *
 
 */ function demo_param_complex($config)
 
# Collections
 
(opens new window) proposes a form of Generics-style notation for collections.
 
# Generics Syntax
 
Type[] TypeType> TypeType[, Type]. > TypeType[|Type]. > 
 
Values in a Collection MAY even be another array and even another Collection.
 
TypeTypeType>> TypeTypeType[, Type]. >> TypeTypeType[|Type]. >> 
 
# Examples
 
 /** * @var ArrayObject $name */ $name = new ArrayObject(['a', 'b']); /** * @var ArrayObject $name */ $name = new ArrayObject([1, 2]); /** * @var ArrayObject $name */ $name = new ArrayObject([ new stdClass(), new stdClass() ]); /** * @var ArrayObject $name */ $name = new ArrayObject([ 'a', true, 1, 'b', new stdClass(), 'c', 2 ]); /** * @var ArrayObject $name */ $name = new ArrayObject([ new ArrayObject([1, 2]), new ArrayObject([1, 2]) ]); /** * @var ArrayObject $name */ $name = new ArrayObject([ 1 => 'a', 2 => 'b' ]); /** * @var ArrayObject $name */ $name = new ArrayObject([ 'a' => 1, 'b' => 2 ]); /** * @var ArrayObject $name */ $name = new ArrayObject([ 'a' => new stdClass(), 'b' => new stdClass() ]); 
 
# Syntax
 
 
@api
 
@author [name] [ ]
 
@copyright
 
@deprecated [][:] [ ]
 
@example [URI] [ ]
 
 
@inheritDoc
 
@internal
 
>
 
@license [ |URI] [name]
 
@method [return «Type»] [name]([«Type»] [parameter], [. ]) [description]
 
@package [level 1][level 2][etc.]
 
@param [«Type»] [name] [ ]
 
@property [«Type»] [name] [ ]
 
@return [description]
 
@see [URI | «FQSEN»] [ ]
 
@since [] [ ]
 
@throws [«Type»] [ ]
 
@todo [description]
 
@uses [file | «FQSEN»] [ ]
 
@var [«Type»] [element_name] [ ]
 
@version [«Semantic Version»] [ ]
 
@filesource — Includes current file in phpDocumentor parsing results
 
@link [URI] [ ] — Link tag helps to define relation or link between structural elements
 
 
# Remarks
 
«PHPDoc» is a section of documentation which provides information on aspects of a «Structural Element» — PSR-5
 
PHPDoc annotations are comments that provide metadata about all types of structures in PHP. Many popular IDEs are configured by default to utilize PHPDoc annotations to provide code insights and identify possible problems before they arise.
 
While PHPDoc annotations are not part of the PHP core, they currently hold draft status with PHP-FIG
 
All PHPDoc annotations are contained within DocBlocks that are demonstrated by a multi-line with two asterisks:
 
Источник
 
Документирование PHP скриптов с помощью phpDoc и phpDocumentor
 
Если вы когда-нибудь пытались прочитать код, написанный кем-то, кроме вас, вы знаете, что это может быть сложной задачей. Беспорядочный «код спагетти», смешанный с множеством странно названных переменных, заставляет вашу голову кружиться. Эта функция ожидает строку или массив? Эта переменная хранит целое число или объект? После бесчисленных часов следования за нитями кода и попытки понять, что делает каждый бит, нередко отказаться и просто переписать все с нуля — задача, которая тратит слишком много вашего драгоценного времени.
 
PHPDoc, сокращение от PHPDocumentor, является мощным инструментом, который позволяет легко документировать ваш код с помощью специально отформатированных комментариев. Документация будет доступна не только в исходном коде, но и в профессиональной документации, извлеченной с использованием веб-интерфейса или интерфейса командной строки. Результат может быть в различных форматах, таких как HTML, PDF и CHM. Кроме того, многие IDE, которые обеспечивают завершение кода, могут анализировать комментарии PHPDoc и предоставлять полезные функции, такие как подсказки типов. Используя PHPDoc, вы можете позволить другим (и вам самим) легко понять ваш код — через недели, месяцы и даже годы после его написания.
 
DocBlock — это многострочный комментарий в стиле C, используемый для документирования блока кода. Он начинается с /** и имеет звездочку в начале каждой строки.
 
/** * Этот класс является примером использования doc-блоков phpDoc */ class SomeClass < /** @type string|null Текст приветствия */ protected $weclome = null; /** * Этот метод задает текст приветствия. * @param string $text текст приветствия, максимум 255 символов. * @return void */ public function setWeclomeText($text) < $this->weclome = $text; > >
 
DocBlocks состоит из трех разделов: краткое описание, длинное описание и теги. Все три раздела являются необязательными.
 
Краткое описание — это краткое описание, оканчивающееся либо новой строкой, либо точкой. Процедуры синтаксического анализа PHPDoc’а умны; короткое описание заканчивается только в том случае, если точка находится в конце предложения.
 
Длинное описание — это то, куда уходит основная часть документации; это может быть многострочно и сколько угодно времени.
 
Как длинные, так и короткие описания могут содержать определенные элементы HTML для форматирования. HTML-теги, которые не поддерживаются, будут отображаться в виде простого текста. Однако PHPDoc может генерировать документацию в нескольких форматах, поэтому теги HTML не обязательно отображаются так же, как в файле HTML; фактическое форматирование зависит от сгенерированного формата файла.
 
Раздел тегов DocBlock содержит любое количество специальных тегов, обозначаемых символом @. Теги используются для указания дополнительной информации, такой как ожидаемые параметры и их тип. Большинство тегов должны быть в отдельной строке, за исключением определенных тегов, которые могут быть встроенными. Встроенные теги окружены фигурными скобками и могут быть как в длинном, так и в коротком описании.
 
Не все элементы кода могут быть документированы с помощью DocBlocks. Вот список элементов кода, которые могут быть документированы:
 
 
файлы
 
Классы
 
Функции и методы
 
Свойства класса
 
Глобальные переменные
 
include() / require()
 
define()
 
 
Справочник phpDoc
 
@api — помечает структурный элемент, используемый сторонними программами, и являющийся частью API.
 
/** * Этот метод показывает версию релиза * @api * @return void */ function showVersion() <>
 
@author — задает имя автора.
 
/** * @author My Name * @author My Name */
 
@copyright — копирайтинг.
 
/** * @copyright 2020-2021 The alishoff.com */
 
@deprecated — тег для пометки элементов на удаление в будущих версиях.
 
/** * @deprecated * @deprecated 1.0.0 * @deprecated Больше не используется внутри кода, и не рекомендуется. */
 
@filesource — сообщает в phpDocumentor, что нужно включить исходный код в текущий файл для разбора.
 
@ignore — сообщает в phpDocumentor, что следующий структурный элемент обрабатывать не надо.
 
@internal — говорит, что элемент является внутренним элементом этого приложения или библиотеки.
 
/** * @internal * @return Возвращает целочисленное значение - количество чего либо. */ function count() <>
 
@license — описывает соответствие лицензии.
 
/** * @license GPL * @license http://opensource.org/licenses/gpl-license.php GNU Public License */
 
@link — связывает структурный элемент с сайтом, откуда он взят.
 
/** * @link http://example.com Документация к функции. * @return Возвращает целочисленное значение - количество чего либо. */ function count() <>
 
@method — указывает какие магические (не явные) методы класса можно вызвать.
 
class Parent < public function __call() <>> /** * @method string getString() * @method void setInteger(integer $integer) * @method setString(integer $integer) */ class Child extends Parent <>
 
@param — описывает тип и имя параметра передаваемого в функцию.
 
/** * Counts the number of items in the provided array. * @param mixed[] $array Array массив значений. * @param int|string $value некоторое значение. * @return int возвращает номер элемента. */ function count(array $items, $value) <>
 
@property — аналогичен тегу @method. Позволяет классу знать какие можно использовать магические свойства.
 
class Parent < public function __get() <>> /** * @property string $myProperty */ class Child extends Parent <>
 
@property-read — указывает какие можно использовать магические свойства, только для чтения.
 
class Parent < public function __get() <>> /** * @property-read string $myProperty */ class Child extends Parent <>
 
@property-write — указывает какие можно использовать магические свойства, только для записи.
 
class Parent < public function __set() <>> /** * @property-write string $myProperty */ class Child extends Parent <>
 
@return — описывает возвращаемое значение функцией или методом.
 
/** * @return string|null Метка для текста. */ function getLabel() <>
 
@see — задает ссылку из структурного элемента, на веб-сайт или другой элемент.
 
/** * @see http://example.com Документация функции. * @see MyClass::$items свойства элементов. * @see MyClass::setItems() установка элементов коллекции. * @return integer Показывает количество элементов в коллекции. */ function count() <>
 
@since — говорит о том, что структурный элемент стал доступен с заданной версии пакета.
 
/** * Файл проекта * @package test * @version 1.5.2 */ /** * функция dataFunction * @since Version 1.1.2 */ function dataFunction() <>
 
@var — указывает описание для свойств класса.
 
@version — версия документа.
 
/** * Пример использования тега @version * @version v 1.2 */ function dataFunction() <>
 
@example — пример использования метода или класса.
 
@global — описывает глобальные переменные.
 
@package — классификация структурных элементов в логических подразделениях.
 
@subpackage — описывает под-пакет основного пакета, используется вместе с тегом @package.
 
@todo — документирует задачи, которые необходимо выполнить в ближайшем будущем.
 
@uses — показывает ссылку на документацию по этому элементу, и создает обратную ссылку в других документациях элементов на него.
 
Источник
 
Читайте также:  What is css in html5