Документация по заголовочному файлу C / C ++ [закрыто]

Question

Как вы думаете, что является наилучшей практикой при создании общедоступных заголовочных файлов на C ++?

1. Должны ли заголовочные файлы не содержать краткой или объемной документации?Я видел все, от почти полного отсутствия документации (полагаясь на некоторую внешнюю документацию) до больших спецификаций инвариантов, допустимых параметров, возвращаемых значений и т.д.Я не уверен, что именно я предпочитаю, большая документация хороша, поскольку у вас всегда есть доступ к ней из вашего редактора, с другой стороны, заголовочный файл с очень краткой документацией часто может отображать полный интерфейс на одной или двух страницах текста, давая гораздо лучший обзор того, что можно сделать с классом.

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

Answer 1

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

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

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

Answer 2

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

2. По моему опыту, с Doxygen все в порядке.

Answer 3

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

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

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

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

Answer 4

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

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

Answer 5

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

Строковые Служебные функции