Введение

Этот документ описывает, как использовать инструмент HeaderDoc. Это также объясняет, как вставить комментарии HeaderDoc в Ваши заголовки и другие файлы. Этот документ соответствует HeaderDoc 8.0. Для получения информации о предыдущих версиях консультируйтесь с документацией, установленной с Вашим распределением HeaderDoc.

Что такое HeaderDoc?

HeaderDoc является рядом инструментов для встраивания структурированных комментариев в файлах исходного кода и заголовочных файлах, записанных на различных языках и впоследствии создании богатого вывода HTML и XML из тех комментариев. Комментарии HeaderDoc подобны по внешности комментариям Javadoc в исходном файле Java, но традиционные комментарии HeaderDoc обеспечивают немного более формальный набор тегов для разрешения большего управления поведением HeaderDoc.

HeaderDoc прежде всего предназначается для использования на OS X как часть Инструментов Разработчика OS X. Однако в различных версиях, это также использовалось успешно в других операционных системах, включая Linux, Солярис и Mac OS 9. (Ваш пробег может варьироваться.)

В дополнение к традиционной разметке HeaderDoc HeaderDoc 8 поддерживает разметку JavaDoc. HeaderDoc 8 поддерживает широкий диапазон языков:

Также включенный с основным сценарием (headerdoc2html) gatherheaderdoc, служебный сценарий, создающий основное оглавление для всей документации, сгенерированной headerdoc2html. Информация о выполнении gatherheaderdoc предоставлен в Усовершенствованной Конфигурации HeaderDoc и Функциях.

Оба сценария обычно устанавливаются в /usr/bin, как headerdoc2html и gatherheaderdoc.

gatherheaderdoc сценарий также использует вызванный инструмент resolveLinks создать ссылки между документами. Несмотря на то, что Вы, вероятно, не должны будете использовать этот инструмент непосредственно, можно сделать так, если необходимо соединить многократные наборы документации. Этот инструмент описан в Использовании resolveLinks для Разрешения Перекрестных ссылок.

HeaderDoc идет с серией инструментов для генерации страницы справочника, xml2man и hdxml2manxml. Первый инструмент, xml2man, преобразовывает подобный mdoc диалект XML в страницы справочника mdoc-стиля. Второй инструмент, hdxml2manxml, преобразовывает HeaderDoc XML (сгенерированный с флагом-X) в серию .mxml файлов, подходящих для использования с xml2man.

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

Как я получаю его?

HeaderDoc доступен двумя способами. Во-первых, HeaderDoc является частью стандартной установки Инструментов Разработчика OS X. При установке Инструментов Разработчика CD это уже установлено в системе.

Во-вторых, HeaderDoc может быть загружен с Дарвинского исходного набора в http://www .opensource.apple.com/darwinsource/.

Организация этого документа

Этот документ разделен на несколько глав, описывающих различные аспекты комплекта инструментов.