Нужна ссылка на правила документирования php файлов

[Vano]

Дайте плз ссылку как правильно документировать классы методы, функции, константы, ну в общем всё что нужно.

 

[Vano]

И в частности скажите как правильно написать примерно вот такой коммент

/**
     * Sets the function name to generate unique name of the file
     *
     * @param callable|Closure $functionName The function name must be an instance of Closure or callable
     * signature of Closure: function ($uploadedFile)
     * @param bool $fromConfig Whether to get the option from the application configuration
     * @return $this
     */

 

[Vano]

И Closure в use директиве не прописан. То-есть вызываю так instanceof \Closure.
Поправьте меня плз)

 

[Vano]

А и зачем нужон PHPDocumentor?

 

[c0dex]

@Vano, PSR вроде бы, не?

 

[Vano]

@Vano, PSR вроде бы, не?

Нууу щас покопаюсь...

 

[Vano]

@c0dex, Нууу, там только propose по этому вопросу.

 

[AnrDaemon]

А весь интернет документирован "запросами на комментарии". Тебя это не смущает?

 

[Вурдалак]

А весь интернет документирован "запросами на комментарии". Тебя это не смущает?

Proposal обозначает, что PSR еще не утверждён. И не будет, надеюсь.

 

[AnrDaemon]

Религия? Или есть причины?

 

[Adelf]

Боже.. PSR на пхпдоки... с выходом PHP7 это становится совсем уж абсурдом.

 

[AnrDaemon]

А, в этом смысле. Таки да, абсурд. Мухи (код) отдельно, комментарии - отдельно.

 

[fixxxer]

@param callable|Closure

Closure она и так callable, нет смысла указывать.

А ваще при нормальном дизайне от таких комментариев смысла мало (я про текстовую часть, а не про хинты для ide) - обычно получается что-то типа function performAction performs the action, не вижу смысла их писать везде - только в неочевидных или странных местах. Ну или phpdoc к классу, где описывается его ответственность - там уместно, да.

Вот в приведенном сниппете дизайн явно странный.

Стандартизировать тут непонятно что, де-факто стандарт - это то, что понимает сторм

 

[Vano]

@fixxxer, ну покрайней мере от IDEшки стандарты можно гдето взять?) ну ладно думаю можно, нужно лишь поискать, я думал есть утвержденный стандарт от разработчиков php.

 

[Vano]

Вот в Yii2 мне очень нравится документация. А в Ларавеле наоборот скудная.

 

[fixxxer]

Да ну, у ларавела отличная документация. Вот что раздражает - это __call-ы на __call-ах, очень затрудняет навигацию по сорцам, ну и всякие временные переменные с расхинтовкой через /** @var */ приходится вводить.

 

[fixxxer]

@fixxxer, ну покрайней мере от IDEшки стандарты можно гдето взять?).

Ты, надеюсь, не в блокноте пишешь? Сторм сам прекрасно справляется с генерацией базовых phpdoc-ов, куда там буквы и типы дописывать вроде понятно

А так - https://manual.phpdoc.org/. Но с необходимостью генерации документации по phpdoc-ам я сталкивался ровно один раз - чтобы напечатать много листов бумаги с чем-то умным, а то люди не понимали, за что такие деньги разумеется это никто никогда не читал.

 

[Vano]

Ты, надеюсь, не в блокноте пишешь? Сторм сам прекрасно справляется с генерацией базовых phpdoc-ов, куда там буквы и типы дописывать вроде понятно

А так - https://manual.phpdoc.org/

Нуу значит я пользоватся не умею(стормом) а вообще я хочу перейти на нетБинс, чтоб не "платить" за лицензицю))

 

[fixxxer]

Че там уметь, /** ентер.

Нетбинс - дерьмо, он на простейшем return $this с наследованием ломается, не говоря уж об анализе чуть сложнее чем undefined variable.

 

[Vano]

Не всегда там то что нужно через ентер.
Допустим есть свойство которое в методе я проверяю на соответсвие типу переменной, а phpStorm ставит всего просто @var. А я хочу чтобы пользовательский код знал что ему назначать нужно.

Про нетбинс, именно по этому мне нужно научиться правильно коммментировать)