retrovim 0.0.3

package/nvim/plugins/mini.nvim/doc/mini-doc.txt

@@ -0,0 +1,434 @@
+*mini.doc* Generate Neovim help files
+
+MIT License Copyright (c) 2022 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                       *MiniDoc*
+Key design ideas:
+- Keep documentation next to code by writing EmmyLua-like annotation
+  comments. They will be parsed as is, so formatting should follow built-in
+  guide in |help-writing|. However, custom hooks are allowed at many
+  generation stages for more granular management of output help file.
+
+- Generation is done by processing a set of ordered files line by line.
+  Each line can either be considered as a part of documentation block (if
+  it matches certain configurable pattern) or not (considered to be an
+  "afterline" of documentation block). See |MiniDoc.generate()| for more
+  details.
+
+- Processing is done by using nested data structures (section, block, file,
+  doc) describing certain parts of help file. See |MiniDoc-data-structures|
+  for more details.
+
+- Project specific script can be written as plain Lua file with
+  configuratble path. See |MiniDoc.generate()| for more details.
+
+What it doesn't do:
+- It doesn't support markdown or other markup language inside annotations.
+- It doesn't use treesitter in favor of Lua string manipulation for basic
+  tasks (parsing annotations, formatting, auto-generating tags, etc.). This
+  is done to manage complexity and be dependency free.
+
+# Setup ~
+
+This module needs a setup with `require('mini.doc').setup({})` (replace
+`{}` with your `config` table). It will create global Lua table `MiniDoc`
+which you can use for scripting or manually (with `:lua MiniDoc.*`).
+
+See |MiniDoc.config| for available config settings.
+
+You can override runtime config settings locally to buffer inside
+`vim.b.minidoc_config` which should have same structure as `MiniDoc.config`.
+See |mini.nvim-buffer-local-config| for more details.
+
+To stop module from showing non-error feedback, set `config.silent = true`.
+
+# Tips ~
+
+- Some settings tips that might make writing annotation comments easier:
+    - Set up appropriate |'comments'| for `lua` file type to respect
+      EmmyLua-like's `---` comment leader. Value `:---,:--` seems to work.
+    - Set up appropriate |'formatoptions'| (see also |fo-table|). Consider
+      adding `j`, `n`, `q`, and `r` flags.
+    - Set up appropriate |'formatlistpat'| to help auto-formatting lists (if
+      `n` flag is added to |'formatoptions'|). One suggestion (not entirely
+      ideal) is a value `^\s*[0-9\-\+\*]\+[\.\)]*\s\+`. This reads as "at
+      least one special character (digit, `-`, `+`, `*`) possibly followed
+      by some punctuation (`.` or `)`) followed by at least one space is a
+      start of list item".
+- Probably one of the most reliable resources for what is considered to be
+  best practice when using this module is this whole plugin. Look at source
+  code for the reference.
+
+# Comparisons ~
+
+- [tjdevries/tree-sitter-lua](https://github.com/tjdevries/tree-sitter-lua):
+    - Its key design is to use treesitter grammar to parse both Lua code
+      and annotation comments. This makes it not easy to install,
+      customize, and support.
+    - It takes more care about automating output formatting (like auto
+      indentation and line width fit). This plugin leans more to manual
+      formatting with option to supply customized post-processing hooks.
+
+------------------------------------------------------------------------------
+                                                       *MiniDoc-data-structures*
+Data structures
+
+Data structures are basically arrays of other structures accompanied with
+some fields (keys with data values) and methods (keys with function
+values):
+- `Section structure` is an array of string lines describing one aspect
+  (determined by section id like `@param`, `@return`, `@text`) of an
+  annotation subject. All lines will be used directly in help file.
+- `Block structure` is an array of sections describing one annotation
+  subject like function, table, concept.
+- `File structure` is an array of blocks describing certain file on disk.
+  Basically, file is split into consecutive blocks: annotation lines go
+  inside block, non-annotation - inside `block_afterlines` element of info.
+- `Doc structure` is an array of files describing a final help file. Each
+  string line from section (when traversed in depth-first fashion) goes
+  directly into output file.
+
+All structures have these keys:
+- Fields:
+    - `info` - contains additional information about current structure.
+      For more details see next section.
+    - `parent` - table of parent structure (if exists).
+    - `parent_index` - index of this structure in its parent's array. Useful
+      for adding to parent another structure near current one.
+    - `type` - string with structure type (section, block, file, doc).
+- Methods (use them as `x:method(args)`):
+    - `insert(self, [index,] child)` - insert `child` to `self` at position
+      `index` (optional; if not supplied, child will be appended to end).
+      Basically, a `table.insert()`, but adds `parent` and `parent_index`
+      fields to `child` while properly updating `self`.
+    - `remove(self [,index])` - remove from `self` element at position
+      `index`. Basically, a `table.remove()`, but properly updates `self`.
+    - `has_descendant(self, predicate)` - whether there is a descendant
+      (structure or string) for which `predicate` returns `true`. In case of
+      success also returns the first such descendant as second value.
+    - `has_lines(self)` - whether structure has any lines (even empty ones)
+      to be put in output file. For section structures this is equivalent to
+      `#self`, but more useful for higher order structures.
+    - `clear_lines(self)` - remove all lines from structure. As a result,
+      this structure won't contribute to output help file.
+
+Description of `info` fields per structure type:
+- `Section`:
+    - `id` - captured section identifier. Can be empty string meaning no
+      identifier is captured.
+    - `line_begin` - line number inside file at which section begins (-1 if
+      not generated from file).
+    - `line_end` - line number inside file at which section ends (-1 if not
+      generated from file).
+- `Block`:
+    - `afterlines` - array of strings which were parsed from file after
+      this annotation block (up until the next block or end of file).
+      Useful for making automated decisions about what is being documented.
+    - `line_begin` - line number inside file at which block begins  (-1 if
+      not generated from file).
+    - `line_end` - line number inside file at which block ends  (-1 if not
+      generated from file).
+- `File`:
+    - `path` - absolute path to a file (`''` if not generated from file).
+- `Doc`:
+    - `input` - array of input file paths (as in |MiniDoc.generate()|).
+    - `output` - output path (as in |MiniDoc.generate()|).
+    - `config` - configuration used (as in |MiniDoc.generate()|).
+
+------------------------------------------------------------------------------
+                                                               *MiniDoc.setup()*
+                           `MiniDoc.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniDoc.config|.
+
+Usage ~
+>lua
+  require('mini.doc').setup() -- use default config
+  -- OR
+  require('mini.doc').setup({}) -- replace {} with your config table
+<
+------------------------------------------------------------------------------
+                                                                *MiniDoc.config*
+                                `MiniDoc.config`
+Defaults ~
+>lua
+  MiniDoc.config = {
+    -- Function which extracts part of line used to denote annotation.
+    -- For more information see 'Notes' in |MiniDoc.config|.
+    annotation_extractor = function(l) return string.find(l, '^%-%-%-(%S*) ?') end,
+
+    -- Identifier of block annotation lines until first captured identifier
+    default_section_id = '@text',
+
+    -- Hooks to be applied at certain stage of document life cycle. Should
+    -- modify its input in place (and not return new one).
+    hooks = {
+      -- Applied to block before anything else
+      block_pre = --<function: infers header sections (tag and/or signature)>,
+
+      -- Applied to section before anything else
+      section_pre = --<function: replaces current aliases>,
+
+      -- Applied if section has specified captured id
+      sections = {
+        ['@alias'] = --<function: registers alias in MiniDoc.current.aliases>,
+        ['@class'] = --<function>,
+        ['@diagnostic'] = --<function: ignores any section content>,
+        -- For most typical usage see |MiniDoc.afterlines_to_code|
+        ['@eval'] = --<function: evaluates lines; replaces with their return>,
+        ['@field'] = --<function>,
+        ['@overload'] = --<function>,
+        ['@param'] = --<function>,
+        ['@private'] = --<function: registers block for removal>,
+        ['@return'] = --<function>,
+        ['@seealso'] = --<function>,
+        ['@signature'] = --<function: formats signature of documented object>,
+        ['@tag'] = --<function: turns its line in proper tag lines>,
+        ['@text'] = --<function: purposefully does nothing>,
+        ['@toc'] = --<function: clears all section lines>,
+        ['@toc_entry'] = --<function: registers lines for table of contents>,
+        ['@type'] = --<function>,
+        ['@usage'] = --<function>,
+      },
+
+      -- Applied to section after all previous steps
+      section_post = --<function: currently does nothing>,
+
+      -- Applied to block after all previous steps
+      block_post = --<function: does many things>,
+
+      -- Applied to file after all previous steps
+      file = --<function: adds separator>,
+
+      -- Applied to doc after all previous steps
+      doc = --<function: adds modeline>,
+
+      -- Applied before output file is written. Takes lines array as argument.
+      write_pre = --<function: removes delimiters at the top>,
+
+      -- Applied after output help file is written. Takes doc as argument.
+      write_post = --<function: various convenience actions>,
+    },
+
+    -- Path (relative to current directory) to script which handles project
+    -- specific help file generation (like custom input files, hooks, etc.).
+    script_path = 'scripts/minidoc.lua',
+
+    -- Whether to disable showing non-error feedback
+    silent = false,
+  }
+<
+# Notes ~
+
+- `annotation_extractor` takes single string line as input. Output
+  describes what makes an input to be an annotation (if anything). It
+  should be similar to `string.find` with one capture group: start and end
+  of annotation indicator (whole part will be removed from help line) with
+  third value being string of section id (if input describes first line of
+  section; `nil` or empty string otherwise). Output should be `nil` if line
+  is not part of annotation.
+  Default value means that annotation line should:
+    - Start with `---` at first column.
+    - Any non-whitespace after `---` will be treated as new section id.
+    - Single whitespace at the start of main text will be ignored.
+- Hooks are expected to be functions. Their default values might do many
+  things which might change over time, so for more information please look
+  at source code. Some more information can be found in
+  |MiniDoc.default_hooks|.
+
+------------------------------------------------------------------------------
+                                                               *MiniDoc.current*
+                               `MiniDoc.current`
+Table with information about current state of auto-generation
+
+It is reset at the beginning and end of `MiniDoc.generate()`.
+
+At least these keys are supported:
+- {aliases} - table with keys being alias name and values - alias
+  description and single string (using `\n` to separate lines).
+- {eval_section} - input section of `@eval` section hook. Can be used for
+  information about current block, etc.
+- {toc} - array with table of contents entries. Each entry is a whole
+  `@toc_entry` section.
+
+------------------------------------------------------------------------------
+                                                         *MiniDoc.default_hooks*
+                            `MiniDoc.default_hooks`
+Default hooks
+
+This is default value of `MiniDoc.config.hooks`. Use it if only a little
+tweak is needed.
+
+Some more insight about their behavior:
+- Default inference of documented object metadata (tag and object signature
+  at the moment) is done in `block_pre`. Inference is based on string
+  pattern matching, so can lead to false results, although works in most
+  cases. It intentionally works only if first line after block has no
+  indentation and contains all necessary information to determine if
+  inference should happen.
+- Hooks for sections describing some "variable-like" object (`@class`,
+  `@field`, `@param`) automatically enclose first word in `{}`.
+- Hooks for sections which supposed to have "type-like" data (`@field`,
+  `@param`, `@return`, `@type`) automatically enclose FIRST FOUND type-like
+  word and its neighbor characters in `(<type>)` (expect false positives).
+  Algorithm is far from being 100% correct, but seems to work with present
+  allowed type annotation. For allowed types see
+  https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#types-and-type
+  or, better yet, look in source code of this module.
+- Automated creation of table of contents (TOC) is done in the following way:
+    - Put section with `@toc_entry` id in the annotation block. Section's
+      lines will be registered as TOC entry.
+    - Put `@toc` section where you want to insert rendered table of
+      contents. TOC entries will be inserted on the left, references for
+      their respective tag section (only first, if present) on the right.
+      Render is done in default `doc` hook (because it should be done after
+      processing all files).
+- The `write_post` hook executes some actions convenient for iterative
+  annotations writing:
+    - Generate `:helptags` for directory containing output file.
+    - Silently reload buffer containing output file (if such exists).
+    - Display notification message about result.
+
+------------------------------------------------------------------------------
+                                                            *MiniDoc.generate()*
+                `MiniDoc.generate`({input}, {output}, {config})
+Generate help file
+
+# Algorithm ~
+
+- Main parameters for help generation are an array of input file paths and
+  path to output help file.
+- Parse all inputs:
+  - For each file, lines are processed top to bottom in order to create an
+    array of documentation blocks. Each line is tested whether it is an
+    annotation by applying `MiniDoc.config.annotation_extractor`: if
+    anything is extracted, it is considered to be an annotation. Annotation
+    line goes to "current block" after removing extracted annotation
+    indicator, otherwise - to afterlines of "current block".
+  - Each block's annotation lines are processed top to bottom. If line had
+    captured section id, it is a first line of "current section" (first
+    block lines are allowed to not specify section id; by default it is
+    `@text`). All subsequent lines without captured section id go into
+    "current section".
+- Apply structure hooks (they should modify its input in place, which is
+  possible due to "table nature" of all inputs):
+    - Each block is processed by `MiniDoc.config.hooks.block_pre`. This is a
+      designated step for auto-generation of sections from described
+      annotation subject (like sections with id `@tag`, `@type`).
+    - Each section is processed by `MiniDoc.config.hooks.section_pre`.
+    - Each section is processed by corresponding
+      `MiniDoc.config.hooks.sections` function (table key equals to section
+      id). This is a step where most of formatting should happen (like
+      wrap first word of `@param` section with `{` and `}`, append empty
+      line to section, etc.).
+    - Each section is processed by `MiniDoc.config.hooks.section_post`.
+    - Each block is processed by `MiniDoc.config.hooks.block_post`. This is
+      a step for processing block after formatting is done (like add first
+      line with `----` delimiter).
+    - Each file is processed by `MiniDoc.config.hooks.file`. This is a step
+      for adding any file-related data (like add first line with `====`
+      delimiter).
+    - Doc is processed by `MiniDoc.config.hooks.doc`. This is a step for
+      adding any helpfile-related data (maybe like table of contents).
+- Collect all strings from sections in depth-first fashion (equivalent to
+  nested "for all files -> for all blocks -> for all sections -> for all
+  strings -> add string to output"). Strings can have `\n` character
+  indicating start of new line.
+- Modify collected strings with `MiniDoc.config.write_pre`. Takes strings
+  from previous step as input and should return array of strings.
+- Write modified strings to output file.
+- Execute `MiniDoc.config.write_post` hook. This is useful for showing some
+  feedback and making actions involving newly updated help file (like
+  generate tags, etc.).
+
+# Project specific script ~
+
+If all arguments have default `nil` values, first there is an attempt to
+source project specific script. This is basically a
+`luafile <MiniDoc.config.script_path>` with current Lua runtime while caching
+and restoring current `MiniDoc.config`. Its successful execution stops any
+further generation actions while error means proceeding generation as if no
+script was found.
+
+Typical script content might include definition of custom hooks, input and
+output files with eventual call to `require('mini.doc').generate()` (with
+or without arguments).
+
+Parameters ~
+{input} `(table|nil)` Array of file paths which will be processed in supplied
+  order. Default: all `.lua` files from current directory following by all
+  such files in these subdirectories: `lua/`, `after/`, `colors/`. Note:
+  any `init.lua` file is placed before other files from the same directory.
+{output} `(string|nil)` Path for output help file. Default:
+  `doc/<current-directory>.txt` (designed to be used for generating help
+  file for plugin).
+{config} `(table|nil)` Configuration overriding parts of |MiniDoc.config|.
+
+Return ~
+`(table)` Document structure which was generated and used for output
+  help file. In case `MiniDoc.config.script_path` was successfully used,
+  this is a return from the latest call of this function.
+
+------------------------------------------------------------------------------
+                                                  *MiniDoc.afterlines_to_code()*
+                     `MiniDoc.afterlines_to_code`({struct})
+Convert afterlines to code
+
+This function is designed to be used together with `@eval` section to
+automate documentation of certain values (notably default values of a
+table). It processes afterlines based on certain directives and makes
+output look like a Lua code block.
+
+Most common usage is by adding the following section in your annotation: >
+
+  ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
+<
+# Directives ~
+
+Directives are special comments that are processed using Lua string pattern
+capabilities (so beware of false positives). Each directive should be put
+on its separate line. Supported directives:
+- `--minidoc_afterlines_end` denotes a line at afterlines end. Only all
+  lines before it will be considered as afterlines. Useful if there is
+  extra code in afterlines which shouldn't be used.
+- `--minidoc_replace_start <replacement>` and `--minidoc_replace_end`
+  denote lines between them which should be replaced with `<replacement>`.
+  Useful for manually changing what should be placed in output like in case
+  of replacing function body with something else.
+
+Here is an example. Suppose having these afterlines: >lua
+
+  --minidoc_replace_start {
+  M.config = {
+    --minidoc_replace_end
+    param_one = 1,
+    --minidoc_replace_start param_fun = --<function>
+    param_fun = function(x)
+      return x + 1
+    end
+    --minidoc_replace_end
+  }
+  --minidoc_afterlines_end
+
+  return M
+<
+After adding `@eval` section those will be formatted as: >
+
+  {
+    param_one = 1,
+    param_fun = --<function>
+  }
+<
+Parameters ~
+{struct} `(table)` Block or section structure which after lines will be
+  converted to code.
+
+Return ~
+`(string|nil)` Single string (using `\n` to separate lines) describing
+  afterlines as Lua code block in help file. If `nil`, input is not valid.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: