Используя HeaderDoc
HeaderDoc включает два сценария, headerdoc2html (headerDoc2HTML.pl в исходном распределении), который генерирует документацию для каждого заголовка, с которым это встречается, и gatherheaderdoc (gatherHeaderDoc.pl в исходном распределении), который находит эти острова документации и собирает основное оглавление, соединяющее их.
gatherheaderdoc инструмент является сценарием постобработки для HeaderDoc. Его основная цель состоит в том, чтобы взять каталог, содержащий вывод от HeaderDoc, и создать оглавление со ссылками.
gatherheaderdoc инструмент высоконастраиваем. Можно сконфигурировать его, чтобы вставить пользовательские ссылки навигационной цепочки, использовать пользовательский шаблон TOC, и даже автоматически вставить информацию «о платформе» в шаблон TOC, при желании.
Эта глава разделена на три части:
Выполнение headerdoc2html — информация о выполнении
headerdoc2html.Выполнение gatherheaderdoc — информация о выполнении
gatherheaderdoc.
Выполнение headerdoc2html
Как только у Вас есть заголовок, содержащий комментарии HeaderDoc, можно работать headerdoc2html сценарий для генерации вывода HTML как это:
> headerdoc2html MyHeader.h |
Это обработает MyHeader.h и создайте выходной вызванный каталог MyHeader в том же каталоге как входной файл. Для просмотра результатов в веб-браузере откройте файл index.html то, что Вы находите в выходном каталоге.
При необходимости вместо того, чтобы указать единственный входной файл (как выше), можно указать входной каталог. HeaderDoc обработает каждый .h файл во входном каталоге (и все его подкаталоги), генерируя выходной каталог файлов HTML для каждого заголовка, содержащего комментарии HeaderDoc.
HeaderDoc и объектно-ориентированные языки
HeaderDoc обрабатывает C++ и заголовки Objective C почти таким же способом, которым это делает заголовок C. Фактически, пока HeaderDoc не встречается с объявлением класса в заголовке C++, обработка идентична.
Когда HeaderDoc генерирует документацию HTML для C++ или заголовка Objective C, это создает один frameset для заголовка в целом и отдельный framesets для каждого класса, протокола или категории, объявленной в заголовке.
В объявлениях класса Objective C можно использовать @method тегируйте для документирования каждого метода. Так как Objective C является надмножеством C, заголовок мог бы также объявить типы, функции или другой API за пределами любого объявления класса. Вы использовали бы @typedef, @function, и другой C тегирует для документирования этих объявлений.
HeaderDoc записывает уровень управления доступом (общественность, защищенная или частная) элементов API, объявленных в классе C++. Эта информация привыкла к дальнейшей группе элементы API в получающейся документации.
Переключатели командной строки HeaderDoc
HeaderDoc имеет много полезных переключателей командной строки, изменяющих его поведение.
Флаг | Описание | |
|---|---|---|
|
Причины HeaderDoc к содержанию выходного класса как составная страница вместо того, чтобы разбить его в отдельные страницы для функций, типов данных, и т.д. | |
| Указывает, что маркер должен быть явно определен к указанному значению (или 1, если никакое значение не указано) для C предварительная обработка целей. | |
| Обработайте все. С этим флагом HeaderDoc пытается обработать весь файл, включая содержание, не имеющее никакой разметки HeaderDoc. Примечание: Не все языки программирования поддерживают этот флаг. | |
| Говорит HeaderDoc генерировать framesets вместо того, чтобы использовать iframe элементы. Примечание: В HeaderDoc 8.7 необходимо обычно указывать этот флаг из-за проблемы со ссылками, открывающимися на новой странице в находящемся в iframe выводе. Посмотрите Поздно повреждающиеся Ошибки для большего количества информации и патчей. | |
|
Включает включение | |
| Отключает эмиссию документации для функциональных локальных переменных (задокументированный с | |
| Указывает число раздела для использования при генерации содержания страницы справочника с | |
| Проигнорируйте все имена, указанные в тегах HeaderDoc (за исключением анонимных перечислений, в которых никакое имя не предоставлено кодом), и используйте имена, указанные кодом вместо этого. | |
| Включает “внешнее имя только” обработка типа, в которую не документируются имена тега для определений типов (например, | |
| Режим Pipe. В этом режиме HeaderDoc распечатывает получающееся содержание XML или функциональный список (по умолчанию) к стандартному выводу. Можно только обработать единственный файл за один раз в этом режиме. | |
| Противоположность тихих, этот флаг включает параноидальные предупреждения о многих типичных проблемах. | |
|
HeaderDoc причин для включения функций и типов данных от суперкласса в документации дочерних классов (если они обрабатываются сразу). | |
| Тестовый режим HeaderDoc. Обратите внимание на то, что этот тестовый режим только доступен при выполнении из источника tarball, не из установленной системы. Для получения дополнительной информации посмотрите Тестирование HeaderDoc. | |
| Указывает, что маркер должен быть явно не определен для C предварительная обработка целей. | |
|
Причины HeaderDoc для вывода содержания XML вместо HTML. | |
| Говорит HeaderDoc пытаться выровнять параметры функции вертикально после вводной круглой скобки вместо того, чтобы расположить их с отступом единственной вкладкой width. | |
|
Помещает HeaderDoc в «основной» режим. В этом режиме пронумерованные списки автоматически не распознаны и встроили комментарии HeaderDoc, не удалены из объявлений. | |
|
Позволяет Вам добавлять альтернативный конфигурационный файл. Например:
| |
|
Включает дополнительную отладочную информацию. | |
| Указывает исключить список. Файл передал как параметр | |
| Включает режим вывода списка функции. В этом режиме HeaderDoc испускает простой список имен функций, с которыми встречаются и содержание тех функций в легко формат машины-parseable. | |
| Содержание группы на правой стороне группой вместо в алфавитном порядке. | |
|
Говорит HeaderDoc выводить организацию макро-объявлений. | |
| Включает поддержку JavaDoc ( | |
|
Говорит HeaderDoc не генерировать запросы на канал в объявлениях. | |
|
Говорит HeaderDoc генерировать страницу справочника для каждой функции, найденной вместо генерации XML или вывода HTML. | |
| Проигнорируйте имена классов и заголовков, указанных в тегах HeaderDoc, и всегда используйте имена, предоставленные самим кодом. | |
|
Позволяет Вам указывать другой каталог для вывода. Например:
| |
|
Включает препроцессор C. С этим переключателем, любым | |
|
Заставляет HeaderDoc работать тихо (за исключением предупреждений и ошибок). | |
|
HeaderDoc причин для перехода к режиму разделения комментария, в котором это выводит копию заголовочного файла в выходном каталоге, из которого были удалены все комментарии HeaderDoc. | |
|
Включает строгий режим тегирования, в который любые параметры функции, не описанные с | |
|
Отключает сортировку функций, типов данных, и т.д. в оглавлении, таким образом сохраняя исходный порядок файла. Обратите внимание на то, что, если Вы просто хотите сохранить группировки, необходимо использовать | |
| Говорит HeaderDoc информации о печатной версии и выходу. | |
| Причины HeaderDoc для испускания файла Doxygen-тега-style. (Обратите внимание на то, что этот вариант формата файла тега добавляет информацию о наследовании классов, обычно не включающуюся в нормальный файл тега Doxygen.) | |
| Устанавливает формат, используемый для оглавления (левая сторона). Допустимые значения:
| |
| Включает различные флаги, и дополнительная политика проверяет определенный для внутреннего использования Apple. | |
| Интерпретировать | |
| Включайте документацию, отмеченную с |
Большинство этих переключателей может использоваться друг в сочетании с другом. Очевидные исключения -X и -m (XML по сравнению с выводом страницы справочника). При необходимости в и XML и в выводе страницы справочника необходимо указать -X флаг (вывод XML), затем выполняет сценарии hdxml2manxml и xml2man преобразовать вывод XML в страницу справочника самостоятельно.
Выполнение gatherheaderdoc
gatherheaderdoc сценарий сканирует входной каталог (рекурсивно) для любой документации, сгенерированной headerdoc2html. Это создает основное оглавление (названный masterTOC.html по умолчанию — имя может быть изменено путем определения нового имени в конфигурационном файле или путем указания второго параметра). Это также добавляет, что «главная» ссылка ко всей документации устанавливает его посещения, чтобы упростить перейти назад к основному оглавлению.
Вот пример того, как создать документацию для многих заголовков (демонстрационные, предоставленные сценарии), и затем генерировать основное оглавление:
> headerdoc2html -o OutputDir ExampleHeaders |
> gatherheaderdoc OutputDir |
Можно теперь открыть файл OutputDir/masterTOC.html в Вашем браузере для наблюдения связанных наборов документации.
Можно также добавить второй параметр для изменения имени выходного файла. Например:
> headerdoc2html -o OutputDir ExampleHeaders |
> gatherheaderdoc OutputDir MYTOCNAME.html |
На сей раз, gatherheaderdoc создаваемый файл OutputDir/MYTOCNAME.html вместо OutputDir/masterTOC.html.
Для получения дополнительной информации о конфигурировании gatherheaderdoc, посмотрите Основную Конфигурацию HeaderDoc.