Some notes on features that might be nice to have for Janet docstrings. The existing docstrings exhibit a number of features but as there was no convention established early on nor any automation, existing docstrings vary a bit.
Below are some descriptions of features along with concrete examples from existing Janet docstrings.
exhibit a
exhibit b
Janet's docstrings "support some subset of Markdown"...but exactly what?
+ as a list item marker).doc-format was substantially changed by bakpakin
| # XXX: | |
| # | |
| # * spork/pm.janet's resolve-bundle has a docstring that looks like | |
| # it might eventually end up with a nested list. | |
| # | |
| # * could a nested list item end up looking like an ordinary "indented" | |
| # line? | |
| # assumes source has been formatted with doc-format such that there is | |
| # no indentation and no color (which implies list item markers have |
sort - buffer, array, tablesort-by - buffer, array, table (undocumented)reverse! - buffer, array, table (undocumented)take - tuple, string, table (undocumented), or arraytake-while - tuple, string, table (undocumented), or arrayloop and fiber/new use some odd indentation?
| # parse docstring's flavor of markdown | |
| # based on initial commit of mendoza by bakpakin | |
| (defn- combine-strings | |
| "Flatten consecutive strings in an indexed structure by concatenating | |
| them. The resulting document graph should be much cleaner. Also, empty | |
| strings will be removed entirely." | |
| [els] | |
| (def buf @"") |
| (defn int-product | |
| [x y] | |
| (defn helper | |
| [counter total] | |
| (if (zero? counter) | |
| total | |
| (helper (dec counter) (+ total y)))) | |
| # | |
| (helper x 0)) |
| (|[$0 $1] 1 0) | |
| # => | |
| [1 0] | |
| (|[$&] 1 0) | |
| # => | |
| [[1 0]] | |
| (|[$0 $1 $&] 1 0) | |
| # => |