Маркеры символа для документации HTMLBASED

Поскольку HeaderDoc генерирует документацию для ряда заголовочных файлов, это вводит названные привязки (<a name=”marker”></a>) в HTML для маркировки расположения документации для каждого символа API. Этот документ описывает состав этих маркеров.

Как Вы будете видеть, каждый маркер сам описание и может ответить на вопросы, такие как:

С этой встроенной информацией документация HTML может быть отсканирована для создания списков API в различных целях. Например, такой список мог использоваться, чтобы проверить, что все объявили, что API имеет соответствующую документацию. Или, документация могла быть отсканирована для создания индексов различных видов. Сценарий сканирования мог также создать гиперссылки от индексов до исходной документации. Короче говоря, эти привязки сохраняют, по крайней мере, часть семантической информации, обычно теряющейся при преобразовании материала в формат HTML.

Строка маркера

Строка маркера определяется как:

marker := prefix '/' lang-type '/' sym-type '/' sym-value

Маркер является строкой, составленной из двух или больше значений, разделенных наклонной чертой вправо (/). Символ наклонной черты вправо используется, потому что это не допустимый символ на имена символа ни для одного из языков в настоящее время на рассмотрении.

Префикс определяет этот маркер как соответствующий нашим соглашениям и помогает идентифицировать эти маркеры для сканеров. Тип языка определяет язык символа. Тип символа определяет некоторую семантическую информацию о символе, такой как, является ли это именем класса или именем функции. Значение символа является строкой, представляющей символ.

Поскольку строка должна быть закодирована как часть URL, это должно повиноваться очень строгому ряду правил. В частности любые символы кроме букв и чисел должны быть закодированы как объект URL. Например, оператор + в C++ был бы закодирован как %2b.

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

Определенные в настоящее время типы языка описаны в Таблице b-1.

Табличные b-1 HeaderDoc API  ссылочные типы языка

applescript

Сценарий AppleScript

c

C заголовок или исходный код

cpp

Заголовок C++ или исходный код

doc

Специальное пространство имен в целях документации. (Содержание нужно считать неструктурированным за исключением специальных форм, отмеченных в Специальных Ссылочных типах API в документе Иерархия.)

idl

Файл Языка описания интерфейса.

Примечание: Это значение является значением по умолчанию если никакое значение для IDLLanguage установлен в конфигурационном файле. Посмотрите Основную Конфигурацию HeaderDoc для получения дополнительной информации.

java

Заголовок Java

js

Сценарий JavaScript

Примечание: Некоторые исторические реализации использовали строку javascript.

mig

Описание интерфейса Генератора Интерфейса Маха

occ

Заголовок Objective C или исходный код

pascal

Исходный код Паскаля

perl

сценарий perl

php

Сценарий PHP

python

Сценарий Python

ruby

Сценарий Ruby

shell

Граница, Korn, Граница Снова или сценарий оболочки C

tcl

Сценарий TCL

Тип языка определяет привязку к языку символа. Некоторые логические символы могут быть доступными больше чем на одном языке. c язык определяет символы, которые можно вызвать от языковой семьи C (C, Objective C и C++).

Типы символа для всех языков

Символ вводит характерный для всех языков, описаны в Таблице b-2.

Табличный b-2  Символ вводит для всех языков

тег

структура, объединение или перечислимый тег

econst

перечислимая константа — т.е. символ, определенный в перечислении

tdef

имя определения типа (или Паскаль type)

macro

макро-имя (без' ()')

data

глобальная переменная, экземпляр или статические файлом данные

func

имя функции (без' ()')

Типы символа для языков с классами

cat

Название категории (только Objective C).

cl

Имя класса.

Примечание: В Perl это используется для имен пакетов, и таким образом имена могут содержать двойное двоеточие между частями имен пакета. Например:

//apple_ref/perl/cl/HeaderDoc::APIOwner

clconst

Постоянные значения, определенные в классе. Например:

//apple_ref/java/clconst/ClassName/kConstantName
clm

Класс (или статичный [в Java или C++]) метод.

Примечание: Форматы для имен методов описаны в Objective C (occ) Формат Имени метода и C++ / Java (cpp/java) Формат Имени метода.

