Repository navigation
Expand file tree
/
Copy pathmini-doc.txt
More file actions
434 lines (373 loc) · 20.2 KB
/
Copy pathmini-doc.txt
File metadata and controls
434 lines (373 loc) · 20.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
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
8000
_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: