hs.doc.builder

Создаёт файлы поддержки документации. Ещё находится в стадии эксперимента.

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

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

Документация для модулей и пакетов должна быть встроена в исходный код соответствующего объекта в специальных строках комментариев. Очень краткий пример форматирования документации можно найти по адресу https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md#documentation, но планируется более подробное руководство.

Большая часть этого подмодуля должна рассматриваться на стадии «Проверка концепции» и потребует дополнительных работ с вашей стороны для генерации полезной документации в форматах HTML, Markdown или Docset. В будущем это должно измениться.

Обзор API

Функции — API-вызовы, предлагаемые непосредственно расширением

genComments
genJSON
genSQL

Документация API

Функции

genComments

Подпись	`hs.doc.builder.genComments(path, [recurse]) -> table`
Тип	Функция
Описание	Генерирует таблицу документации для модулей Hammerspoon или пакетов Spoon из исходных файлов, расположенных в указанном пути или путях.
Параметры	where — строка, определяющая один путь или таблица, содержащая несколько строк, определяющих пути, где должны быть проверены исходные файлы для генерации таблицы документации. recurse — необязательный булев параметр, по умолчанию true, определяющий, нужно ли проверять файлы в подкаталогах указанного пути для поиска строк комментариев.
Возвращаемые значения	table — таблица, содержащая документацию, разбитую на пары ключ-значение, используемые для генерации документации, отображаемой `hs.doc` и `hs.doc.hsdocs`.
Примечания	Поскольку Hammerspoon и все известные в настоящее время доступные модули написаны на Objective-C и/или Lua, в указанных пути(ях) проверяются только файлы с расширением .m или .lua. Пожалуйста, отправьте вопрос (или запрос на добавление, если вы сами изменяете этот подмодуль) по адресу https://github.com/Hammerspoon, если вам нужно изменить это для вашего дополнения.
Исходный код	extensions/doc/doc_builder.lua строка 37

genJSON

Подпись	`hs.doc.builder.genJSON(source) -> string`
Тип	Функция
Описание	Генерирует строковое представление JSON документации, указанной в источнике. Этот формат ожидается `hs.doc` и `hs.doc.hsdoc`, и используется для предоставления встроенной документации для Hammerspoon.
Параметры	source — источник для генерации JSON-строки. Если это строка, она передаётся в hs.doc.builder.genComments, а результат используется. Если это таблица, предполагается, что она уже сгенерирована вызовом hs.doc.builder.genComments.
Возвращаемые значения	string — строковое представление документации в формате JSON
Примечания	Если у вас установлен инструмент командной строки `hs` (см. `hs.ipc`), вы можете использовать следующее для генерации файла `docs.json`, который используется для предоставления документации для пакетов Hammerspoon Spoon: `hs -c "hs.doc.builder.genJSON(\"$(pwd)\")" > docs.json` Вы также можете использовать это для генерации документации для любых модулей сторонних разработчиков, которые вы создаёте, но вам придётся зарегистрировать документацию с помощью `hs.doc.registerJSONFile` самостоятельно — она не загружается автоматически, как это происходит для пакетов Spoons.
Исходный код	extensions/doc/doc_builder.lua строка 194

genSQL

Подпись	`hs.doc.builder.genSQL(source) -> string`
Тип	Функция
Описание	Генерирует SQL-команды, необходимые для создания индекса поиска при создании набора документов документации.
Параметры	source — источник для генерации SQL-команд. Если это строка, она передаётся в hs.doc.builder.genComments, а результат используется. Если это таблица, предполагается, что она уже сгенерирована вызовом hs.doc.builder.genComments.
Возвращаемые значения	string — соответствующие SQL-команды в виде строки
Исходный код	extensions/doc/doc_builder.lua строка 170

© 2014–2017 Hammerspoon contributors
Licensed under the MIT License.
https://www.hammerspoon.org/docs/hs.doc.builder.html