Auto generate docs

doc/luasnip.txt

@@ -1,4 +1,4 @@
-*luasnip.txt*            For NVIM v0.8.0            Last change: 2023 March 13
+*luasnip.txt*            For NVIM v0.8.0            Last change: 2023 March 30
 
 ==============================================================================
 Table of Contents                                  *luasnip-table-of-contents*
@@ -36,6 +36,7 @@ Table of Contents                                  *luasnip-table-of-contents*
   - Filetype-Functions                     |luasnip-extras-filetype-functions|
   - Postfix-Snippet                           |luasnip-extras-postfix-snippet|
   - Snippet List                                 |luasnip-extras-snippet-list|
+  - Snippet Location                         |luasnip-extras-snippet-location|
 16. Extend Decorator                                |luasnip-extend-decorator|
 17. LSP-Snippets                                        |luasnip-lsp-snippets|
   - Snipmate Parser                     |luasnip-lsp-snippets-snipmate-parser|
@@ -56,8 +57,9 @@ Table of Contents                                  *luasnip-table-of-contents*
 24. Events                                                    |luasnip-events|
 25. Cleanup                                                  |luasnip-cleanup|
 26. Logging                                                  |luasnip-logging|
-27. Config-Options                                    |luasnip-config-options|
-28. API                                                          |luasnip-api|
+27. Source                                                    |luasnip-source|
+28. Config-Options                                    |luasnip-config-options|
+29. API                                                          |luasnip-api|
 >
                 __                       ____
                /\ \                     /\  _`\           __
@@ -1674,6 +1676,26 @@ Let’s recreate the custom display example above:
 <
 
 
+SNIPPET LOCATION                             *luasnip-extras-snippet-location*
+
+This module can consume a snippets |luasnip-source|, more specifically, jump to
+the location referred by it. This is primarily implemented for snippet which
+got their source from one of the loaders, but might also work for snippets
+where the source was set manually.
+
+`require("luasnip.extras.snip_location")`: *
+`snip_location.jump_to_snippet(snip, opts)` Jump to the definition of `snip`. *
+`snip`: a snippet with attached source-data. * `opts`: `nil|table`, optional
+arguments, valid keys are: * `hl_duration_ms`: `number`, duration for which the
+definition should be highlighted, in milliseconds. 0 disables the highlight. *
+`edit_fn`: `function(file)`, this function will be called with the file the
+snippet is located in, and is responsible for jumping to it. We assume that
+after it has returned, the current buffer contains `file`. *
+`snip_location.jump_to_active_snippet(opts)` Jump to definition of active
+snippet. * `opts`: `nil|table`, accepts the same keys as the `opts`-parameter
+of `jump_to_snippet`.
+
+
 ==============================================================================
 16. Extend Decorator                                *luasnip-extend-decorator*
 
@@ -2762,7 +2784,43 @@ print a short message to the log.
 
 
 ==============================================================================
-27. Config-Options                                    *luasnip-config-options*
+27. Source                                                    *luasnip-source*
+
+It is possible to attach, to a snippet, information about its source. This can
+be done either by the various loaders (if it is enabled in `ls.setup`
+(|luasnip-config-options|, `loaders_store_source`)), or manually. The attached
+data can be used by |luasnip-extras-snippet-location| to jump to the definition
+of a snippet.
+
+It is also possible to get/set the source of a snippet via API:
+
+`ls.snippet_source`:
+
+
+- `get(snippet) -> source_data`:
+    Retrieve the source-data of `snippet`. `source_data` always contains the key
+    `file`, the file in which the snippet was defined, and may additionally
+    contain `line` or `line_end`, the first and last line of the definition.
+- `set(snippet, source)`:
+    Set the source of a snippet.
+    - `snippet`: a snippet which was added via `ls.add_snippets`.
+    - `source`: a `source`-object, obtained from either `from_debuginfo` or
+        `from_location`.
+- `from_location(file, opts) -> source`:
+    - `file`: `string`, The path to the file in which the snippet is defined.
+    - `opts`: `table|nil`, optional parameters for the source.
+        - `line`: `number`, the first line of the definition. 1-indexed.
+        - `line_end`: `number`, the final line of the definition. 1-indexed.
+- `from_debuginfo(debuginfo) -> source`:
+    Generates source from the table returned by `debug.getinfo` (from now on
+    referred to as `debuginfo`). `debuginfo` has to be of a frame of a function
+    which is backed by a file, and has to contain this information, ie. has to be
+    generated by `debug.get_info(*, "Sl")` (at least `"Sl"`, it may also contain
+    more info).
+
+
+==============================================================================
+28. Config-Options                                    *luasnip-config-options*
 
 These are the settings you can provide to `luasnip.setup()`:
 
@@ -2829,10 +2887,14 @@ These are the settings you can provide to `luasnip.setup()`:
     warnings, consider adding the undefined globals to the globals recognized by
     `lua-language-server` or add `---@diagnostic disable: undefined-global`
     somewhere in the affected files.
+- `loaders_store_source`, boolean, whether loaders should store the source of the
+    loaded snippets. Enabling this means that the definition of any snippet can be
+    jumped to via |luasnip-extras-snippet-location|, but also entails slightly
+    increased memory consumption (and load-time, but it’s not really noticeable).
 
 
 ==============================================================================
-28. API                                                          *luasnip-api*
+29. API                                                          *luasnip-api*
 
 `require("luasnip")`: