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 дозволяє організувати коректне автодоповнення коду.
  • Дозволяє автоматично створювати документацію до коду.
  • Дозволяє пришвидшити рефакторинг коду іншими розробниками.
  • Дозволяє швидко згадати, за що відповідає фрагмент коду, не читаючи вміст функції або методу.
  • Дозволяє описати для інших програмістів особливості використання фрагменту коду.

Див. також[ред.ред. код]

Посилання[ред.ред. код]

Примітки[ред.ред. код]