PHPDoc
PHPDoc — це адаптований стандарт документування Javadoc для використання в PHP. Наразі[коли?] стандарт коментування має лише неформальний статус, проте, планується його закріплення як одного зі стандартів розробки PHP-фреймворків, котрий розробляє група PHP-FIG. Стандарт, який розробляється, отримає номер PSR-5[1]. PHPDoc підтримує як об'єктно-орієнтований, так і процедурний код.
Синтаксис ред.
Doc-блоки (англ. DocBlock comments) — багаторядкові коментарі в стилі С, розміщені перед елементом, який коментується. Першим символом в коментарі (і на початку кожного рядка коментаря) повинен бути * (символ зірочки). Блоки розділяються порожніми рядками.
Таким чином, Doc-блок поміщається в контейнер, який починається з символів /** та закінчується */.
Для внутрішніх рядків контейнера всі whitespace-символи, які розташовані до першого символу *, ігноруються
Приклад Doc-блока для функції, яка отримує md5-хеш з сіллю:
/**
* Це Doc-блок для функції, яка отримує md5-хеш з сіллю
*
* @param $str Вхідний рядок, від якого потрібно отримати хеш
* @return string
*/
function foo($str)
{
global $salt;
return md5($salt.$str);
}
Застосування ред.
- Застосовується для формального опису коду.
- Дозволяє визначити необхідні типи даних вхідних змінних, результату, який отримується внаслідок виконання певних блоків коду.
- Завдяки підтримці в IDE дозволяє організувати коректне автодоповнення коду.
- Дозволяє автоматично створювати документацію до коду.
- Дозволяє пришвидшити рефакторинг коду іншими розробниками.
- Дозволяє швидко згадати, за що відповідає фрагмент коду, не читаючи вміст функції або методу.
- Дозволяє описати для інших програмістів особливості використання фрагменту коду.
Див. також ред.
Примітки ред.
- ↑ fig-standards/phpdoc.md at master · phpDocumentor/fig-standards · GitHub. Архів оригіналу за 31 березня 2016. Процитовано 17 травня 2016.
Посилання ред.
- (англ.)Офіційний сайт проекту [Архівовано 12 лютого 2009 у Wayback Machine.]