(all) Update code annotations to be more precise.

Details:
- Add `|nil` for optional arguments and returns.
- Use `function|table` for callables.
- Use "namespaced" aliases.
- Resolves #215.

Co-authored-by: Turiiya <34311583+tobealive@users.noreply.github.com>

doc/mini-ai.txt

@@ -708,7 +708,7 @@ Parameters~
   <a> and <i> fields with captures for `a` and `i` textobjects respectively.
   Each value can be either a string capture (should start with `'@'`) or an
   array of such captures (best among all matches will be chosen).
-{opts} `(table)` Options. Possible values:
+{opts} `(table|nil)` Options. Possible values:
   - <use_nvim_treesitter> - whether to try to use 'nvim-treesitter' plugin
     (if present) to do the query. It implements more advanced behavior at
     cost of increased execution time. Provides more coherent experience if

doc/mini-align.txt

@@ -851,7 +851,7 @@ Parameters~
 {expr} `(string)` Lua expression as a string which will be used as predicate.
 
 Return~
-`(table)` A step named "filter" and with appropriate callable action.
+`(table|nil)` A step named "filter" and with appropriate callable action.
 
 ------------------------------------------------------------------------------
                                              *MiniAlign.gen_step.ignore_split()*
@@ -865,7 +865,7 @@ Parameters~
 {patterns} `(table)` Array of patterns to be added to
   `split_exclude_patterns` as is. Default: `{ [[".-"]] }` (excludes strings
   for most cases).
-{exclude_comment} `(boolean)` Whether to add comment pattern to
+{exclude_comment} `(boolean|nil)` Whether to add comment pattern to
   `split_exclude_patterns`. Comment pattern is derived from 'commentstring'
   option. Default: `true`.
 
@@ -900,9 +900,9 @@ Output calls `trim()` method of parts (see |MiniAlign.as_parts()|) with
 supplied `direction` and `indent` arguments.
 
 Parameters~
-{direction} `(string)` Which sides to trim whitespace. One of "both"
+{direction} `(string|nil)` Which sides to trim whitespace. One of "both"
   (default), "left", "right", "none".
