autogsdoc - Генератор документации GNUstep API и конвертер XML->HTML
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
Инструмент autogsdoc — это утилита командной строки, которая помогает разработчикам создавать справочную документацию для API-интерфейсов GNUstep. Это также позволяет разработчикам писать и поддерживать другую документацию в формате XML и преобразовывать ее в HTML. В частности, autogsdoc:
Извлекайте специальные комментарии, описывающие общедоступные интерфейсы классов, категорий, протоколов, функций и макросов, из исходного кода Objective C (файлы заголовков и, возможно, исходные файлы) в XML-файлы GSDoc.
Преобразование XML-файлов GSDoc, созданных из исходного кода или написанных разработчиками вручную, в HTML.
Создавайте индексы на основе наборов XML-файлов GSDoc, а также конвертируйте их в HTML.
Чаще всего это используется для запуска команды с одним или несколькими именами файлов заголовков в качестве аргументов... инструмент будет автоматически анализировать соответствующие исходные файлы в том же каталоге, что и заголовки (или текущий каталог, или каталог, указанный с помощью DocumentationDirectory). по умолчанию) и создавать файлы GSDoc и HTML в качестве выходных данных. Для достижения наилучших результатов этот режим следует запускать из каталога, содержащего исходные файлы. (Обратите внимание, что, поскольку C является подмножеством Objective C, этот инструмент может работать для документирования функций и других структур C в простом исходном коде C.)
Файлы GSDoc также могут быть предоставлены непосредственно в дополнение или сами по себе и будут преобразованы в HTML. См. HTML-документацию GSDoc или справочную страницу gsdoc(7) для получения информации о формате GSDoc.
Наконец, файлы HTML могут быть переданы в командной строке. Перекрестные ссылки на другие части документации кода, найденные в них, будут переписаны на основе того, что находится в проекте в настоящее время.
Анализатор исходного кода автоматически создаст документы GSDoc со списком методов классов, найденных в исходных файлах, и будет включать текст из специально отформатированных комментариев из исходных файлов.
Любой комментарий, начинающийся с косой черты и двух звездочек, а не с обычной косой черты и одиночной звездочки, считается разметкой GSDoc и используется в качестве описания класса или метода, следующего за ним. Этот текст комментария переформатируется, а затем вставляется в вывод.
Если несколько комментариев связаны с одним и тем же элементом, при необходимости они объединяются разрывом строки (
).Инструмент можно легко использовать для документирования программ, а также библиотек, просто дав ему имя исходного файла, содержащего функцию main() программы — он берет специальные комментарии от этой функции и обрабатывает их особым образом, вставляя их как раздел в конце первой главы документа (при необходимости создает первую главу).
Параметры описаны в разделе Аргументы и значения по умолчанию ниже.
В некоторых случаях выполняется специальная дополнительная обработка, преимущественно в первом комментарии, найденном в исходном файле, из которого могут быть извлечены различные фрагменты разметки GSDoc и помещены в соответствующие места в выходном документе.
В любой строке, где находится AutogsdocSource:, оставшаяся часть строки берется в качестве имени исходного файла, который будет использоваться вместо предположения, что каждый обрабатываемый файл .h использует файл .m того же имя. Вы можете указать несколько строк AutogsdocSource:, где файл заголовка объявляет элементы, определенные в нескольких исходных файлах. Если имя файла является абсолютным, оно используется так, как указано. Если, с другой стороны, это относительный путь, программа ищет исходный файл сначала относительно местоположения заголовочного файла, и, если он там не найден, относительно текущего каталога, в котором работает autogsdoc, и, наконец, относительно каталог, указанный в DocumentationDirectory по умолчанию.
Резюме содержания документа... размещено в заголовке вывода GSDoc.
Описание автора кода — может быть повторено для обработки случая, когда у документа несколько авторов. Помещается в заголовок вывода GSDoc. Для удобства чтения исходника выполняется специальная дополнительная обработка, связанная с автором документа - Любая строка вида
имя <адрес электронной почты>', или
имя <адрес электронной почты>', или
имя' или
имя» будет распознано и преобразовано в элемент author, возможно содержащий элемент email.
Размещается в выводе GSDoc непосредственно перед концом основной части документа и предназначен для использования в качестве приложений, предметного указателя и т. д.
Размещается непосредственно перед любой сгенерированной документацией по классу... предназначен для предоставления общего описания того, как работает документируемый код. Любая документация по функции main() программы вставлена в виде раздела в конце этой главы.
Авторское право на содержание документа... размещено в заголовке вывода GSDoc. Для повышения удобочитаемости исходного текста выполняется специальная дополнительная обработка: любая строка вида «Текст авторского права (C)» будет распознана и преобразована в элемент copy.
Дата редакции документа... помещается в заголовок вывода GSDoc. Если его не указать, инструмент попытается создать значение из тега RCS Date (если он доступен).
Вставляется в документ в начале основной части ... предназначен для введения или содержания страниц и т. д.
Название документа... размещено в заголовке вывода GSDoc. Если его не указать, инструмент сгенерирует собственный заголовок (вероятно, некачественный), поэтому вам следует включить эту разметку вручную.
Идентификатор версии документа... помещается в заголовок вывода GSDoc. Если это значение опущено, инструмент попытается создать значение из тега RCS Revision (если он доступен).
Примечание Только что описанная разметка может использоваться в документации по классу, категории или протоколу... если это так, она извлекается и оборачивает остальную часть документации по классу в качестве главы класса. Остальная часть документации класса обычно вставляется в конец главы, но вместо этого может быть заменена вместо псевдоэлемента
В комментариях, используемых для предоставления текста для описания метода, следующая разметка удаляется из текста и обрабатывается особым образом:
Метод помечен как назначенный инициализатор для класса.
Метод помечен как тот, который подклассы должны переопределять (например, абстрактный метод).
Метод помечен как один из подклассов, который НЕ должен переопределять.
Разметка удаляется из описания и помещается после в выходных данных GSDoc, чтобы метод описывался как соответствующий (или не соответствующий) указанным стандартам.
Как правило, текст в комментариях переформатируется для стандартизации и красивого отступа... переформатирование не выполняется для любого текста внутри элемента
Некоторые общеизвестные константы, такие как YES, NO и nil, заключены в разметку ... .
Имена аргументов метода в описаниях методов заключаются в разметку ... .
Имена методов (начинающиеся с плюса или минуса) заключаются в разметку
Спецификаторы методов, включая имена классов (начинающиеся и заканчивающиеся квадратными скобками), заключаются в разметку
Имена функций (оканчивающиеся на '()'), отличные от 'main()', заключаются в разметку
Инструмент принимает определенные пользовательские значения по умолчанию (которые, конечно, можно указать в качестве аргументов командной строки, добавив «-» перед именем по умолчанию и указав значение после этого, как в -Clean YES):
Если для этого логического значения установлено значение YES, то вместо создания документации инструмент удаляет все файлы GSDoc, созданные в проекте, и все файлы html, созданные на их основе (а также любые файлы, которые были бы созданы из явно перечисленных файлов GSDoc), и окончательно удаляет файл индекса проекта. Единственным исключением из этого является то, что файлы шаблонов GSDoc (т. е. те, которые указаны с использованием аргументов "-ConstantsTemplate...", "-FunctionsTemplate..." и т. д.) не удаляются, если не установлен флаг CleanTemplates.
Этот флаг указывает, должны ли файлы шаблонов GSDoc удаляться вместе с другими файлами, если указан параметр «Очистить». По умолчанию они не удаляются ... поскольку эти шаблоны могли быть созданы вручную и в них просто были вставлены данные.
Укажите имя документа-шаблона, в который должна быть вставлена документация о константах из всех файлов проекта. Это полезно, если константы в исходном коде разбросаны по множеству файлов, и вам нужно сгруппировать их в одно место. Вы несете ответственность за то, чтобы документ базового шаблона (в который вставляется отдельная постоянная документация) содержал всю остальную информацию, которую вы хотите, но для удобства autogsdoc сгенерирует для вас простой шаблон (который вы затем можете отредактировать), если файл не не существует. Вставка происходит непосредственно перед элементом back (или, если он не существует, непосредственно перед концом элемента body) в шаблоне.
Укажите, где заголовки должны быть задокументированы как найденные. Фактическое имя, созданное в документации, формируется путем добавления последнего компонента имени файла заголовка к значению этого значения по умолчанию. Если это значение по умолчанию не указано, используется полное имя файла заголовка (как указано в командной строке) с добавленным по умолчанию HeaderDirectory. Типичным использованием этого может быть «-Declared Foundation» при создании документации для базовой библиотеки GNUstep. Это приведет к тому, что в документации будет сказано, что NSString объявлен в «Foundation/NSString.h».
Этот флаг позволяет вам генерировать документацию для всех переменных экземпляра. Обычно документируются только те из них, которые явно объявлены как «общедоступные» или «защищенные».
Этот флаг позволяет вам полностью отключить документацию для переменных экземпляра. Обычно явно объявленные «общедоступные» или «защищенные» переменные экземпляра будут задокументированы.
Этот флаг, если он установлен, указывает генератору HTML размещать документацию по переменной экземпляра в конце класса, а не в начале. Это полезно, если вы используете много защищенных переменных экземпляра, которые будут представлять второстепенный интерес для обычных пользователей класса.
Может использоваться для указания каталога, в который будет помещена сгенерированная документация. Если это не установлено, вывод помещается в текущий каталог. Этот каталог также используется в крайнем случае для поиска исходных файлов (не заголовков) и, что более важно, он используется в качестве первого и единственного средства для поиска любых файлов .gsdoc, переданных на командная строка. Любая информация о путях, указанная для этих файлов, удаляется, и они ищутся в DocumentationDirectory (даже если они не были созданы автоматически).
Задает имя файла, содержащего список имен файлов, в виде массива списка свойств в формате (name1,name2,...). Если это присутствует, имена файлов в списке аргументов программы игнорируются, и имена в этом файле используются в качестве списка имен для обработки.
Укажите имя шаблонного документа, в который должна быть вставлена документация о функциях из всех файлов проекта. Это полезно, если исходный код функции разбросан по множеству файлов, и вам нужно сгруппировать его в одном месте. Вы несете ответственность за то, чтобы документ базового шаблона (в который вставляется документация по отдельным функциям) содержал всю остальную информацию, которую вы хотите, но для удобства autogsdoc сгенерирует для вас простой шаблон (который вы затем можете отредактировать), если файл не не существует. Вставка происходит непосредственно перед элементом back (или, если он не существует, непосредственно перед концом элемента body) в шаблоне.
Может использоваться, чтобы указать, должен ли быть сгенерирован вывод HTML. По умолчанию ДА.
Может использоваться для указания каталога для поиска файлов заголовков. Если указано, это значение добавляется к относительным именам заголовков, в противном случае относительные имена заголовков интерпретируются относительно текущего каталога. Это значение по умолчанию не влияет на файлы заголовков, указанные как абсолютные пути.
Логическое значение, которое может использоваться для указания того, что программа должна игнорировать время модификации файла и в любом случае перегенерировать файлы. Предоставляется для использования в сочетании с системой make, которая, как ожидается, сама управляет проверкой зависимостей.
Это значение используется для управления автоматическим включением локальных внешних проектов в систему индексации для создания перекрестных ссылок в окончательном выводе документа. Если установлено значение «Нет», то ссылки на локальные проекты не выполняются, в противном случае в «Локальном» каталоге документации GNUstep выполняется рекурсивный поиск файлов с расширением «.igsdoc», и используется информация индексации из этих файлов. Значение этой строки также используется для создания имен файлов в перекрестной ссылке... если это пустая строка, предполагается, что используемый путь является файлом в том же каталоге, где был найден файл igsdoc, в противном случае это используется в качестве префикса имени в указателе. NB. Локальные проекты с тем же именем, что и документируемый в данный момент проект, не будут включены в этот механизм. Если вы хотите включить такие проекты, вы должны сделать это явным образом, используя -Projects...
Укажите имя шаблона документа, в который должна быть вставлена документация о макросах из всех файлов проекта. Это полезно, если код макроса разбросан по множеству файлов, и вам нужно сгруппировать его в одном месте. Вы несете ответственность за то, чтобы документ базового шаблона (в который вставляется документация по отдельным макросам) содержал всю остальную информацию, которую вы хотите, но для удобства autogsdoc сгенерирует для вас простой шаблон (который вы затем можете отредактировать), если файл не не существует. Вставка происходит непосредственно перед элементом back (или, если он не существует, непосредственно перед концом элемента body) в шаблоне.
Имя файла, которое будет использоваться для вывода информации о зависимости для make. Это примет форму списка всех заголовочных и исходных файлов, известных для проекта, как зависимости от имени проекта (см. «Проект»).
Может использоваться для указания имени этого проекта... определяет имя справочного файла указателя, созданного как часть документации для предоставления информации, позволяющей другим проектам делать перекрестные ссылки на элементы этого проекта.
Это значение может быть предоставлено в виде словаря, содержащего пути к индексным/справочным файлам igsdoc, используемым внешними проектами, а также значения, используемые для сопоставления имен файлов, найденных в индексах. Например, если в файле индекса проекта (igsdoc) указано, что класс «Foo» находится в файле «Foo», а путь, связанный с этим индексом проекта, — «/usr/share/doc/proj», то создается html. вывод может ссылаться на класс как находящийся в '/usr/share/doc/prj/Foo.html' . Обратите внимание, что словарь может быть задан в командной строке с использованием стандартного формата PropertyList (а не формата XML OS X), с использованием точек с запятой в качестве разделителей строк и заключения его в одинарные кавычки.
Логическое значение, которое может использоваться для указания того, что программа должна регистрировать, какие файлы регенерируются из-за их зависимости от других файлов.
Логическое значение, используемое для указания, должна ли программа вставлять в документацию информацию о соответствии стандартам. Это следует использовать только при документировании самих библиотек и инструментов GNUstep, поскольку предполагается, что документируемый код является частью GNUstep и, возможно, соответствует стандарту OpenStep или реализует методы, совместимые с MacOS-X.
Это значение используется для управления автоматическим включением внешних системных проектов в систему индексации для создания перекрестных ссылок в окончательном выводе документа. Если установлено значение «Нет», то ссылки на системные проекты не выполняются, в противном случае в каталоге документации GNUstep «Система» выполняется рекурсивный поиск файлов с расширением «.igsdoc», и используется информация индексации из этих файлов. Значение этой строки также используется для создания имен файлов в перекрестной ссылке... если это пустая строка, предполагается, что используемый путь является файлом в том же каталоге, где был найден файл igsdoc, в противном случае это используется в качестве префикса имени в указателе. NB. Системные проекты с тем же именем, что и документируемый в данный момент проект, не будут включены в этот механизм. Если вы хотите включить такие проекты, вы должны сделать это явным образом, используя -Projects...
Укажите имя документа-шаблона, в который должна быть вставлена документация по typedef из всех файлов проекта. Это полезно, если исходный код typedef разбросан по множеству файлов, и вам нужно сгруппировать его в одном месте. Вы несете ответственность за то, чтобы документ базового шаблона (в который вставляется отдельная документация typedef) содержал всю остальную информацию, которую вы хотите, но для удобства autogsdoc сгенерирует для вас простой шаблон (который вы затем можете отредактировать), если файл не не существует. Вставка происходит непосредственно перед элементом back (или, если он не существует, непосредственно перед концом элемента body) в шаблоне.
Строка, используемая для предоставления имени, которое будет использоваться в ссылке «вверх» из сгенерированных документов GSDoc. Обычно это должно быть имя файла, который содержит индекс содержимого проекта. Если это значение отсутствует или задано как пустая строка, то в документах не будет ссылки «вверх».
Укажите имя шаблона документа, в который должна быть вставлена документация о переменных из всех файлов проекта. Это полезно, если переменный исходный код разбросан по множеству файлов, и вам нужно сгруппировать его в одном месте. Вы несете ответственность за то, чтобы документ базового шаблона (в который вставляется документация по отдельным переменным) содержал всю остальную информацию, которую вы хотите, но для удобства autogsdoc сгенерирует для вас простой шаблон (который вы затем можете отредактировать), если файл не не существует. Вставка происходит непосредственно перед элементом back (или, если он не существует, непосредственно перед концом элемента body) в шаблоне.
Логическое значение, используемое для указания, хотите ли вы, чтобы производился подробный вывод отладки/предупреждения.
Логическое значение, используемое для указания, хотите ли вы создавать стандартный вывод предупреждений (например, отчет о недокументированных методах).
Это значение представляет собой словарь, используемый для сопоставления идентификаторов/ключевых слов, найденных в исходных файлах, с другими словами. Обычно вам не нужно использовать это, но иногда полезно избежать путаницы синтаксического анализатора из-за использования макросов препроцессора C. Вы можете эффективно переопределить макрос, сделав его менее запутанным. Значение, на которое вы сопоставляете идентификатор, должно быть одним из следующих: - Другой идентификатор, Пустая строка - значение игнорируется, Две косые черты ('//') - остальная часть строки игнорируется. Обратите внимание, что словарь может быть задан в командной строке с использованием стандартного формата PropertyList (а не формата XML OS X), с использованием точек с запятой в качестве разделителей строк и заключения его в одинарные кавычки.
Значение по умолчанию «Вверх» используется для указания имени документа, который следует использовать в качестве ссылки «вверх» для любых других используемых документов. Это имя не должно включать путь или расширение. Как правило, документ, на который ссылается это значение по умолчанию, должен быть отредактированным вручную документом GSDoc, который должен иметь раздел назад, содержащий индекс проекта. например
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc> Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .htmlНекоторые элементы GSDoc еще не отображаются должным образом в HTML. Это:
Сообщения об ошибках и предупреждения могут поступать на каждом из этапов конвейера: управление верхнего уровня, анализ источника, анализ GSDoc и индексирование.
gsdoc(7), GNUstep(7)
Autogsdoc объединил возможности двух более ранних инструментов, autodoc и gsdoc, которые выполняли переводы исходный->GSDoc и GSDoc->HTML соответственно. Эти более ранние инструменты и формат GSDoc были разработаны для GNUstep на основе более раннего языка GDML SGML.
Эта страница руководства впервые появилась в gnustep-base 1.9.2 (март 2004 г.).
autogsdoc был написан Ричардом Фрит-Макдональдом rfm@gnu.org
Эта страница руководства добавлена Адрианом Робертом arobert@cogsci.ucsd.edu.