Где на ваш взгляд лучше помещать документирующие комментарии (.h.hpp vs .c.cpp)

В заголовке

/thread

Без аргументов?

Наводящий вопрос: у всех библиотек доступны c/cpp файлы?

Наводящий вопрос: у всех библиотек доступны c/cpp файлы?

Наводящий ответ: Да, допустим.

Скажем, если документируются не интерфейсы, а весь код.

Что значит весь код?

Срр файлы, вестимо.

В заголовах документируется API, в cpp - реализация.

Наводящий ответ: Да, допустим.

Как правило, библиотеки бывают проприеторастическими, а там что доступно - заголовки и всё. Так что я за хедеры.

Но пожалуй slovazap более прав - в хедерах API правильно описывать, а в CPP реализацию можно прокомментировать. Так делают в некоторых библиотеках.

Но пожалуй slovazap более прав - в хедерах API правильно описывать, а в CPP реализацию можно прокомментировать. Так делают в некоторых библиотеках.

Да, я это и пытался сказать. Но лучше писать так, чтобы в коде комментарии сводились к минимуму. Разве уж совсем необходимо.

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

Есть мнение, что Doxygen-комментарии в заголовочных файлах слишком их захламляют и мешают ознакамливаться с интерфейсом модуля.

Лучше всего писать документацию в файлах .java, или на худой конец .py. В файлах .h и .cpp лучше вообще ничего не писать, и вообще отойти от них подальше.

http://iron-sport.ru/media/k2/items/cache/18cb4412b3fd96d4c2c15944894f7ea5_L.jpg

там, где её берёт генератор документации
если это qt, то в cpp (для qdoc)

Что серьезно? Над этим вопросом еще и думать надо?

Если ты пишешь документацию в cop файлах, то лучше сразу в окно выходить.

Лучше в .cpp. Иначе заголовок превратиться в сплошную документацию и по нему довольно трудоемко будет понять, интерфейс класса и его реализацию.

Наводящий вопрос: у всех библиотек доступны c/cpp файлы?

Почти у всех. Мало кто станет использовать в проекте библиотеку без исходников. Даже если библиотека в бинарном виде (установлена из бинарного пакета), от нее будет документация (исходники также будут доступны). Возможно, в заголовочном файле полезно оставить однострочное описание.

Как правило, библиотеки бывают проприеторастическими

Библиотеки без исходников - скорее исключение. Кроме того, тебе документация нужна, а не исходники.

Есть мнение, что написать скрипт, который удалит все комментарии из кода дело пяти минут. Вот только зачем это делать, когда Doxygen генерирует прекрасные html странички, которые описывабт код просто замечательно?

Половина родных библиотек для Windows и Visual Studio без исходников, только с заголовками и все едят и радуются.

При использовании Doxygen интерфейс класса изучается не в исходнике hpp/h.

На случай, когда в системе нет Doxygen, gtk-doc, и прочих генераторов, наверное.

В документации по doxygen достаточно примеров, еще код KDE - образец.

Обычно уже сгенерированная дока в виде html страничек лежит вместе с проектом.

Вот только зачем это делать, когда Doxygen генерирует прекрасные html странички, которые описывабт код просто замечательно?

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

Собственно это же самое касается и всяких питонов и хипстерских rust где документацию принято херачить прямо в методах. Достаточно посмотреть некоторые компоненты с большой долей документации чтобы убедиться как это «удобно» без обмазывания убогими IDE.

Нормальные IDE умеют сворачивать комментарии. Не вижу проблем. Уверен, даже vim можно научить такому поведению (у меня вроде так и было).

+100. Комментарии не мешают читать код. А иногда помогают его не читать вообще, если дока достаточно понятная.