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