Что такое документация и с чем её едят (как правильно, как лучше?)?

Берете phpstorm, пишите функцию/метод. Главное - указать, что принимает и возвращает функция.
По возможности используете тайп хинтинги (явное указание типов аргументов и возвращаемого значения).
alt+enter по названию функции -> generate doc block - phpstorm сгенерил вам док блоки.
Осталось добавить описание к функции сверху и к параметрам справа от них.