Документация файла заголовка C/С++

Как вы думаете, лучше всего создавать публичные файлы заголовков на С++?

Если заголовочные файлы не содержат никакой, краткой или массивной документации? Я видел все из почти без документации (опираясь на некоторую внешнюю документацию) на большие спецификации инвариантов, действительные параметры, возвращаемые значения и т.д. Я не уверен, что я предпочитаю, большая документация хороша, так как у вас всегда есть доступ к это из вашего редактора, с другой стороны, заголовочный файл с очень краткой документацией может часто показывать полный интерфейс на одной или двух страницах текста, давая гораздо лучший обзор того, что можно сделать с классом.
Скажем, я иду с чем-то вроде краткой или массивной документации. Я хочу что-то похожее на javadoc, где я документирую возвращаемые значения, параметры и т.д. Какое лучшее соглашение для этого в С++? Насколько я помню, doxygen делает хорошие вещи с документацией в стиле java doc, но есть ли какие-либо другие соглашения и инструменты для этого, о которых я должен знать, прежде чем перейти к документации по стилю javadoc?

Ответ 1

Обычно я помещаю документацию для интерфейса (параметры, возвращаемое значение, что делает функция) в файл интерфейса (.h) и документацию для реализации (как это делает функция) в файле реализации (.c,.cpp,.m).

Я пишу обзор класса непосредственно перед его объявлением, поэтому у читателя есть непосредственная основная информация.

Инструмент, который я использую, - Doxygen.

Ответ 2

Я бы определенно имел некоторую документацию в самих файлах заголовков. Это значительно улучшает отладку, чтобы иметь информацию рядом с кодом, а не в отдельных документах. Как правило, я буду документировать API (возвращаемые значения, аргументы, изменения состояния и т.д.) Рядом с кодом и высокоуровневые архитектурные обзоры в отдельных документах (чтобы дать более широкое представление о том, как все складывается; трудно разместить это вместе с кодом, поскольку он обычно ссылается на несколько классов сразу).
Doxygen прекрасен из моего опыта.

Ответ 3

Я считаю, что Doxygen - самая распространенная платформа для создания документации, и, насколько мне известно, она более или менее способна охватывать JavaDoc-нотацию (не ограничиваясь этим, конечно). Я использовал doxygen для C, с результатами OK, я думаю, что он более подходит для С++. Возможно, вы захотите также изучить robodoc, хотя я думаю, что Occam Razor скажет вам скорее пойти на Doxygen.

Что касается документации, я никогда не был поклонником документации, но нравится мне это или нет, имея больше документации, всегда бьющей без документации. Я бы поместил API-документацию в заголовочный файл, а документация по внедрению в реализацию (это понятно, не так ли?).:) Таким образом, у IDE есть возможность забрать его и показать его во время автозаполнения (Eclipse делает это для JavaDocs, например, возможно, также для doxygen?), Которые не следует недооценивать. JavaDoc имеет эту дополнительную причуду, что он использует первое предложение (то есть до первой полной остановки) в качестве краткого описания, не знаю, делает ли Doxygen это, хотя, если это так, его следует принимать во внимание при написании документации.

Наличие большого количества документации сопряжено с риском устаревания, однако хранение документации рядом с кодом даст людям возможность обновить ее, поэтому вы должны обязательно хранить ее в файлах источника/заголовка, Не следует забывать, что это производство документации. Да, некоторые люди будут напрямую использовать документацию (через IDE или что-то еще, или просто читать заголовочный файл), но некоторые люди предпочитают другие способы, поэтому вам, вероятно, стоит рассмотреть возможность размещения вашей (регулярно обновляемой) документации по API в Интернете, все красивое и доступное для просмотра, а также, возможно, создание man файлов, если вы нацеливаете разработчиков на основе nix.

Что мои два цента.

Ответ 4

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

Напишите документацию в форме, которую большинство редакторов распознает, является блоком; для С++ это похоже на /*, а не на //. Таким образом вы можете сложить его и просто увидеть объявления.

Ответ 5

Возможно, вас будет интересовать gtk-doc. Это может быть "немного неудобно для настройки и использования", но вы можете получить хорошую документацию API из исходного кода, выглядя так:

Функции служебной программы String