doc: add LSP annotations for `lsp_format` options (#461)

* doc: add LSP annotations for `lsp_format` options

* doc: regenerate documentation

---------

Co-authored-by: Steven Arcangeli <stevearc@stevearc.com>

3 files changed, 44 insertions, 27 deletions

diff --git a/README.md b/README.md
index 3c551b8..ad6a782 100644
--- a/README.md
+++ b/README.md
@@ -574,21 +574,26 @@ require("conform").formatters.my_formatter = {
 `format(opts, callback): boolean` \
 Format a buffer
 
-| Param    | Type                                                 | Desc                                                  |                                                                                                                                                                                                |
-| -------- | ---------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.                                                 |
-|          | 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_format                                           | `nil\|"never"\|"fallback"\|"prefer"\|"first"\|"last"` | "fallback" LSP formatting when no other formatters are available, "prefer" only LSP formatting when available, "first" LSP formatting then other formatters, "last" other formatters then LSP. |
-|          | 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 using LSP formatting                                                                                                                                         |
-|          | name                                                 | `nil\|string`                                         | Passed to vim.lsp.buf.format when using LSP formatting                                                                                                                                         |
-|          | filter                                               | `nil\|fun(client: table): boolean`                    | Passed to vim.lsp.buf.format when using LSP formatting                                                                                                                                         |
-| callback | `nil\|fun(err: nil\|string, did_edit: nil\|boolean)` | Called once formatting has completed                  |                                                                                                                                                                                                |
+| Param    | Type                                                 | Desc                                 |                                                                                                                                                      |
+| -------- | ---------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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.       |
+|          | 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_format                                           | `nil\|conform.LspFormatOpts`         | Configure if and when LSP should be used for formatting. Defaults to "never".                                                                        |
+|          |                                                      | > `"never"`                          | never use the LSP for formatting (default)                                                                                                           |
+|          |                                                      | > `"fallback"`                       | LSP formatting is used when no other formatters are available                                                                                        |
+|          |                                                      | > `"prefer"`                         | use only LSP formatting when available                                                                                                               |
+|          |                                                      | > `"first"`                          | LSP formatting is used when available and then other formatters                                                                                      |
+|          |                                                      | > `"last"`                           | other formatters are used then LSP formatting when 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 using LSP formatting                                                                                               |
+|          | name                                                 | `nil\|string`                        | Passed to vim.lsp.buf.format when using LSP formatting                                                                                               |
+|          | filter                                               | `nil\|fun(client: table): boolean`   | Passed to vim.lsp.buf.format when using LSP formatting                                                                                               |
+| callback | `nil\|fun(err: nil\|string, did_edit: nil\|boolean)` | Called once formatting has completed |                                                                                                                                                      |
 
 Returns:
 
diff --git a/doc/conform.txt b/doc/conform.txt
index a3d3c2e..4d2c0b6 100644
--- a/doc/conform.txt
+++ b/doc/conform.txt
@@ -119,12 +119,12 @@ setup({opts})                                                      *conform.setu
       {opts} `nil|conform.setupOpts`
           {formatters_by_ft} `nil|table<string, conform.FiletypeFormatter>` Map
                              of filetype to formatters
-          {format_on_save}   `nil|conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts` I
-                             f this is set, Conform will run the formatter on
+          {format_on_save}   `nil|conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts`
+                             If this is set, Conform will run the formatter on
                              save. It will pass the table to conform.format().
                              This can also be a function that returns the table.
-          {format_after_save} `nil|conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts` I
-                             f this is set, Conform will run the formatter
+          {format_after_save} `nil|conform.FormatOpts|fun(bufnr: integer): nil|conform.FormatOpts`
+                             If this is set, Conform will run the formatter
                              asynchronously after save. It will pass the table
                              to conform.format(). This can also be a function
                              that returns the table.
@@ -133,8 +133,8 @@ setup({opts})                                                      *conform.setu
                              the location of the log file.
           {notify_on_error}  `nil|boolean` Conform will notify you when a
                              formatter errors (default true).
-          {formatters}       `nil|table<string, conform.FormatterConfigOverride|fun(bufnr: integer): nil|conform.FormatterConfigOverride>` C
-                             ustom formatters and overrides for built-in
+          {formatters}       `nil|table<string, conform.FormatterConfigOverride|fun(bufnr: integer): nil|conform.FormatterConfigOverride>`
+                             Custom formatters and overrides for built-in
                              formatters.
 
 format({opts}, {callback}): boolean                               *conform.format*
@@ -152,11 +152,16 @@ format({opts}, {callback}): boolean                               *conform.forma
                        the buffer
           {formatters} `nil|string[]` List of formatters to run. Defaults to all
                        formatters for the buffer filetype.
-          {lsp_format} `nil|"never"|"fallback"|"prefer"|"first"|"last"` "fallbac
-                       k" LSP formatting when no other formatters are available,
-                       "prefer" only LSP formatting when available, "first" LSP
-                       formatting then other formatters, "last" other formatters
-                       then LSP.
+          {lsp_format} `nil|conform.LspFormatOpts` Configure if and when LSP
+                       should be used for formatting. Defaults to "never".
+              `"never"`    never use the LSP for formatting (default)
+              `"fallback"` LSP formatting is used when no other formatters are
+                         available
+              `"prefer"`   use only LSP formatting when available
+              `"first"`    LSP formatting is used when available and then other
+                         formatters
+              `"last"`     other formatters are used then LSP formatting when
+                         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`
diff --git a/lua/conform/init.lua b/lua/conform/init.lua
index 0bab347..aa97f1c 100644
--- a/lua/conform/init.lua
+++ b/lua/conform/init.lua
@@ -328,13 +328,20 @@ local function has_lsp_formatter(opts)
   return not vim.tbl_isempty(lsp_format.get_format_clients(opts))
 end
 
+---@alias conform.LspFormatOpts
+---| '"never"' # never use the LSP for formatting (default)
+---| '"fallback"' # LSP formatting is used when no other formatters are available
+---| '"prefer"' # use only LSP formatting when available
+---| '"first"' # LSP formatting is used when available and then other formatters
+---| '"last"' # other formatters are used then LSP formatting when available
+
 ---@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_format? "never"|"fallback"|"prefer"|"first"|"last" "fallback" LSP formatting when no other formatters are available, "prefer" only LSP formatting when available, "first" LSP formatting then other formatters, "last" other formatters then LSP.
+---@field lsp_format? conform.LspFormatOpts Configure if and when LSP should be used for formatting. Defaults to "never".
 ---@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 using LSP formatting