Где лучше размещать комментарии

Разработчики Qt, например, пишут всю документацию в .cpp, даже для функций, которые полностью определены в .h

Лучше писать отдельно от кода или вообще не писать.

Определенные страницы да, но описание функций мне кажется лучше все таки комментариями писать. Так больше шанс что документация будет актуальна.

А мне нравится (ИМХО, да) когда документация прямо в заголовочниках, как в ffmpeg, например. Можно читать в каком-нибудь Assistant, а можно нажать F2 на функции, потом PageUp и вот она документация прямо в редакторе...

Но таки да, для простыней а-ля кутешные DetailedDescription такой подход не годится.

Да у ffmpeg красиво оформлено все.

Лучше писать отдельно от кода или вообще не писать.

Отдельно от кода меньше шансов, что при изменении кода ты не забудешь поправить doxygen описания.

Отдельно от кода меньше шансов, что при изменении кода ты не забудешь поправить doxygen описания.

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

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

понятно почему так делают, там просто описание функций и удобно наверное почитать про функцию именно там,

Да, *.h - это интерфейсная часть, и именно там _должно_ быть всё, необходимое для вызова функций/классов извне. Для опенсорса, конечно, это не так критично, как для проприетарщины, в крайнем случае можно и *.cpp посмотреть - но это именно крайний случай, не надо заставлять лезть в реализацию человека, которому для вызова нужен лишь интерфейс.

Ну так будет же документация с генерированная через doxygen, пусть туда лезет лучше.

https://ru.wikipedia.org/wiki/Грамотное_программирование

http://www.sphinx-doc.org/en/stable/

Doxygen это на любителя еботня..

Я пишу в .cpp/.c файлах, ибо они так и так громоздкие, а нормальной IDE вообще пофиг откуда тянуть. Вообще в doxygen документация из заголовочного файла имеет меньший приоритет (т.е. если ты сделаешь ее и в хедере и в .cpp, то IDE или генератор документации или еще что-нибудь, что работает с doxygen, должно брать то, что ты написал в .cpp)

Делать документацию нужно только перед релизом и тогда ничего не забудешь. И за одно не будешь тратить просто так время на ненужные переписывания текстов в процессе разработки.

А потом в команду приходит новый разработчик и офигевает с огромной вообще недокументированной проги.