Примеры DocBlock
DocBlocks, сокращение от Documentation Blocks, заметки описывающие что делают определенные части кода. Блоки документации написанные разработчиками, помогают другим разработчикам, понять что именно представляет собой код и что он делает.
DocBlock для файла
| Дескриптор | Требование | Примечания |
|---|---|---|
Summaryкраткое описание |
необязательный | Необязательно, если файл не содержит более двух классов или функций, далее следует пустая строка |
Descriptionподробное описание |
необязательный | Далее следует пустая строка |
@category
|
необязательный | Имя категории, в которую объединены несколько пакетов |
@package
|
необязательный | Указание имени пакета, в который входит данный программный код (файл). Используется в заголовочном блоке файла или в блоке комментариев класса |
@subpackage
|
необязательный | Объеденяет несколько пакетов в один раздел документации. Используется с тегом @package. Применяется в начале файла или заглавном докблоке класса. |
@author
|
необязательный | Имя автора кода, phpDocumentor будет искать текст между угловыми скобками, <info@hmarketing.ru> |
@copyright
|
необходимый | Информация, указывающая на правообладателя кода |
@license
|
необходимый | Ссылка на лицензию, под которой распространяется код |
@deprecated
|
необязательный | Указывает на то, что код устарел |
@link
|
необязательный | Возможность добавить ссылку к любому документируемому коду |
@see
|
необязательный | Указывает на то, что документация уже существует в другом докблоке |
@since
|
необязательный | Указывает на версию, класса, метода, функции с которой комментируемый элемент стал доступен |
ООП
DocBlock для класса
| Дескриптор | Требование | Примечания |
|---|---|---|
Summaryкраткое описание |
необходим | Далее следует пустая строка |
Descriptionподробное описание |
необязательный | Далее следует пустая строка |
@category
|
необязательный | Имя категории, в которую объединены несколько пакетов |
@package
|
необходим | Указание имени пакета, в который входит данный программный код (файл). Используется в заголовочном блоке файла или в блоке комментариев класса |
@subpackage
|
необязательный | Объеденяет несколько пакетов в один раздел документации. Используется с тегом @package. Применяется в начале файла или заглавном докблоке класса. |
@author
|
необязательный | Имя автора кода, phpDocumentor будет искать текст между угловыми скобками, <info@hmarketing.ru> |
@copyright
|
необходимый | Информация, указывающая на правообладателя кода |
@license
|
необходимый | Ссылка на лицензию, под которой распространяется код |
@deprecated
|
необязательный | Указывает на то, что код устарел |
@link
|
необязательный | Возможность добавить ссылку к любому документируемому коду |
@see
|
необязательный | Указывает на то, что документация уже существует в другом докблоке |
@since
|
необходим | Версия программного обеспечения, в котором был представлен класс |
DocBlock для свойств класса
| Дескриптор | Требование | Примечания |
|---|---|---|
Summaryкраткое описание |
необходим | Далее следует пустая строка |
@var
|
необязательный | Указывает описание для свойств класса |
@deprecated
|
необязательный | Указывает на то, что код устарел |
@since
|
необходим | Версия программного обеспечения, в котором был представлен класс |
DocBlock для методов класса
| Дескриптор | Требование | Примечания |
|---|---|---|
Summaryкраткое описание |
необходим | Далее следует пустая строка |
Descriptionподробное описание |
необязательный | Далее следует пустая строка |
@param
|
необходим | Описывает входные параметры для функций и методов классов |
@return
|
необходим | Используется для описания данных, возвращаемых функцией или методом класса |
@since
|
необходим | Версия программного обеспечения, в котором был представлен метод |