data

Данные экземпляра. Например:

//apple_ref/cpp/data/MyClass/MyVariable
intf

Интерфейс или имя протокола.

intfcm

Метод класса определяется в протоколе

Примечание: Форматы для имен методов описаны в Objective C (occ) Формат Имени метода и C++ / Java (cpp/java) Формат Имени метода.

intfm

Метод, определенный в интерфейсе (или протокол).

Примечание: Форматы для имен методов описаны в Objective C (occ) Формат Имени метода и C++ / Java (cpp/java) Формат Имени метода.

intfp

Свойство, определенное в интерфейсе (или протокол)

//apple_ref/occ/intfp/ClassName/PropertyName
instm

Метод экземпляра.

Примечание: Форматы для имен методов описаны в Objective C (occ) Формат Имени метода и C++ / Java (cpp/java) Формат Имени метода.

instp

Свойство Instance. Например:

//apple_ref/occ/instp/ClassName/PropertyName

C++ (cpp) типы символа

tmplt

Шаблон класса C++.

ftmplt

Шаблон функции C++.

Примечание: Формат для этого типа описан в C++ / Java (cpp/java) Формат Имени метода.

func

C++ определил объем функции (другими словами, не экстерн 'C'); включает тип возврата и подпись, как описано в C++ / Java (cpp/java) Формат Имени метода, но без имени класса. Например:

//apple_ref/cpp/func/funcName/returnType/(argType,argType,argType)

Objective C (occ) формат имени метода

Формат для имен методов для Objective C:

class_name '/' method_name
e.g.: //apple_ref/occ/instm/NSString/stringWithCString:

Для методов в категориях Objective C название категории не включено в маркер имени метода. Класс назвал используемым, класс, на котором определяется категория. Например, для windowDidMove: метод делегата для NSWindow, маркер был бы:

e.g.: //apple_ref/occ/intfm/NSObject/windowDidMove:

Формат свойства Objective C

Формат для протокола Objective C:

class_name '/' protocol_name
e.g. //apple_ref/occ/instp/MyClass/MyProp

C++ / Java (cpp/java) Формат Имени метода

Формат для имен методов для Java и C++:

    class_name '/' method_name '/' return_type '/' '(' signature ')'
e.g.: //apple_ref/java/instm/NSString/stringWithCString/NSString/(char*)

Для Java и C++, подписи являются частью имени метода; подписи включаются в круглые скобки. Алгоритм для кодирования подписи:

  1. Удалите название параметра; например, change (Foo *bar, int i) к (Foo *, int ).

  2. Удалите пробелы; например, изменение (Foo *, int ) к (Foo*,int).

Соедините интерфейсом с форматом привязки разработчика

Формат для Интерфейсной привязки Разработчика:

'binding' '/' class_name '/' binding_name
e.g. //apple_ref/occ/binding/myclass/mybinding

Специальные Ссылочные типы API в документе Иерархия

В целом, doc иерархия должна считаться непрозрачным блобом содержания. Вы не должны рассчитывать на структуру a doc Ссылка API. Однако существует несколько специальных подтипов в doc пространство, которые являются значительными и должны использоваться только в формулируемой цели.

  • uid— Уникальный идентификатор для документа. Можно использовать значения, сгенерированные uuidgen здесь. Все другие значения резервируются для использования Apple.

  • title:...— HeaderDoc-специфичная иерархия для специальных идентификаторов сгенерирована от части имени комментария HeaderDoc. Они сгенерированы когда:

    • Имя указано в комментарии HeaderDoc, не соответствующем проанализированного имени.

    • Объявление анализируется, который не имеет никакого имени (такого как анонимное перечисление), и указанное имя содержит пробелы или другие запрещенные символы.

    Полное имя для этой ссылочной части зависит от имени исходного типа данных. Например, определение типа было бы:

    //apple_ref/doc/title:tdef/Whatever

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

  • enumconstant, functionparam, methodparam, defineparam, structfield, typedeffield— Специальные ссылочные типы для полей в структурах, параметров в функциях, и т.д. Появляется в важном моменте в документации.

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

    enumconstant поле должно только появиться если нормальный ссылочный маркер API (econst) не делает, что означает, что Вы вряд ли будете фактически видеть этот тип маркера на практике.

  • anysymbol— Допустимый в запросах на канал только. Запрос на канал в этом пространстве имен заставляет преобразователь ссылки искать символ по имени вместо ссылкой API. Например, запрос на канал:

    //apple_ref/doc/anysymbol/MyProject

    соответствовал бы любую из следующих ссылок API:

    //apple_ref/c/func/MyProject
    //apple_ref/cpp/instm/MyClass/MyProject/bool/(char*,int)
    //apple_ref/perl/data/MyProject
    //apple_ref/java/cl/MyProject

    И т.д. Если больше чем один из этих символов существует, он соответствует самый близкий символ в иерархии (как определено числом продвижения частей абсолютного пути).

