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

Question

[kotmarvell]

Что такое документация и зачем она? Как правильно писать? Какие есть стили? (Очень прошу примеры, пожалуйста)
Посылать к гуглу не лучший вариант. Я делал это, но при поиске очень много воды.
Так что решил воспользоваться вопросом, раз уж есть такая возможность.

Comments

[Антон Спирин]

Посылать к гуглу не лучший вариант. Я делал это, но при поиске очень много воды.

Учитесь отделять зерна от плевел. Иначе толку от вас, как от разработчика, почти 0.

[kotmarvell]

Антон Спирин, верю, но спросить лишним не будет на начальном этапе

[kotmarvell]

deepin, Документирование кода

[Евгений Ромашкан]

kotmarvell,

верю, но спросить лишним не будет на начальном этапе

Будет. Вы считаете что тостер чем-то отличается от остального интернета, и тут одни профессионалы сидят, а все ответчики обязательно разбираются в том что говорят?
Зря. Информацию уметь фильтровать тут нужно точно ничуть не меньше.

Answer 1

[Konata Izumi]

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