Используя HeaderDoc

HeaderDoc включает два сценария, headerdoc2html (headerDoc2HTML.pl в исходном распределении), который генерирует документацию для каждого заголовка, с которым это встречается, и gatherheaderdoc (gatherHeaderDoc.pl в исходном распределении), который находит эти острова документации и собирает основное оглавление, соединяющее их.

gatherheaderdoc инструмент является сценарием постобработки для HeaderDoc. Его основная цель состоит в том, чтобы взять каталог, содержащий вывод от HeaderDoc, и создать оглавление со ссылками.

gatherheaderdoc инструмент высоконастраиваем. Можно сконфигурировать его, чтобы вставить пользовательские ссылки навигационной цепочки, использовать пользовательский шаблон TOC, и даже автоматически вставить информацию «о платформе» в шаблон TOC, при желании.

Эта глава разделена на три части:

Выполнение 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 имеет много полезных переключателей командной строки, изменяющих его поведение.

Флаг

Описание

-C

--class-as-composite

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

-D <маркер>

-D <маркер>=<значение>

--defined <маркер>

--defined <маркер>=<значение>

Указывает, что маркер должен быть явно определен к указанному значению (или 1, если никакое значение не указано) для C предварительная обработка целей.

-E

--process-everything

Обработайте все. С этим флагом HeaderDoc пытается обработать весь файл, включая содержание, не имеющее никакой разметки HeaderDoc.

Примечание: Не все языки программирования поддерживают этот флаг.

-F

--old-style-frames

Говорит HeaderDoc генерировать framesets вместо того, чтобы использовать iframe элементы.

Примечание: В HeaderDoc 8.7 необходимо обычно указывать этот флаг из-за проблемы со ссылками, открывающимися на новой странице в находящемся в iframe выводе. Посмотрите Поздно повреждающиеся Ошибки для большего количества информации и патчей.

-H

--insert-header

Включает включение htmlHeader строка, как указано в конфигурационном файле.

-L

--suppress-local-variables

Отключает эмиссию документации для функциональных локальных переменных (задокументированный с @var тегируйте в блоке документации функции). Это позволяет Вам иметь традиционную версию своей документации в общедоступных целях API и большей полной версии во внутренних целях.

-M

--man-section

Указывает число раздела для использования при генерации содержания страницы справочника с -m флаг.

-N

--ignore-all-names

Проигнорируйте все имена, указанные в тегах HeaderDoc (за исключением анонимных перечислений, в которых никакое имя не предоставлено кодом), и используйте имена, указанные кодом вместо этого.

-O

--outer-names-only

Включает “внешнее имя только” обработка типа, в которую не документируются имена тега для определений типов (например, foo в typedef struct foo {...} tdname;).

-P

--pipe-output

Режим Pipe. В этом режиме HeaderDoc распечатывает получающееся содержание XML или функциональный список (по умолчанию) к стандартному выводу. Можно только обработать единственный файл за один раз в этом режиме.

-Q

--paranoid

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

-S

--merge-superclass-docs

HeaderDoc причин для включения функций и типов данных от суперкласса в документации дочерних классов (если они обрабатываются сразу).

-T <режим>

--test <режим>

Тестовый режим HeaderDoc. Обратите внимание на то, что этот тестовый режим только доступен при выполнении из источника tarball, не из установленной системы. Для получения дополнительной информации посмотрите Тестирование HeaderDoc.

-U <маркер>

--undefined <маркер>

Указывает, что маркер должен быть явно не определен для C предварительная обработка целей.

-X

--xml-output

Причины HeaderDoc для вывода содержания XML вместо HTML.

-a

--align-columns

Говорит HeaderDoc пытаться выровнять параметры функции вертикально после вводной круглой скобки вместо того, чтобы расположить их с отступом единственной вкладкой width.

-b

--basic-processing-only

Помещает HeaderDoc в «основной» режим. В этом режиме пронумерованные списки автоматически не распознаны и встроили комментарии HeaderDoc, не удалены из объявлений.

-c

--config-file

Позволяет Вам добавлять альтернативный конфигурационный файл. Например:

headerdoc2html -c myCustomHeaderDocConfigFile.config MyHeader.h

-d

--debugging

Включает дополнительную отладочную информацию.

-e

--exclude-list-file

Указывает исключить список. Файл передал как параметр -e флаг содержит разделенный от новой строки список регулярных выражений Perl. Любое имя файла или путь к файлу, соответствующий любое из этих регулярных выражений, исключены из обработки.

-f

--function-list-output

Включает режим вывода списка функции. В этом режиме HeaderDoc испускает простой список имен функций, с которыми встречаются и содержание тех функций в легко формат машины-parseable.

-g

--group-right-side

Содержание группы на правой стороне группой вместо в алфавитном порядке.

-i

--truncate-function-like-macros

Говорит HeaderDoc выводить организацию макро-объявлений.

-j

--allow-javadoc-syntax

Включает поддержку JavaDoc (/**) маркеры комментария в других языках программирования.

-l

--no-link-requests

Говорит HeaderDoc не генерировать запросы на канал в объявлениях.

-m

--man-page-output

Говорит HeaderDoc генерировать страницу справочника для каждой функции, найденной вместо генерации XML или вывода HTML.

-n

--ignore-apiowner-names

Проигнорируйте имена классов и заголовков, указанных в тегах HeaderDoc, и всегда используйте имена, предоставленные самим кодом.

-o <каталог>

--output-directory <каталог>

Позволяет Вам указывать другой каталог для вывода. Например:

headerdoc2html -o /tmp MyHeader.h

-p

--enable-cpp

Включает препроцессор C. С этим переключателем, любым #define с HeaderDoc разметка влияет на любое содержание, появляющееся после него в том же заголовочном файле, и также влияющее на любое содержание после #include в любом файле, включающем тот заголовочный файл.

-q

--quiet

Заставляет HeaderDoc работать тихо (за исключением предупреждений и ошибок).

-s

--strip

HeaderDoc причин для перехода к режиму разделения комментария, в котором это выводит копию заголовочного файла в выходном каталоге, из которого были удалены все комментарии HeaderDoc.

-t

--enforce-strict-tagging

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

-u

--unsorted

Отключает сортировку функций, типов данных, и т.д. в оглавлении, таким образом сохраняя исходный порядок файла. Обратите внимание на то, что, если Вы просто хотите сохранить группировки, необходимо использовать @group или @functiongroup теги вместо этого.

-v

--version

Говорит HeaderDoc информации о печатной версии и выходу.

-x

--doxytags

Причины HeaderDoc для испускания файла Doxygen-тега-style. (Обратите внимание на то, что этот вариант формата файла тега добавляет информацию о наследовании классов, обычно не включающуюся в нормальный файл тега Doxygen.)

--tocformat

Устанавливает формат, используемый для оглавления (левая сторона). Допустимые значения:

  • default— используйте самый актуальный стиль оглавления (в настоящее время div).

  • div— используйте формат отделения (в настоящее время значение по умолчанию).

  • frames— используйте устаревший формат кадров.

  • iframes— используйте наследство iframes формат.

--apple

Включает различные флаги, и дополнительная политика проверяет определенный для внутреннего использования Apple.

--auto-availability

Интерпретировать #if и #ifdef блоки, содержащие информацию о доступности и автоматически заполняющие информацию о доступности. (Это, вероятно, не полезно для проектов, которые не являются частью OS X.)

--document-internal

Включайте документацию, отмеченную с @internal. По умолчанию эта документация опущена.

Большинство этих переключателей может использоваться друг в сочетании с другом. Очевидные исключения -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.