Используя ссылки API в теге @link

Когда ссылочный маркер API появляется в комментарии, он точно походит на нормальный ссылочный маркер API за одним исключением: в любой точке, где наклонная черта появляется, законно предшествовать той наклонной черте с наклонной чертой влево. Причина этого может быть продемонстрирована следующим маркером символа:

    //apple_ref/cpp/instm/MyClass/MyMethod/void*/(char*,int)

Заметьте это */ появляется в маркере символа, который обычно заканчивал бы комментарий во многих языках программирования. Для фиксации этого Вы настроили бы символ для сходства с этим:

/* ...
    @link //apple_ref/cpp/instm/MyClass/MyMethod/void*\/(char*,int) ... @/link
 ...
 */

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

Используя resolveLinks для Разрешения Перекрестных ссылок

HeaderDoc включает вызванный инструмент resolveLinks (в /usr/bin или Xcode.app/Contents/Developer/usr/bin начало в 8,8, в /System/Library/Perl/Extras/PERL_VERSION/HeaderDoc/bin в предыдущих версиях), который используется для разрешения перекрестных ссылок для Вас Везде, где перекрестная ссылка появляется, сгенерирована ссылка, если существует место назначения.

resolveLinks инструмент обрабатывает все дерево содержания в двух передачах. В первой передаче это определяет местоположение целевых привязок. Эти целевые привязки похожи на это:

<a name="//apple_ref/..."></a>

Каждый из них name значения являются идентификатором для символа API. Формат для этих идентификаторов указан в Строке Маркера.

Во второй передаче, resolveLinks поиски перекрестных ссылок на эти места назначения. Эти перекрестные ссылки могут произойти в одной из двух форм, в зависимости от того, как ли место назначения, известно, существует или нет.

<a logicalPath=“//apple_ref/...“ href="path">foo</a>
<!-- a logicalPath=“//apple_ref/...“ -->

Каждый из них logicalPath значения тогда соединяются (если возможный) с name значения получены во время первой передачи. Если место назначения существует для перекрестной ссылки, resolveLinks вставляет относительный путь целевой привязки в запросе перекрестной ссылки href атрибут. Результат состоит в том, что привязка перекрестной ссылки является теперь допустимой ссылкой к требуемой целевой привязке.

Если ссылка существует, и запрос перекрестной ссылки находится в форме комментария, resolveLinks инструмент изменяет запрос перекрестной ссылки из комментария в привязку (ссылка) тег. Точно так же, если место назначения не существует, это изменяет перекрестную ссылку от тега привязки до тега комментария. Результат состоит в том, что никогда не должно быть никаких неработающих ссылок.

По большей части этот процесс очевиден для Вас как пользователь. Существует два исключения, однако: перекрестные ссылки между наборами документа и перекрестные ссылки с помощью многократных ссылочных префиксов API (такой как apple_ref).

Разрешение конфликтных ссылок API

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

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

Используя многократные ссылочные префиксы API

