Мы используем doxygen для создания API (справочной) документации для нашего кода. У нас есть небольшой Java API и большой C++ API. Обычным инструментом для API Java является Javadoc, но doxygen может делать и то, и другое, и мы решили использовать один инструмент для обоих.
С помощью Javadoc вы можете добавить обзор любого пакета, добавив в исходный код файл со специальным именем. Затем Javadoc показывает этот обзор с документацией, которую вы хотите включить, а также с документацией по отдельным классам. Обзоры пакетов полезны для объяснения того, как группы связанных классов предназначены для совместного использования, и могут включать диаграммы, примеры и многое другое. Поскольку они являются частью сборки Javadoc, они могут ссылаться на отдельные классы (или методы или другие элементы).
Как мне сделать эквивалент в doxygen как для пакетов Java, так и для пространств имен C++ (которые мы используем как пакеты )? Я знаю, что могу редактировать главную страницу, которая служит обзором всего API, но я хочу больше распространять документацию. Мне не нужна одна обзорная страница; Мне нужна одна обзорная страница для каждого раздела логического кода, и я хочу, чтобы этот обзор находился в том же каталоге, что и код (где он с большей вероятностью будет обновляться).
Есть ли способ сделать это с помощью doxygen, или мне придется писать свои собственные инструменты для добавления файлов в вывод doxygen?
Мы решили эту проблему, добавив обзорные файлы в формате Markdown в исходное дерево и внеся одно небольшое изменение в конфигурацию.
В Doxyfile мы устанавливаем для GENERATE_TREEVIEW значение yes . Это включает оглавление боковой панели, которое необходимо, если вы хотите, чтобы эти обзорные файлы где-то действительно отображались. (Обычно doxygen просто выдает элементы кода — классы, интерфейсы и т. д. Древовидная структура дает вам место для размещения других вещей.) Пока вы редактируете Doxyfile, убедитесь, что для MARKDOWN_SUPPORT установлено значение yes. (Я думаю, что это значение по умолчанию.)
Затем мы добавили один файл Markdown (расширение .md) в каждый подкаталог нашего исходного дерева. Doxygen поддерживает все обычные функции Markdown . Мы назвали каждый файл в соответствии с его содержащим каталогом. Например, в каталоге server мы назвали файл server.md.
В обычном древовидном представлении doxygen есть разделы для пространств имен, классов, файлов и, возможно, других вещей. (Это может варьироваться в зависимости от языка; у нас C++.) Наши дополнительные файлы отображаются в разделе над этими разделами, что имеет смысл — «классы» относятся только к классам, а обзор пакета, который объясняет, как они работают вместе, находится выше. который. Мы не пытались усложнить организацию, так как нам нужно было всего несколько файлов на этом уровне.