Здравствуйте, NikeByNike, Вы писали:

NBN>Мы немного корячили доксиджен и с помощью напильника получали довольно сносный формат документации. Правда врядли кто то из разработчиков решится это повторить...

Мой point заключается в том, что писание документации — это такая же вдумчивая работа, как писание кода. Никакая автоматически сгенеренная документация не заменяет нормальной документации, написанной живым человеком специально для этой цели, а не в качестве побочного продукта при кодировании. Да, я понимаю, нету времени, нету людей, дедлайн прошел месяц назад, что очень лень и все такое. Но если, ребята, у вас нет времени написать документацию, то у вас и не будет документации, не надо себя обманывать.

Единственное оправдание держать документацию в исходниках, это пресловутая возможность пройтись по ним доксигеном. Потому что вообще-то в исходниках развесистые комментарии только мешают, затеняя логику самого кода. А так как от доксигеновской документации все равно, см. выше, проку мало, то и незачем ради нее исходники марать.

Назначение комментариев в исходниках — быть именно пояснением к исходникам, а не заменой документации. Именно из этого и следует исходить, выбирая стиль, в котором пишутся комментарии.

Ковырянием же доксигена можно, наверное, повлиять на стиль, в котором он форматирует свой output. Но я говорю совсем не об этом.