Если Вы используете многократные ссылочные префиксы API в единственном дереве выходного содержания и хотите соединить его вместе использование resolveLinks, необходимо сказать resolveLinks для поиска всех префиксов, Вы заботитесь о. Существует два способа сделать это:

  • Выполненный resolveLinks вручную, указание -r флаг для каждого префикса. Например:

    resolveLinks -r david_ref -r joe_ref /path/to/dir

  • Укажите список допустимых префиксов в Вашем headerDoc2HTML.config файл с помощью externalAPIUIDPrefixes опция.

    Примечание: Этот конфигурационный файл читается gatherHeaderDoc, не resolveLinks. Таким образом эта установка конфигурационного файла влияет на поведение resolveLinks только, когда resolveLinks выполняется gatherHeaderDoc, не, когда Вы работаете resolveLinks вручную.

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

Каждый раз, когда resolveLinks обрабатывает дерево, оно генерирует файл перекрестной ссылки для того содержания. По умолчанию это сохранило этот файл как /tmp/xref_out, но можно изменить это с -x флаг для более позднего использования.

Если Вы хотите обработать дерево в режиме только для чтения (не написав изменения в ответ в самом дереве), можно указать -n (никакая запись) флаг. В этом режиме это генерирует выходной файл перекрестной ссылки, но не изменит файлы ввода HTML.

Начало в HeaderDoc 8.8, resolveLinks поддерживает дополнительные флаги для использования в своих интересах этих файлов перекрестной ссылки. Как правило, Вы использовали бы некоторую комбинацию -s, -S, -b, и -i флаги.

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

Является самым простым объяснить эти флаги путем обеспечения примера случая общего использования. У Вас есть два каталога, A и B.

Текущее расположение

Заключительное расположение

/Users/myusername/A

/Library/WebServer/Documents/Tools/A

/Users/myusername/B

/Library/WebServer/Documents/Utilities/B

Для создания этих ссылок Вы сначала генерировали бы файлы перекрестной ссылки для каждой папки как это:

resolveLinks -n -x /tmp/A.xrefs -b "$PWD/" "A"
resolveLinks -n -x /tmp/B.xrefs -b "$PWD/" "B"

Пути в получающемся файле перекрестной ссылки находятся в форме A/... или B/....

Затем, необходимо фактически разрешить ссылки. Это - то, где другие флаги играют роль.

resolveLinks -b "$PWD/" -s /tmp/B.xrefs -S "/Library/WebServer/Documents/Utilities/" -i "/Library/WebServer/Documents/Tools/" "A"
resolveLinks -b "$PWD/" -s /tmp/A.xrefs -S "/Library/WebServer/Documents/Tools/" -i "/Library/WebServer/Documents/Utilities/" "B"

Можно передать в многократных парах -s и -S флаги (максимум до 1 024) для дополнительной гибкости. Для каждого файла семени необходимо сначала использовать -s флаг для указания расположения самого файла семени затем используйте -S флаг для указания расположения, где будет в конечном счете установлено содержание, описанное тем файлом семени.

Кроме того, для отбора путей к файлам необходимо также использовать -i флаг для сообщения resolveLinks где будет в конечном счете установлена папка, которую Вы обрабатываете. Обратите внимание на то, что как прежде, -b флаг определяет, какую часть разделить от каждого пути в папке Вы обрабатываете, и что запаздывающая наклонная черта в -b флаг является значительным здесь также.

В действительности можно думать о флагах как это:

  • -b— Снимает изоляцию с ведущих частей пути от папки, которую Вы в настоящее время обрабатываете. Последняя часть пути разделяется только если сопровождаемый запаздывающей наклонной чертой.

  • -i— Добавляют ведущие части пути к папке, которую Вы в настоящее время обрабатываете (представление предложенного заключительного расположения установки).

  • -S— Добавляют ведущие части пути к папкам, обработанным ранее и импортированным из файла семени (представляющий их предложенные заключительные расположения установки).

Наконец при желании можно передать -a флаг для сообщения resolveLinks использовать абсолютные пути вместо относительных путей при соединении с содержанием, описанным определенным файлом семени или всеми файлами семени. Как -S флаг, если передано перед первым -s флаг, -a флаг изменяет соединяющееся поведение глобально. Иначе, это изменяет только соединяющееся поведение для предыдущего -s флаг.

Для получения дополнительной информации см. страницу руководства для resolveLinks.