Вперед Назад

Усовершенствованная конфигурация HeaderDoc и функции

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

Создание шаблонного файла TOC

Файлы шаблона TOC являются в основном обычными файлами HTML. Они могут содержать любое содержимое HTML. В дополнение к содержимому HTML они могут также содержать условное содержимое HTML — т.е. содержание, только включенное, если соблюдены определенные условия. Наконец, они могут включать различные списки.

Шаблонная поддержка особенно мощна, когда объединено с поддержкой платформ (который, в целях HeaderDoc, по существу свободная группировка связанной документации, сохраненной в том же выходном каталоге).

Вот специальные теги, указывающие содержание списка или условное выражение:

$$title@@: Вводит «Фу Доцумэньтатиона», где Фу является именем платформы.
$$tocname@@: Указывает имя основного файла TOC. Полезный, когда используется с многократными шаблонами целевой страницы, как описано в Использовании Многократных Шаблонов Целевой страницы.
$$framework@@: Указывает полное имя платформы, как указано @framework тег в .hdoc файл.
$$frameworkabstract@@: Вставляет краткий обзор платформы, как указано @abstract тег в .hdoc файл.
$$frameworkdir@@: Вставляет "краткое название” платформы. Это определяется путем взятия имени файла “.hdoc” файл и снятие изоляции .hdoc расширение). Это имя также предварительно ожидается к имени дополнительного шаблона целевой страницы, как описано в Использовании Многократных Шаблонов Целевой страницы.
$$frameworkdiscussion@@: Вставляет обсуждение платформы, как указано @discussion тег (или неявно как часть @framework тег) в .hdoc файл.
$$frameworkuid@@: Вставляет платформу привязка UID.
$$headersection@@: Запустите условного блока для заголовков. Если не будет никаких перечисленных заголовков, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/headersection@@: Конец условного блока для заголовков.
$$headerlist@@: Список всех заголовков в выходном каталоге.
$$classsection@@: Запустите условного блока для классов. Если не будет никаких перечисленных классов, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/classsection@@: Конец условного блока для классов.
$$classlist@@: Список всех классов в выходном каталоге.
$$categorysection@@: Запустите условного блока для категорий. Если не будет никаких перечисленных категорий, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/categorysection@@: Конец условного блока для категорий.
$$categorylist@@: Список всех категорий в выходном каталоге.
$$protocolsection@@: Запустите условного блока для протоколов. Если не будет никаких перечисленных протоколов, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/protocolsection@@: Конец условного блока для протоколов.
$$protocollist@@: Список всех протоколов в выходном каталоге.
$$datasection@@: Запустите условного блока для данных (глобальные переменные и константы). Если не будет никаких перечисленных элементов данных, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/datasection@@: Конец условного блока для данных (глобальные переменные и константы).
$$datalist@@: Список всех элементов данных в выходном каталоге.
$$typesection@@: Запустите условного блока для типов. Если не будет никаких перечисленных типов, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/typesection@@: Конец условного блока для типов.
$$typelist@@: Список всех типов в выходном каталоге.
$$functionsection@@: Запустите условного блока для функций или методов. Если не будет никаких функций или перечисленных методов, то содержание между этим тегом и заключительной условной меткой блока не появится.
$$/functionsection@@: Конец условного блока для функций или методов.
$$functionlist@@: Список всех функций/методов в выходном каталоге.

Значение по умолчанию тегов списка к необработанному списку (отдельный столбец) без границы. Однако можно изменить число столбцов, таблицы width, и граничить довольно легко. Например:

    $$functionlist cols=3 order=down atts=border=”0” cellpadding=”1” cellspacing=”0” width=”420”@@

указывает, что таблица составит три столбца, перечисленные вниз первый столбец, тогда вниз следующий столбец, и т.д. Это также указывает что дополнительные атрибуты border, cellpadding, cellspacing, и width будет вставлен в тег таблицы автоматически. Обратите внимание на то, что atts параметр должен быть последним перечисленным параметром.

nogroups

gatherheaderdoc инструмент обычно разделяет записи группировкой TOC. Если Вы хотите, чтобы этот список включал все в единственный список, добавьте этот флаг. Для примера см. алфавитный список всех страниц руководства OS X как часть Страниц справочника OS X.

cols

Указывает число столбцов в таблице. (Обратите внимание на то, что число строк не может быть указано, поскольку оно вычисляется на основе числа столбцов и числа записей в таблице.), Например, Вы могли бы указать cols=3.

order

Указывает, должна ли таблица читать через или вниз. Если Вы указываете order=across, первая запись будет в верхней левой ячейке, второй будет вправо и т.д. Если Вы указываете order=down, вторая запись будет ниже первой записи. Значение по умолчанию снижается.

trclass

Указывает класс CSS, которому применятся к <tr> (строка таблицы) тегирует в таблице. Например, Вы могли бы указать trclass=toctrclass.

tdclass

Указывает класс CSS, которому применятся к <td> (ячейка данных таблицы) тегирует в таблице. Например, Вы могли бы указать tdclass=toctdclass.

notable

