Написання документації до коду - завдання не найприємніша і радісна, але якщо ви робите великий проект і / або берете участь в командній розробці, то, я б сказав, це річ просто навіть необхідна. Якщо у вас багато різних інтерфейсів, класів, функцій, методів, з різними парметри і вихідними даними, і з цим доводиться працювати більш ніж одному розробнику, дуже здорово мати під рукою опис всіх цих самих класів, їх атрибутів і параметрів, а не бігати кожен раз до розробника і питати який параметр що значить. Це ні в якому разі не скасовує того, що самі назви класів, методів і параметрів повинні мати осмислені імена, але не про це зараз мова. Зараз ми поговоримо про документування вихідних кодів на php. Я для цих цілей використовую такий інструмент як Doxygen.
Що таке Doxygen?
Для тих, хто не в курсі що це таке, коротка довідка. Як написано на сайті проекту:
Doxygen - це кроссплатформенная система документування вихідних текстів, яка підтримує C / C ++, Objective-C, Python, Java, IDL, PHP, C #, Fortran, VHDL і, частково, D.
Дана утилитка є під всі основні платформи: Windows / Linux / MacOS; а деякі ентузіасти навіть портувала її під Solaris / OS / 2 / IRIX / FreeBSD. Так само на сайті є прекрасна документація як в pdf-форматі, так і в chm-форматі. Дуже рекомендую з нею ознайомитися.