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