Написание документации к коду — задача не самая приятная и радостная, но если вы делаете большой проект и/или участвуете в командной разработке, то, я бы сказал, это вещь просто даже необходимая. Если у вас много разных интерфейсов, классов, функций, методов, с различными парметрами и выходными данными, и с этим приходится работать более чем одному разработчику, очень здорово иметь под рукой описание всех этих самых классов, их атрибутов и параметров, а не бегать каждый раз к разработчику и спрашивать какой параметр что значит. Это ни в коем случае не отменяет того, что сами названия классов, методов и параметров должны иметь осмысленные имена, но не об этом сейчас речь. Сейчас мы поговорим о документировании исходных кодов на php. Я для этих целей использую такой инструмент как Doxygen.