LINUX.ORG.RU

Ответ на: комментарий от anonymous_sapiens

Какая разница, на каком языке? Вопрос про doxygen.

Obey-Kun ★★★★★ ()

Зачем загромождать хэдеры развёрнутыми комментариями и описаниями, если предполагается получать полную документацию по API простым путём (с помощью doxygen в твоём случае)? ".c/.cpp" однократно распарсятся во время компиляции, на выходе получишь библиотеку и доку по API. А хэдеры остаются неизменными - нафиг их такие громоздкие таскать в комплекте с библиотекой и парсить лишние килобайты какждый раз при сборке с библиотекой?

Led ★★★☆☆ ()
Ответ на: комментарий от Obey-Kun

Аргумент насчёт громоздкости принят — описания методов и классов/структур/enum'ов вынесу в cpp. А с полями что делать? Тоже выносить?

Obey-Kun ★★★★★ ()
Ответ на: комментарий от Obey-Kun

Кстати, насчёт выноса описаний классов/структур/enum'ов... немного пугает тот факт, что придётся поддерживать одинаковые названия в 2 местах

Obey-Kun ★★★★★ ()
Ответ на: комментарий от Obey-Kun

Ну, описания «классов/структур/enum'ов» придётся оставить в хэдерах - лишний «головняк» для синхронизации не нужен:(

Led ★★★☆☆ ()
Ответ на: комментарий от Led

то же, я так понял, верно и насчёт полей? или нынче все крутые перцы используют d-поинтеры и засирают хедеры уже в них?:)

Obey-Kun ★★★★★ ()
Ответ на: комментарий от Obey-Kun

Какий полей? Если полей структур/классов, то вместе с этими структурами классами.

Возможно, я плохо подумал перед тем как отвечать: мой ответ больше касался C, а в случае C++ бОльшую часть всё равно придётся описывать в хэдерах:(

Led ★★★☆☆ ()

Интерфейсы должны документироваться в файлах .h/.hpp

Реализации должны документироваться в .c/.cpp

anonymous ()
Ответ на: комментарий от anonymous

> Интерфейсы должны документироваться в файлах .h/.hpp

В Qt и куче проектов не так.

Obey-Kun ★★★★★ ()

Я все пишу в одном месте — в .h'никах. Чтобы можно было открыть и сразу понять что к чему. В .cpp файлах комментарии относящиеся к документации обычно не пишую.

Reset ★★★★★ ()
Ответ на: комментарий от Led

Это каког же объема комментарии надо туда запихать, чтобы это сказалось на скорости сборки?

Reset ★★★★★ ()
Ответ на: комментарий от Reset

поменял коммент в хедере — должны пересобраться все о-шки, которые его подключают.

Obey-Kun ★★★★★ ()
Ответ на: комментарий от Obey-Kun

Очевидно, что комментарии обычно меняются при изменении интерфейса.

Reset ★★★★★ ()
Ответ на: комментарий от Reset

во время активного пиления ещё и во время исправлений и уточнений, например

Obey-Kun ★★★★★ ()

В заголовках.

1) описанияй полей, структур (уже сказали)
2) документация имеет больше отношения к API, и независима от реализации

JackYF ★★★★ ()
Ответ на: комментарий от Led

> Зачем загромождать хэдеры развёрнутыми комментариями и описаниями, если предполагается получать полную документацию по API простым путём (с помощью doxygen в твоём случае)? ".c/.cpp" однократно распарсятся во время компиляции, на выходе получишь библиотеку и доку по API. А хэдеры остаются неизменными - нафиг их такие громоздкие таскать в комплекте с библиотекой и парсить лишние килобайты какждый раз при сборке с библиотекой?

Что с вами? Старая трава уже не катит?

andreyu ★★★★★ ()
Ответ на: комментарий от Reset

> Я все пишу в одном месте — в .h'никах. Чтобы можно было открыть и сразу понять что к чему. В .cpp файлах комментарии относящиеся к документации обычно не пишую.

Полностью согласен.

andreyu ★★★★★ ()

В хедерах, потому что это касается интерфейса, а не реализации.

Pavval ★★★★★ ()

С точки зрения комментариев мне очень понравились «лептоника» и gwyddion: в заголовочных файлах более-менее подробное описание структур, сишные файлы содержат общую информацию в «шапке» и сведения о назначении, аргументах и возвращаемом значении перед каждой функцией.

Eddy_Em ☆☆☆☆☆ ()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.