hs.doc

Создание объектов документации для интерактивной справки в Hammerspoon

Созданный объект документации представляет собой таблицу с методами мета-преобразования tostring, позволяющими получить доступ к документации конкретных функций путем добавления пути к методу или функции к созданному объекту.

Из консоли Hammerspoon:

  doc = require("hs.doc")
  doc.hs.application

Результатом будет:

  Manipulate running applications

  [submodules]
  hs.application.watcher

  [subitems]
  hs.application:activate([allWindows]) -> bool
  hs.application:allWindows() -> window[]
      ...
  hs.application:visibleWindows() -> win[]

По умолчанию, внутренняя документация ядра и части руководства Lua 5.3, расположенного по адресу http://www.lua.org/manual/5.3/manual.html, уже зарегистрированы для включения в этот объект документации, но вы можете зарегистрировать дополнительную документацию из модулей сторонних разработчиков с помощью hs.registerJSONFile(...).

Подмодули

Обзор API

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

help
locateJSONFile
preloadSpoonDocs
registeredFiles
registerJSONFile
unregisterJSONFile

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

Функции

help

Подпись	`hs.doc.help(identifier)`
Тип	Функция
Описание	Выводит документацию по определенным частям API Hammerspoon и Lua 5.3. Эта функция также была переименована как `hs.help` и `help` в качестве сокращения для использования в консоли Hammerspoon.
Параметры	identifier - Строка, содержащая подпись определенной части API Hammerspoon (например, `"hs.reload"`)
Возвращаемые значения	Ничего
Примечания	Эта функция предназначена в основном для получения справки по API во время использования консоли Hammerspoon. Файлы документации, зарегистрированные с помощью hs.doc.registerJSONFile или hs.doc.preloadSpoonDocs, которые еще не были загружены, будут загружены при вызове этой команды в любом из описанных ниже форматов. Вы также можете получить результаты этой функции с помощью следующих методов из консоли: help("prefix.path") -- нужны кавычки, например `help("hs.reload")` help.prefix.path -- кавычки не нужны, например `help.hs.reload` `prefix` может быть одним из следующих: `hs` - предоставляет документацию по встроенным командам и модулям Hammerspoon `spoon` - предоставляет документацию по установленным на вашей системе Spoons `lua` - предоставляет документацию по версии Lua, используемой Hammerspoon, в настоящее время 5.3 `lua._man` - предоставляет оглавление руководства Lua 5.3. Вы можете получить доступ к определенному разделу руководства Lua, включив в него главу (и подраздел) следующим образом: `lua._man._3_4_8`. `lua._C` - предоставляет документацию, конкретно касающуюся Lua C API, для использования при разработке модулей, требующих внешних библиотек. `path` представляет собой один или несколько компонентов, разделенных точкой, определяющих модуль, подмодуль, функцию или метод, для которых вы хотите получить документацию.
Исходный код	extensions/doc/doc.lua строка 139

locateJSONFile

Подпись	`hs.doc.locateJSONFile(module) -> path \| false, message`
Тип	Функция
Описание	Определяет JSON-файл, соответствующий указанному модулю сторонних разработчиков или Spoon, путем поиска в package.path и package.cpath.
Параметры	module - имя модуля, для которого требуется найти JSON-файл
Возвращаемые значения	путь к JSON-файлу или `false, error` в случае невозможности найти соответствующий JSON-файл.
Примечания	JSON-файл должен называться 'docs.json' и располагаться в той же директории, что и файл `lua` или `so`, используемый при загрузке модуля через `require`. Документация для основных модулей хранится в JSON-файле, указанном в переменной `hs.docstrings_json_file`; эта функция предназначена для поиска файла документации для модулей сторонних разработчиков и Spoons.
Исходный код	extensions/doc/doc.lua строка 171

preloadSpoonDocs

Подпись	`hs.doc.preloadSpoonDocs()`
Тип	Функция
Описание	Определяет все файлы документации установленных Spoon и помечает их для загрузки при следующем вызове функции hs.doc.help.
Параметры	Нет
Возвращаемые значения	Нет
Исходный код	extensions/doc/doc.lua строка 216

registeredFiles

Подпись	`hs.doc.registeredFiles() -> table`
Тип	Функция
Описание	Возвращает список зарегистрированных JSON-файлов.
Параметры	Нет
Возвращаемые значения	таблица, содержащая список зарегистрированных JSON-файлов
Примечания	Таблица, возвращаемая этой функцией, имеет мета-таблицу, содержащую метод __tostring, позволяющий просмотреть список зарегистрированных файлов, просто набрав `hs.doc.registeredFiles()` в консоли Hammerspoon. По умолчанию, внутренняя документация ядра и части руководства Lua 5.3, расположенного по адресу http://www.lua.org/manual/5.3/manual.html, уже зарегистрированы для включения в этот объект документации. Вы можете отменить регистрацию этих значений по умолчанию, если хотите начать с чистого листа, выполнив следующие команды: `hs.doc.unregisterJSONFile(hs.docstrings_json_file)` - для отмены регистрации документации API Hammerspoon `hs.doc.unregisterJSONFile((hs.docstrings_json_file:gsub("/docs.json$","/lua.json")))` - для отмены регистрации документации Lua 5.3.
Исходный код	extensions/doc/doc.lua строка 109

registerJSONFile

Подпись	`hs.doc.registerJSONFile(jsonfile, [isSpoon]) -> status[, message]`
Тип	Функция
Описание	Регистрация JSON-файла для включения при генерации внутренней документации Hammerspoon.
Параметры	jsonfile - Строка, содержащая расположение JSON-файла isSpoon - необязательный булевый параметр, по умолчанию false, указывающий, что документация должна быть добавлена к заголовку `spoons` в иерархии документации.
Возвращаемые значения	status - булевый флаг, указывающий, был ли файл зарегистрирован или нет. Если файл не был зарегистрирован, то также возвращается сообщение об ошибке.
Примечания	эта функция просто регистрирует файл документации; он фактически не будет загружен и проанализирован до тех пор, пока не будет вызван hs.doc.help.
Исходный код	extensions/doc/libdoc.m строка 264

unregisterJSONFile

Подпись	`hs.doc.unregisterJSONFile(jsonfile) -> status[, message]`
Тип	Функция
Описание	Удаление JSON-файла из списка зарегистрированных файлов.
Параметры	jsonfile - Строка, содержащая расположение JSON-файла
Возвращаемые значения	status - булевый флаг, указывающий, был ли файл исключен из регистрации или нет. Если файл не был исключен из регистрации, возвращается сообщение об ошибке.
Примечания	Для этой функции требуется перестроение всей структуры документации для всех оставшихся зарегистрированных файлов, поэтому при следующем запросе справки с помощью hs.doc.help может быть небольшая задержка.
Исходный код	extensions/doc/libdoc.m строка 303