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

Див. також

[ред. | ред. код]

Примітки

[ред. | ред. код]
  1. fig-standards/phpdoc.md at master · phpDocumentor/fig-standards · GitHub. Архів оригіналу за 31 березня 2016. Процитовано 17 травня 2016.

Посилання

[ред. | ред. код]