-{indent} `(string)` What to do with possible indent (left whitespace of first
+{indent} `(string|nil)` What to do with possible indent (left whitespace of first
   string in a row). One of "keep" (default), "low", "high", "remove".
 
 Return~

doc/mini-animate.txt

@@ -489,11 +489,11 @@ Notes:
       immediately.
 
 Parameters~
-{step_action} `(function)` Callable which takes `step` (integer 0, 1, 2,
+{step_action} `(function|table)` Callable which takes `step` (integer 0, 1, 2,
   etc. indicating current step) and executes some action. Its return value
   defines when animation should stop: values `false` and `nil` (equivalent
   to no explicit return) stop animation timer; any other continues it.
-{step_timing} `(function)` Callable which takes `step` (integer 1, 2, etc.
+{step_timing} `(function|table)` Callable which takes `step` (integer 1, 2, etc.
   indicating next step) and returns how many milliseconds to wait before
   executing this step action.
 {opts} `(table|nil)` Options. Possible fields:
@@ -535,7 +535,7 @@ if you want to disable animation.
 Generate timing with linear progression
 
 Parameters~
-{opts} `(table)` Options that control progression. Possible keys:
+{opts} `(table|nil)` Options that control progression. Possible keys:
   - <easing> `(string)` - a subtype of progression. One of "in"
     (accelerating from zero speed), "out" (decelerating to zero speed),
     "in-out" (default; accelerating halfway, decelerating after).
@@ -553,7 +553,7 @@ Return~
 Generate timing with quadratic progression
 
 Parameters~
-{opts} `(table)` Options that control progression. Possible keys:
+{opts} `(table|nil)` Options that control progression. Possible keys:
   - <easing> `(string)` - a subtype of progression. One of "in"
     (accelerating from zero speed), "out" (decelerating to zero speed),
     "in-out" (default; accelerating halfway, decelerating after).
@@ -571,7 +571,7 @@ Return~
 Generate timing with cubic progression
 
 Parameters~
-{opts} `(table)` Options that control progression. Possible keys:
+{opts} `(table|nil)` Options that control progression. Possible keys:
   - <easing> `(string)` - a subtype of progression. One of "in"
     (accelerating from zero speed), "out" (decelerating to zero speed),
     "in-out" (default; accelerating halfway, decelerating after).
@@ -589,7 +589,7 @@ Return~
 Generate timing with quartic progression
 
 Parameters~
-{opts} `(table)` Options that control progression. Possible keys:
+{opts} `(table|nil)` Options that control progression. Possible keys:
   - <easing> `(string)` - a subtype of progression. One of "in"
     (accelerating from zero speed), "out" (decelerating to zero speed),
     "in-out" (default; accelerating halfway, decelerating after).
@@ -607,7 +607,7 @@ Return~
 Generate timing with exponential progression
 
 Parameters~
-{opts} `(table)` Options that control progression. Possible keys:
+{opts} `(table|nil)` Options that control progression. Possible keys:
   - <easing> `(string)` - a subtype of progression. One of "in"
     (accelerating from zero speed), "out" (decelerating to zero speed),
     "in-out" (default; accelerating halfway, decelerating after).
@@ -644,7 +644,7 @@ Example: >
 Generate path as shortest line
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `destination` as input and
     returns boolean value indicating whether animation should be done.
     Default: `false` if `destination` is within one line of origin (reduces
@@ -659,7 +659,7 @@ Return~
 Generate path as line/column angle
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `destination` as input and
     returns boolean value indicating whether animation should be done.
     Default: `false` if `destination` is within one line of origin (reduces
@@ -677,7 +677,7 @@ Return~
 Generate path as closing walls at final position
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `destination` as input and
     returns boolean value indicating whether animation should be done.
     Default: `false` if `destination` is within one line of origin (reduces
@@ -693,7 +693,7 @@ Return~
 Generate path as diminishing spiral at final position
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `destination` as input and
     returns boolean value indicating whether animation should be done.
     Default: `false` if `destination` is within one line of origin (reduces
@@ -728,7 +728,7 @@ Example: >
 Generate subscroll with equal steps
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `total_scroll` as
     input and returns boolean value indicating whether animation should be
     done. Default: `false` if `total_scroll` is 1 or less (reduces
@@ -768,7 +768,7 @@ Example: >
 Generate subresize with equal steps
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `sizes_from` and
     `sizes_to` as input and returns boolean value indicating whether
     animation should be done. Default: always `true`.
@@ -820,7 +820,7 @@ This will result into floating window statically covering whole target
 window.
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `win_id` as input and
     returns boolean value indicating whether animation should be done.
     Default: always `true`.
@@ -841,7 +841,7 @@ This will result into floating window growing from or shrinking to the
 target window center.
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `win_id` as input and
     returns boolean value indicating whether animation should be done.
     Default: always `true`.
@@ -864,7 +864,7 @@ vertically split window will progress towards vertical edge; horizontally -
 towards horizontal.
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <predicate> `(function)` - a callable which takes `win_id` as input and
     returns boolean value indicating whether animation should be done.
     Default: always `true`.
@@ -906,7 +906,7 @@ Example: >
 Generate linear `winblend` progression
 
 Parameters~
-{opts} `(table)` Options that control generator. Possible keys:
+{opts} `(table|nil)` Options that control generator. Possible keys:
   - <from> `(number)` - initial value of 'winblend'.
   - <to> `(number)` - final value of 'winblend'.
 

doc/mini-bufremove.txt

@@ -40,7 +40,7 @@ rules for disabling module's functionality is left to user. See
 Module setup
 
 Parameters~
-{config} `(table)` Module config table. See |MiniBufremove.config|.
+{config} `(table|nil)` Module config table. See |MiniBufremove.config|.
 
 Usage~
 `require('mini.bufremove').setup({})` (replace `{}` with your `config` table)
@@ -64,51 +64,51 @@ Default values:
 Delete buffer `buf_id` with |:bdelete| after unshowing it
 
 Parameters~
-{buf_id} `(number)` Buffer identifier (see |bufnr()|) to use. Default:
-  0 for current.
-{force} `(boolean)` Whether to ignore unsaved changes (using `!` version of
+{buf_id} `(number|nil)` Buffer identifier (see |bufnr()|) to use.
+  Default: 0 for current.
+{force} `(boolean|nil)` Whether to ignore unsaved changes (using `!` version of
   command). Default: `false`.
 
 Return~
-`(boolean)` Whether operation was successful.
+`(boolean|nil)` Whether operation was successful. If `nil`, no operation was done.
 
 ------------------------------------------------------------------------------
                                                        *MiniBufremove.wipeout()*
                    `MiniBufremove.wipeout`({buf_id}, {force})
 Wipeout buffer `buf_id` with |:bwipeout| after unshowing it
 
 Parameters~
-{buf_id} `(number)` Buffer identifier (see |bufnr()|) to use. Default:
-  0 for current.
-{force} `(boolean)` Whether to ignore unsaved changes (using `!` version of
+{buf_id} `(number|nil)` Buffer identifier (see |bufnr()|) to use.
+  Default: 0 for current.
+{force} `(boolean|nil)` Whether to ignore unsaved changes (using `!` version of
   command). Default: `false`.
 
 Return~
-`(boolean)` Whether operation was successful.
+`(boolean|nil)` Whether operation was successful. If `nil`, no operation was done.
 
 ------------------------------------------------------------------------------
                                                         *MiniBufremove.unshow()*
                         `MiniBufremove.unshow`({buf_id})
 Stop showing buffer `buf_id` in all windows
 
 Parameters~
-{buf_id} `(number)` Buffer identifier (see |bufnr()|) to use. Default:
-  0 for current.
+{buf_id} `(number|nil)` Buffer identifier (see |bufnr()|) to use.
+  Default: 0 for current.
 
 Return~
-`(boolean)` Whether operation was successful.
+`(boolean|nil)` Whether operation was successful. If `nil`, no operation was done.
 
 ------------------------------------------------------------------------------
                                               *MiniBufremove.unshow_in_window()*
                    `MiniBufremove.unshow_in_window`({win_id})
 Stop showing current buffer of window `win_id`
 
 Parameters~
-{win_id} `(number)` Window identifier (see |win_getid()|) to use.
+{win_id} `(number|nil)` Window identifier (see |win_getid()|) to use.
   Default: 0 for current.
 
 Return~
-`(boolean)` Whether operation was successful.
+`(boolean|nil)` Whether operation was successful. If `nil`, no operation was done.
 
 
  vim:tw=78:ts=8:noet:ft=help:norl:

doc/mini-comment.txt

@@ -43,7 +43,7 @@ for disabling module's functionality is left to user. See
 Module setup
 
 Parameters~
-{config} `(table)` Module config table. See |MiniComment.config|.
+{config} `(table|nil)` Module config table. See |MiniComment.config|.
 
 Usage~
 `require('mini.comment').setup({})` (replace `{}` with your `config` table)
@@ -92,7 +92,7 @@ dot-repeatability works): it should be called without arguments inside
 expression mapping and with argument when action should be performed.
 
 Parameters~
-{mode} `(string)` Optional string with 'operatorfunc' mode (see |g@|).
+{mode} `(string|nil)` Optional string with 'operatorfunc' mode (see |g@|).
 
 Return~
 `(string)` 'g@' if called without argument, '' otherwise (but after

doc/mini-completion.txt

@@ -140,7 +140,7 @@ rules for disabling module's functionality is left to user. See
 Module setup
 
 Parameters~
-{config} `(table)` Module config table. See |MiniCompletion.config|.
+{config} `(table|nil)` Module config table. See |MiniCompletion.config|.
 
 Usage~
 `require('mini.completion').setup({})` (replace `{}` with your `config` table)
@@ -215,8 +215,9 @@ is setup in |MiniCompletion.setup|.
 Run two-stage completion
 
 Parameters~
-{fallback} `(boolean)` Whether to use fallback completion.
-{force} `(boolean)` Whether to force update of completion popup.
+{fallback} `(boolean|nil)` Whether to use fallback completion. Default: `true`.
+{force} `(boolean|nil)` Whether to force update of completion popup.
+  Default: `true`.
 
 ------------------------------------------------------------------------------
                                             *MiniCompletion.complete_fallback()*
@@ -251,8 +252,8 @@ Designed to be used with |autocmd|. No need to use it directly, everything
 is setup in |MiniCompletion.setup|.
 
 Parameters~
-{actions} `(table)` Array containing any of 'completion', 'info', or
-  'signature' string.
+{actions} `(table|nil)` Array containing any of 'completion', 'info', or
+  'signature' string. Default: array containing all of them.
 
 ------------------------------------------------------------------------------
                                             *MiniCompletion.on_text_changed_i()*

doc/mini-cursorword.txt

@@ -71,7 +71,7 @@ Module-specific disabling:
 Module setup
 
 Parameters~
-{config} `(table)` Module config table. See |MiniCursorword.config|.
+{config} `(table|nil)` Module config table. See |MiniCursorword.config|.
 
 Usage~
 `require('mini.cursorword').setup({})` (replace `{}` with your `config` table)

doc/mini-doc.txt

@@ -145,7 +145,7 @@ Description of `info` fields per structure type:
 Module setup
 
 Parameters~
-{config} `(table)` Module config table. See |MiniDoc.config|.
+{config} `(table|nil)` Module config table. See |MiniDoc.config|.
 
 Usage~
 `require('mini.doc').setup({})` (replace `{}` with your `config` table)
@@ -351,14 +351,14 @@ output files with eventual call to `require('mini.doc').generate()` (with
 or without arguments).
 
 Parameters~
-{input} `(table)` Array of file paths which will be processed in supplied
+{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)` Path for output help file. Default:
+{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)` Configuration overriding parts of |MiniDoc.config|.
+{config} `(table|nil)` Configuration overriding parts of |MiniDoc.config|.
 
 Return~
 `(table)` Document structure which was generated and used for output
@@ -419,8 +419,8 @@ Parameters~
   converted to code.
 
 Return~
-`(string)` Single string (using `\n` to separate lines) describing
-  afterlines as code block in help file.
+`(string|nil)` Single string (using `\n` to separate lines) describing
+  afterlines as code block in help file. If `nil`, input is not valid.
 
 
  vim:tw=78:ts=8:noet:ft=help:norl:

doc/mini-fuzzy.txt

@@ -60,7 +60,7 @@ Given input `word` and target `candidate`:
 Module setup
 
 Parameters~
-{config} `(table)` Module config table. See |MiniFuzzy.config|.
+{config} `(table|nil)` Module config table. See |MiniFuzzy.config|.
 
 Usage~
 `require('mini.fuzzy').setup({})` (replace `{}` with your `config` table)
@@ -121,7 +121,7 @@ Return~
 Fuzzy matching for `lsp_completion.process_items` of |MiniCompletion.config|
 
 Parameters~
-{items} `(table)` Lua array with LSP 'textDocument/completion' response items.
+{items} `(table)` Array with LSP 'textDocument/completion' response items.
 {base} `(string)` Word to complete.
 
 ------------------------------------------------------------------------------
@@ -133,7 +133,7 @@ Designed to be used as value for |telescope.defaults.file_sorter| and
 |telescope.defaults.generic_sorter| inside `setup()` call.
 
 Parameters~
-{opts} `(table)` Options (currently not used).
+{opts} `(table|nil)` Options (currently not used).
 
 Usage~
 >