Document doc string formatter in def, defn, ...

[crocket]

https://janet-lang.org/docs/bindings.html and https://janet-lang.org/docs/functions.html don't explain how multiline doc strings are formatted by doc string formatter.

[bakpakin]

The docstring formatter is used only to print documentation by the doc function - otherwise, docstrings are stored as written. (defn) just prepends the argument list to the docstring.

[sogaiu]

At around the time of the last comment, I think the code for doc-format (which is what I think this issue was referring to) was like this. I think that basically did rewrapping if necessary.

I think it does more now though. IIUC, this PR and subsequent development made constructs from Markdown (e.g. lists and code blocks) mean something within docstrings.

Investigation so far suggests to me that the docstring is parsed into a stack of tuples / arrays (which represent "blocks", which can in some cases be nested) and these are then re-emitted in the form of a buffer, accounting for markup (bold, code, italic, underline), indentation, width, and color settings. There appears to be specific handling for ordered / unordered lists as well as code blocks (fenced and indented may be).

Update: The Formatting with Markdown section does describe some (most/all?) of the supported constructs.