Auto generate docs

doc/luasnip.txt

@@ -251,11 +251,13 @@ The first parameter of `f` is the function. Its parameters are
       reuse functions, ie. ternary if based on text in an insertNode).
 
 The second parameter is a table of indices of jumpable nodes whose text is
-passed to the function. The table may be empty, in this case the function is
-evaluated once upon snippet-expansion. If the table only has a single node, it
-can be passed directly without wrapping it in a table.
+passed to the function.
+The table may be empty, in this case the function is evaluated once upon
+snippet-expansion.
+If the table only has a single node, it can be passed directly without wrapping
+it in a table.
 The indices can be specified either as relative to the functionNodes' parent
-using numbers or as absolute, using the `absolute_indexer`.
+using numbers or as absolute, using the `absolute_indexer` (#absolute_indexer).
 
 The function shall return a string, which will be inserted as-is, or a table
 of strings for multiline-string, here all lines following the first will be
@@ -398,33 +400,59 @@ parents' indent (duh).
 ================================================================================
 DYNAMICNODE                                                  *luasnip-dynamicnode*
 
-Very similar to functionNode: returns a snippetNode instead of just text,
-which makes them very powerful.
+Very similar to functionNode, but returns a snippetNode instead of just text,
+which makes them very powerful as parts of the snippet can be changed based on
+user-input.
 
-Parameters:
-1. position (just like all jumpable nodes)
-2. function: Similar to functionNodes' function, first and second parameters
-   are the `table of text` from nodes the dynamicNode depends on (also without
-   snippet-indent) and the `snippet` (immediate parent of the `dynamicNode`).
-   The third, unlike functionNode, is a user-defined table, `old_state`. This
-   table can contain anything, its main usage is to preserve information from
-   the previously generated snippetNode: If the dynamicNode depends on another
-   node it may be reconstructed, which means all user input to the dynamicNode
-   is lost. Using `old_state`, the user may store eg. insertNodes and then get
-   their text via `node:get_text()` or `node.old_text` upon reconstruction to
-   initialize the new nodes with (only an example, this specific usecase is
-   covered much better by `restoreNode`).
-   The `old_state` table must be stored inside the `snippetNode` returned by
-   the function.
-   All parameters following the third are user defined.
-3. Indices of nodes the dynamicNode depends on: if any of these trigger an
-   update, the dynamicNodes function will be executed and the result inserted at
-   the nodes place. Can be a single index or a table of indices.
-4. The fourth and following parameters are user defined, anything passed
-   here will also be passed to the function (arg 2) following its third
-   parameter (easy to reuse similar functions with small changes).
+The prototype for the dynamicNodes' constructor is
+`d(position, function, argnodes, user_args1, ..., user_argsn)`:
+1. `position`: just like all jumpable nodes, when this node will be jumped into.
+2. `function`: `fn(args, parent, old_state, user_args1, ..., user_argsn) -> snippetNode`
+   This function is called when the argnodes' text changes. It generates and
+   returns (wrapped inside a `snippetNode`) the nodes that should be inserted
+   at the dynamicNodes place.
+   `args`, `parent` and `user_args` are also explained in
+   functionNode (#functionnode)
+   * `args`: `table of text` (`{{"node1line1", "node1line2"}, {"node2line1"}}`)
+     from nodes the dynamicNode depends on.
+   * `parent`: the immediate parent of the `dynamicNode`).
+   * `old_state`: a user-defined table. This table may contain
+     anything, its intended usage is to preserve information from the previously
+     generated `snippetNode`: If the `dynamicNode` depends on other nodes it may
+     be reconstructed, which means all user input (text inserted in `insertNodes`,
+     changed choices) to the previous dynamicNode is lost.
+     The `old_state` table must be stored in `snippetNode` returned by
+     the function (`snippetNode.old_state`).
+     The second example below illustrates the usage of `old_state`.
+   * `user_args1, ..., user_argsn`: passed through from `dynamicNode`-constructor.
+3. `argnodes`: Indices of nodes the dynamicNode depends on: if any of these trigger an
+   update, the `dynamicNode`s' function will be executed and the result inserted at
+   the `dynamicNodes` place.
+   Can be a single index or a table of indices.
+4. `user_args1, ..., user_argsn`: Anything passed here will also be passed to
+   the function (easy to reuse similar functions with small changes) (This may
+   be removed, alternatively use partial functions to reuse functions).
+
+Examples:
 >
-    local function lines(args, snip, old_state, initial_text)
+    s("trig", {
+    	t"text: ", i(1), t{"", "copy: "},
+    	d(2, function(args)
+    			-- the returned snippetNode doesn't need a position; it's inserted
+    			-- "inside" the dynamicNode.
+    			return sn(nil, {
+    				-- jump-indices are local to each snippetNode, so restart at 1.
+    				i(1, args[1])
+    			})
+    		end,
+    	{1})
+    })
+<
+
+This `dynamicNode` inserts an `insertNode` which copies the text inside the
+first `insertNode`.
+>
+    local function lines(args, parent, old_state, initial_text)
     	local nodes = {}
     	if not old_state then old_state = {} end
     	-- count is nil for invalid input.
@@ -465,10 +493,12 @@ Parameters:
     })
 <
 
-This snippet would start out as "1\nSample Text" and, upon changing the 1 to
-eg. 3, it would change to "3\nSample Text\nSample Text\nSample Text". Text
+This snippet would start out as `"1\nSample Text"` and, upon changing the 1 to
+eg. 3, it would change to `"3\nSample Text\nSample Text\nSample Text"`. Text
 that was inserted into any of the dynamicNodes insertNodes is kept when
 changing to a bigger number.
+(`old_state` is no longer the best way to preserve user-input across multiple
+recreations: the shortly-explained `restoreNode` is much more user-friendly)
 
 ================================================================================
 RESTORENODE                                                  *luasnip-restorenode*