Отключает генерацию таблиц. При указании этой опции каждая запись будет разделена a <br> (разрыв строки) тег, сопровождаемый новой строкой. Это прежде всего предназначается для генерации списка, который может быть легко обработан с инструментами пользователя, но она может быть объединена с CSS для создания некоторых интересных и полезных разметок также.

addempty

Эта опция говорит gatherheaderdoc включать пустые ячейки, содержащие неразрывный пробел для заполнения неиспользуемых слотов в последней строке таблицы. Значение по умолчанию, addempty=0, просто закроет заключительную строку таблицы рано. Для добавления дополнительных пустых ячеек (по мере необходимости) для заполнения последней строки в таблице указать addempty=1.

Это обычно имеет значение очень мало, если Вам не включили границы таблицы (atts=border=1, например).

atts

Указывает список атрибутов, которые будут добавлены к <table> тег. Это не атрибуты CSS, хотя Вы могли указать атрибуты CSS путем указания atts=style=“CSS props here”. Все до закрытия @@ маркер включен как часть atts опция.

Например:

    $$functionlist nogroups cols=3 order=down trclass=mytrclass tdclass=mytdclass notable addempty=1 atts=border=”0” cellpadding=”1” cellspacing=”0” width=”420”@@

Используя многократные шаблоны целевой страницы

HeaderDoc не ограничивается единственным шаблоном целевой страницы. Можно генерировать многократные целевые страницы с различным содержанием при желании. Чтобы сделать это, Вы могли бы создать два шаблонных вызванные файла toctemplate.html и functions.tmpl, тогда добавьте строку в своем конфигурационном файле как это:

TOCTemplateFile => toctemplate.html functions.tmpl

Когда Вы работаете gatherheaderdoc, Вы теперь получите две целевых страницы HTML, один для каждого шаблона.

Первый шаблонный файл, toctemplate.html, обрабатывается как «основная» шаблонная страница. gatherheaderdoc инструмент генерирует целевую страницу на основе того шаблона с именем файла, указанным masterTOCName переменная в конфигурационном файле (masterTOC.html по умолчанию).

После первого шаблонного файла, каждый дополнительный шаблонный файл (functions.tmpl, в этом случае), используется для создания целевой страницы HTML, имя которой получено из «краткого названия» платформы (имя .hdoc файл с .hdoc расширение сняло изоляцию с конца), сопровождаемый тире, сопровождаемым шаблонным именем файла (ни с кем “.html” или “.tmpl” расширения), сопровождаемый “.html”.

Например, если .hdoc файл вызывают MyFramework.hdoc, этот второй индексный файл вызвали бы MyFramework-functions.html.

Так как эти шаблоны могут использоваться для генерации многократных документов, Вы не должны указывать этот весь путь в своих шаблонных файлах, как бы то ни было. Вместо этого необходимо указать его относительно имени платформы. Сделать это, в Вашем toctemplate.html файл, необходимо соединиться с индексом функций как это:

<A href="$$frameworkdir@@-functions.html">Functions Index</A><p>

«Кратким названием» платформы автоматически заменят вместо $$frameworkdir@@ ключевое слово. Точно так же в шаблоне функций, можно соединиться с основным TOC как это:

<A href="$$tocname@@">Headers Index</A><p>

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

Пример gatherheaderdoc Шаблон

Следующее является шаблоном в качестве примера для gatherheaderdoc:

<html>

 <head>

 <title>API Reference: Device Drivers (Kernel/IOKit)</title>

 <style type="text/css"><!--#pagehead {

    FONT-WEIGHT: bold; FONT-SIZE: 32px; COLOR: #000000;

    FONT-FAMILY: lucida grande, geneva, helvetica, arial, sans-serif; }

    td { font-size: 10px; } a:link {text-decoration: none;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    color: #0000ff;} a:visited {text-decoration: none;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    color: #0000ff;} a:visited:hover {text-decoration: underline;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    color: #ff6600;} a:active {text-decoration: none;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    color: #ff6600;} a:hover {text-decoration: underline;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    color: #ff6600;} h4 {text-decoration: none;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    font-size: tiny; font-weight: bold;} body {text-decoration: none;

    font-family: lucida grande, geneva, helvetica, arial, sans-serif;

    font-size: 10pt;} -->

 </style>

 </head>

 <Meta name="ROBOTS" content="NOINDEX">

<body bgcolor="#ffffff">

<center>

<!-- start of header -->

<!--#include virtual="/path/to/header.html"-->

<!-- end of header -->

<table border="0" cellpadding="0" cellspacing="0" width="600">

    <tr height="5">

        <td width="600" height="5"><br>

        </td>

    </tr>

    <tr>

        <td width="600">

            <div id="pagehead">$$framework@@</div>

        </td>

    </tr>

    <tr height="10">

        <td width="600" height="10"><br>

        </td>

    </tr>

    <tr>

        <td valign="top" width="600"><font face="Geneva,Helvetica,Arial"

        size="2"><span id="bodytext"> $$frameworkdiscussion@@ </span></font>

        </td>

    </tr>

    <tr height="10">

        <td height="10" width="600"></td>

    </tr>

    <tr height="5">

        <td height="5" width="600">

            <hr alt="">

            <br>

        </td>

    </tr>

    <tr>

        <td width="600" align="center" valign="top">

            <H2>Headers</H2>

                $$headerlist cols=3 order=down atts=border="0"

                cellpadding="1" cellspacing="0" width="420"@@

        <H2>Functions</H2>

                $$functionlist cols=3 order=down atts=border="0"

                cellpadding="1" cellspacing="0" width="420"@@

        </td>

    </tr>

</table>

</center>

</body>

</html>

Используя препроцессор C

Начинаясь в HeaderDoc 8.5, HeaderDoc содержит основную реализацию препроцессора C (включил с -p флаг). Поскольку HeaderDoc не имеет доступа к полной среде времени компиляции заголовков, ее поведение может отличаться от нормальных препроцессоров C в определенных случаях. В этом разделе описываются некоторые из тех различий.

Парсинг правил

Большинство #define даже если препроцессор включен, макросы не анализируются по умолчанию. Это разрешает Вам как пользователь выбирать который макросы обработать.

Если какое-либо следующее является истиной, макросы обрабатываются:

Им предшествует блок комментария HeaderDoc.
Они появляются между началом и концом класса, которому предшествует блок комментария HeaderDoc.

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

Умножьтесь - определенные макросы

HeaderDoc не пытается обработать #if, #ifdef, или #ifndef директивы. Это, при определенных обстоятельствах, может привести к повторным определениям a #define директива, если включен препроцессор. Как с большинством препроцессоров, все такие определения проигнорированы за исключением того, кажущегося первым в файле.

Это сделано немного более осложненным правилами парсинга, описанными в Парсинге Правил.

Встроенные комментарии HeaderDoc в макросе

С большинством типов данных комментарии HeaderDoc, появляющиеся в типе данных, связаны с самим типом данных. Это обычно - истина для #define макросы также. Однако то поведение создало бы проблему, когда препроцессор C включен, поскольку разумно позволить макросам определять содержание, которое будет унесено в класс, и то содержание могло потенциально включать разметку HeaderDoc.

Поэтому то, когда препроцессор C включен, встроило обработку HeaderDoc, отключен для #define макросы. Любая разметка HeaderDoc в организации такого макроса будет унесена в том, везде, где макрос используется и будет только обработан в получающемся контексте.

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

Обработка #include

Реализация HeaderDoc #include ведет себя по-другому, чем Вы могли бы ожидать. Различия включают следующее:

Никакое понятие путей.
Поскольку включать пути не указаны, как они с компилятором, HeaderDoc не может обоснованно определить это <dir1/file.h> и <dir2/file.h> отличны. Поэтому обработке файлов с тем же именем в различных каталогах обескураживают.
Обязательная защита рекурсии.
Поскольку HeaderDoc не обрабатывает #if, #ifdef, и #ifndef условные выражения, HeaderDoc осуществляет защиту рекурсии, не позволяя файлу быть обработанным дважды. Как только файл обрабатывается, предварительно скомпилированная копия его макросов сохранена для будущего использования и автоматически вставляется каждый раз, когда другой #include запросы это.
Это вызывает два побочных эффекта. Во-первых, a #include если заголовок включает т.е. не может быть изменен контекстно-зависимым способом — <a.h> и затем <b.h>, макросы, определенные в <a.h> не будет влиять на синтаксический анализ <b.h> если <b.h> включает <a.h> самостоятельно.
Во-вторых, #include ведет себя во многом как #import. Результат - это если <a.h> включает <b.h> который включает <c.h> который включает <a.h>, продвижение определений до перевключения <a.h> не будет влиять на путь <a.h> анализируется.
Макро-содержание будет показано в выводе документации.
Вместо того, чтобы пытаться перенести вокруг некоторого понятия исходных маркеров, считанных из файла, HeaderDoc вставляет макросы в дерево синтаксического анализа, как будто измененная версия была считана из файла. Это означает, что не возможно, например, для HeaderDoc показать Вам неизменное определение макроса, включающего другой макрос.

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

Другие проблемы

Некоторые общие подобные функции макросы препроцессора предопределены в самом HeaderDoc для предотвращения проблем синтаксического анализа с заголовками Набора I/O. Они не будут, вероятно, влиять на Вас, но необходимо знать о них.

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

Наконец, HeaderDoc действительно делает основную строку и символьную обработку, даже в макросах. В результате несогласованные одинарные и двойные кавычки в a #define макрос может вызвать серьезные проблемы.

Что, если я не Хочу Видеть Макросы в Документации?

Большую часть времени, наличие #define макросы, определенные в документации, полезны. В некоторых случаях, тем не менее, макросы становятся столь большими и уродливыми, что Вы просто хотите избавиться от них. Поэтому HeaderDoc имеет @parseOnly тег.

Например:

/*! This is an ugly internal macro. @parseOnly */

#define CreateStructors \

    /*! Constructor */ \

    blah(); \

    /*! Destructor */ \

    ~blah();

Путем добавления этого тега в конце блока комментария HeaderDoc для макроса макрос будет анализироваться и использоваться препроцессором, но не появится в документации.

Вперед Назад