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

[Winston]

Тема хорошая, но статья не понравилась (Сам уже давно использую phpDoc). По моему, Вы сами плохо знаете синтаксис phpDoc, и для примеров лучше всё-таки приводить ООП PHP5.

1. В самом начале вашего примера не понятно, к чему относится коментарий: к классу или файлу, необходимо 2 коментария.
2. В случае, если функция ничего не возвращает, необходимо это указывать (@return void).

Лучше всего конечно изучать по офф. документации.

[VladimirS]

Я бы еще добавил
@package и @staticvar
Первый относится к хорошему стилю программирования (если вы пишете классы, то возможно захотите включить их в библиотеку), а последний просто часто используется.

[harvester]

Присоединяюсь, @package — обязательно, или из иерархии в доке будет каша, еще пользую @since — но это больше для себя :)

[zt50]

а не подскажете ли вы более полнуб статью по этому делу? с хорошими примерами. Здесь хороший пример, но оооочень хочется рассмотреть тему более полно.
Как использовать тот же package и на что он будет влиять?

Я понимаю на оф. сайте есть описания всех этих полей, но я с ними разобрался :(

[harvester]

Честно говоря я разбирался по документации, без статей :)
Для работы (что бы документации получалась удобной) надо меньше десятка тегов. Самое главное — это описательная часть, не стоит экономить на словах :)

@package — говорит документору, какие классы объединены логически и должны находиться в документации рядом. Запутанно как-то получилось... ну вот например:
есть класс Message и его предок MessageImpl + его предок protoUser, если не ставить @package — будет создано 3 раздела. Я ставлю для первых двух @package Message, для последнего @package protoUser — получается два раздела, что более логично, т.к. первые два — это одна сущность.
Не обязательно включать в @package только родственников, хотя и аналогом package из Java я бы это не назвал. Начинай файл каждого класса словами:
/**
* @version ....
* @package ....
*/
остальные теги по вкусу :)

Удачи.

[zt50]

спасибо!

[abba]

Вроде бы как стало стандартом.

[long]

вообще говоря есть такая штука - стандарт кодирования - которая применяется в рамках проекта/компании. для примера - http://tony2001.phpclub.net/doc/standard…

[qazwsx]

Может кто-нибудь опишет все более грамотно? Мне очень интересно.

А то по кусочкам комментариев сложно понять.

[Devgru]

А можно phpDocumentator использовать без ZDE? Я так и не смог его настроить (XP,apache2,php5)

[kolen]

Очень просто ставится под виндой с помощью PEAR.
pear upgrade phpdocumentor — и всё.

[alexzzam]

А нет ли стандартного способа прикрутить PHPDoc к Eclipse, чтобы доки генерировались по нажатию кнопки, как в Zend?

[davv]

есть, например, метод родительского класса:

/**
*…
*
* @param int $id
* @return __CLASS__
*/
public static function findById( $id) {
return new self();
}

что правильно написать вместо «__CLASS__», чтобы при использовании метода из каждого пронаследованного класса, например:

$obj = Child1:: findById( 1);

в подсказке писалось, что возвращается объект класса Child1, ну и потом при написании «$obj->» выскакивал весь список методов Child1.

надеюсь, понятно написал :)