Стандарт комментирования кода в PHP

Это вещь достаточно распространенная и известная,
я всего лишь расскажу о ее синтаксисе и применении на практике.
Все будет приминительно ООП на PHP.
Сразу оговорюсь, формат применим к классам, их методам и свойствам,
и чтоб в итоге наших трудов мы получили не каляку-маляку из даблслешей,
а красиво написаную документацию, этот формат следует применять.

Практика

Итак, пример:

На первый взгляд смотрится не так уж красиво, но есть ряд преимуществ.
Главное преимущество — стандарт. Теперь о приятностях которые дают нам Zend и Eclipse:

В виде hint-подсказки среда разработки показывает нам развернутое описание функции,
где видно какого формата должны быть входные данные и что мы получим в итоге. «Но это еще не все ©»,
существуют системы автоматического создания документации,
и с их помощю можно получить полное описание нашего проекта,
основываясь только на описанных выше комментариях. Как это примерно выглядит:

эта страничка сгенерирована системой phpDocumetor встроенной в ZDE.

Синтаксис комментариев

Синтаксис для функции или метода
/**
* Имя или краткое описание (класса, метода, свойства, функции)
*
* Развернутое описание
* в несколько строк
*
* @имя_тега значение
* return тип_данных
*/

Синтаксис для свойства
/**
* Описание
*
* var тип_переменной
*/
И на последок список тегов с описанием:

• @access [private | protected | public] (Контроль доступа для элемента)
• @author Антонов А. <[e-mail]> (Автор текущего элемента)
• @param тип_данных $имя_переменной Описание (Описание для входного параметра)
• return тип_данных Описание (Описывает тип возвращаемых данных функцией или методом)

Полный список на phpDocumentor Manual.