Это вещь достаточно распространенная и известная,
я всего лишь расскажу о ее синтаксисе и применении на практике.
Все будет приминительно ООП на PHP.
Сразу оговорюсь, формат применим к классам, их методам и свойствам,
и чтоб в итоге наших трудов мы получили не каляку-маляку из даблслешей,
а красиво написаную документацию, этот формат следует применять.
Итак, пример:
На первый взгляд смотрится не так уж красиво, но есть ряд преимуществ.
Главное преимущество — стандарт. Теперь о приятностях которые дают нам Zend и Eclipse:
В виде hint-подсказки среда разработки показывает нам развернутое описание функции,
где видно какого формата должны быть входные данные и что мы получим в итоге. «Но это еще не все ©»,
существуют системы автоматического создания документации,
и с их помощю можно получить полное описание нашего проекта,
основываясь только на описанных выше комментариях. Как это примерно выглядит:
эта страничка сгенерирована системой phpDocumetor встроенной в ZDE.
Синтаксис для функции или метода
/**
* Имя или краткое описание (класса, метода, свойства, функции)
*
* Развернутое описание
* в несколько строк
*
* @имя_тега значение
* return тип_данных
*/
Синтаксис для свойства
/**
* Описание
*
* var тип_переменной
*/
И на последок список тегов с описанием:
Полный список на phpDocumentor Manual.
я всего лишь расскажу о ее синтаксисе и применении на практике.
Все будет приминительно ООП на PHP.
Сразу оговорюсь, формат применим к классам, их методам и свойствам,
и чтоб в итоге наших трудов мы получили не каляку-маляку из даблслешей,
а красиво написаную документацию, этот формат следует применять.
Практика
Итак, пример:
На первый взгляд смотрится не так уж красиво, но есть ряд преимуществ.
Главное преимущество — стандарт. Теперь о приятностях которые дают нам Zend и Eclipse:
В виде hint-подсказки среда разработки показывает нам развернутое описание функции,
где видно какого формата должны быть входные данные и что мы получим в итоге. «Но это еще не все ©»,
существуют системы автоматического создания документации,
и с их помощю можно получить полное описание нашего проекта,
основываясь только на описанных выше комментариях. Как это примерно выглядит:
эта страничка сгенерирована системой phpDocumetor встроенной в ZDE.
Синтаксис комментариев
Синтаксис для функции или метода
/**
* Имя или краткое описание (класса, метода, свойства, функции)
*
* Развернутое описание
* в несколько строк
*
* @имя_тега значение
* return тип_данных
*/
Синтаксис для свойства
/**
* Описание
*
* var тип_переменной
*/
И на последок список тегов с описанием:
- @access [private | protected | public] (Контроль доступа для элемента)
- @author Антонов А. <andreydust@gmail.com> (Автор текущего элемента)
- @param тип_данных $имя_переменной Описание (Описание для входного параметра)
- return тип_данных Описание (Описывает тип возвращаемых данных функцией или методом)
Полный список на phpDocumentor Manual.
