diff options
author | Jon Heinritz <jon.heinritz@protonmail.com> | 2024-05-22 01:24:14 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-05-21 16:24:14 -0700 |
commit | b8f3ed3903430033f638b17f7455b8fd3d6a85b5 (patch) | |
tree | 41806a1c4e413eae93c8eb8953cad2d4f9074c9c | |
parent | 00f9d91391b04b1935e2f15948bd96cc111e7d3a (diff) |
docs: better type definitions for top-level functions (#410)
* docs: extract conform.format(opts) into it's own class
* docs: extract conform.format_lines(opts) into it's own class
* refactor: use new nvim_doc_tools capability to remove duplicated class definition
---------
Co-authored-by: Steven Arcangeli <stevearc@stevearc.com>
-rw-r--r-- | README.md | 2 | ||||
-rw-r--r-- | doc/conform.txt | 2 | ||||
-rw-r--r-- | lua/conform/init.lua | 38 | ||||
-rwxr-xr-x | scripts/generate.py | 18 |
4 files changed, 34 insertions, 26 deletions
@@ -538,7 +538,7 @@ Format a buffer | Param | Type | Desc | | | -------- | ---------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| opts | `nil\|table` | | | +| opts | `nil\|conform.FormatOpts` | | | | | timeout_ms | `nil\|integer` | Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true. | | | bufnr | `nil\|integer` | Format this buffer (default 0) | | | async | `nil\|boolean` | If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded. | diff --git a/doc/conform.txt b/doc/conform.txt index 185a6d8..99ba786 100644 --- a/doc/conform.txt +++ b/doc/conform.txt @@ -113,7 +113,7 @@ format({opts}, {callback}): boolean *conform.forma Format a buffer Parameters: - {opts} `nil|table` + {opts} `nil|conform.FormatOpts` {timeout_ms} `nil|integer` Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true. diff --git a/lua/conform/init.lua b/lua/conform/init.lua index b02f890..20048a9 100644 --- a/lua/conform/init.lua +++ b/lua/conform/init.lua @@ -364,19 +364,21 @@ M.resolve_formatters = function(names, bufnr, warn_on_missing) return all_info end +---@class conform.FormatOpts +---@field timeout_ms nil|integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true. +---@field bufnr nil|integer Format this buffer (default 0) +---@field async nil|boolean If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded. +---@field dry_run nil|boolean If true don't apply formatting changes to the buffer +---@field formatters nil|string[] List of formatters to run. Defaults to all formatters for the buffer filetype. +---@field lsp_fallback nil|boolean|"always" Attempt LSP formatting if no formatters are available. Defaults to false. If "always", will attempt LSP formatting even if formatters are available. +---@field quiet nil|boolean Don't show any notifications for warnings or failures. Defaults to false. +---@field range nil|table Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode +---@field id nil|integer Passed to |vim.lsp.buf.format| when lsp_fallback = true +---@field name nil|string Passed to |vim.lsp.buf.format| when lsp_fallback = true +---@field filter nil|fun(client: table): boolean Passed to |vim.lsp.buf.format| when lsp_fallback = true + ---Format a buffer ----@param opts? table ---- timeout_ms nil|integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true. ---- bufnr nil|integer Format this buffer (default 0) ---- async nil|boolean If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded. ---- dry_run nil|boolean If true don't apply formatting changes to the buffer ---- formatters nil|string[] List of formatters to run. Defaults to all formatters for the buffer filetype. ---- lsp_fallback nil|boolean|"always" Attempt LSP formatting if no formatters are available. Defaults to false. If "always", will attempt LSP formatting even if formatters are available. ---- quiet nil|boolean Don't show any notifications for warnings or failures. Defaults to false. ---- range nil|table Range to format. Table must contain `start` and `end` keys with {row, col} tuples using (1,0) indexing. Defaults to current selection in visual mode ---- id nil|integer Passed to |vim.lsp.buf.format| when lsp_fallback = true ---- name nil|string Passed to |vim.lsp.buf.format| when lsp_fallback = true ---- filter nil|fun(client: table): boolean Passed to |vim.lsp.buf.format| when lsp_fallback = true +---@param opts? conform.FormatOpts ---@param callback? fun(err: nil|string, did_edit: nil|boolean) Called once formatting has completed ---@return boolean True if any formatters were attempted M.format = function(opts, callback) @@ -477,15 +479,17 @@ M.format = function(opts, callback) end end +---@class conform.FormatLinesOpts +---@field timeout_ms nil|integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true. +---@field bufnr nil|integer use this as the working buffer (default 0) +---@field async nil|boolean If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded. +---@field quiet nil|boolean Don't show any notifications for warnings or failures. Defaults to false. + ---Process lines with formatters ---@private ---@param formatter_names string[] ---@param lines string[] ----@param opts? table ---- timeout_ms nil|integer Time in milliseconds to block for formatting. Defaults to 1000. No effect if async = true. ---- bufnr nil|integer use this as the working buffer (default 0) ---- async nil|boolean If true the method won't block. Defaults to false. If the buffer is modified before the formatter completes, the formatting will be discarded. ---- quiet nil|boolean Don't show any notifications for warnings or failures. Defaults to false. +---@param opts? conform.FormatLinesOpts ---@param callback? fun(err: nil|conform.Error, lines: nil|string[]) Called once formatting has completed ---@return nil|conform.Error error Only present if async = false ---@return nil|string[] new_lines Only present if async = false diff --git a/scripts/generate.py b/scripts/generate.py index e671ce0..30c3b12 100755 --- a/scripts/generate.py +++ b/scripts/generate.py @@ -11,11 +11,11 @@ from nvim_doc_tools import ( dedent, generate_md_toc, indent, - parse_functions, + parse_directory, read_nvim_json, read_section, - render_md_api, - render_vimdoc_api, + render_md_api2, + render_vimdoc_api2, replace_section, wrap, ) @@ -122,8 +122,9 @@ def add_md_link_path(path: str, lines: List[str]) -> List[str]: def update_md_api(): - funcs = parse_functions(os.path.join(ROOT, "lua", "conform", "init.lua")) - lines = ["\n"] + render_md_api(funcs, 3)[:-1] # trim last newline + types = parse_directory(os.path.join(ROOT, "lua")) + funcs = types.files["conform/init.lua"].functions + lines = ["\n"] + render_md_api2(funcs, types, 3)[:-1] # trim last newline replace_section( README, r"^<!-- API -->$", @@ -186,11 +187,14 @@ def gen_formatter_vimdoc() -> VimdocSection: def generate_vimdoc(): doc = Vimdoc("conform.txt", "conform") - funcs = parse_functions(os.path.join(ROOT, "lua", "conform", "init.lua")) + types = parse_directory(os.path.join(ROOT, "lua")) + funcs = types.files["conform/init.lua"].functions doc.sections.extend( [ gen_options_vimdoc(), - VimdocSection("API", "conform-api", render_vimdoc_api("conform", funcs)), + VimdocSection( + "API", "conform-api", render_vimdoc_api2("conform", funcs, types) + ), gen_formatter_vimdoc(), ] ) |