Я хочу документировать библиотеку с помощью doxygen. Документация будет читаться двумя классами пользователей: Пользователи, которые интересуются только внешним API и разработчиками, которые хотят видеть документацию для всех функций/структур.
Я хотел бы использовать для разделения файлов doxy для создания документации. Есть ли какой-нибудь "тег", который я могу добавить в блок комментариев, чтобы отметить комментарий как внутренний/внешний?
Установите INTERNAL_DOCS:
# The INTERNAL_DOCS tag determines if documentation
# that is typed after a \internal command is included. If the tag is set
# to NO (the default) then the documentation will be excluded.
# Set it to YES to include the internal documentation.
INTERNAL_DOCS = NO
В документации вы можете использовать \internal или @internal с любой степенью детализации (файл, функция и т.д.).
Используйте команду \cond:
\internal (@internal) имеет только зернистость для текущего блока комментариев. Это не позволяет вам каким-либо образом скрыть определение структуры в C.
Самый простой способ сделать это:
\ cond INTERNAL
в верхней части внутреннего файла заголовка и
\ endcond
внизу. Затем в файле конфигурации вы добавляете
ENABLED_SECTIONS = ВНУТРЕННИЙ
чтобы внутренние элементы были включены в документацию.
Этот способ также рекомендуется пользователям Doxygen, например. здесь
Это простое решение, в котором используется тот факт, что вы обычно можете отличать внутреннюю и внешнюю части вашего кода от файлов.
Вы можете просто ограничить входные файлы только теми файлами заголовков, которые вы хотите открыть во внешней документации:
# For internal, we parse all files
INPUT = ./
# For external, we parse only the files containing the public interface
INPUT = include/header1.hpp include/header2.hpp
Это имеет то преимущество, что исходные файлы не нужно изменять (с помощью \internal или @internal).