search

janet-lang / janet-lang.org

Website for janet
https://janet-lang.org
MIT License
90 stars 58 forks source link

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

Open crocket opened 4 years ago

crocket commented 4 years ago

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 commented 4 years ago

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 commented 6 months ago

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.