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>

4 files changed, 34 insertions, 26 deletions

diff --git a/README.md b/README.md
index 66912cb..356dea9 100644
--- a/README.md
+++ b/README.md
@@ -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(),
         ]
     )