janet docstrings constructs notes

janet-docstring-constructs-notes.md

Background

This document describes features that Janet docstrings exhibit (along with a few that are not). As there was no explicit convention established early on nor any supporting automation, the docstrings vary a bit in the way the features have been applied to them.

Below are some descriptions of features along with concrete examples for existing Janet docstrings:

• top-level paragraphs
• code spans
• tight unordered lists
• pseudo-loose unordered lists

Other features have some support, but they may not actually be in use, used much, or be all that useful -- at least for janet and/or spork:

• indented code blocks (there are two janet docstrings that use this construct)
• fenced code blocks
• ordered lists
• emphasis and strong emphasis (e.g. italics or bold)

(It could be that other projects might benefit from some or all of the above features though.)

Nested lists don't currently work and although neither janet nor spork have any docstrings that might benefit (except may be one), support might be nice for other projects and possibly for janet and/or spork in the future.

Top-Level Paragraphs

Basic top-level paragraphs are currently supported.

Examples

• module/cache - single top-level paragraph

  A table, mapping loaded module identifiers to their environments.

• module/paths - multiple top-level paragraphs

  The list of paths to look for modules, templated for module/expand-path. Each element is a two-element tuple, containing the path template and a keyword :source, :native, or :image indicating how require should load files found at these paths.

  A tuple can also contain a third element, specifying a filter that prevents module/find from searching that path template if the filter doesn't match the input path. The filter can be a string or a predicate function, and is often a file extension, including the period.

In some cases, using more than one paragraph may make it easier to discern details, at least compared to using a single paragraph.

Consider the example above for module/paths. Below the same prose is in a single paragraph. Please compare it with the two-paragraph version above.

The list of paths to look for modules, templated for module/expand-path. Each element is a two-element tuple, containing the path template and a keyword :source, :native, or :image indicating how require should load files found at these paths. A tuple can also contain a third element, specifying a filter that prevents module/find from searching that path template if the filter doesn't match the input path. The filter can be a string or a predicate function, and is often a file extension, including the period.

When trying to comprehend details closely, it may be that breaking up content into more paragraphs may help. YMMV. In any case, having the option to do so seems preferrable to not.

Code Spans

When rendered as HTML, backtick strings (code spans) may show up distinguished from other content.

Example

• merge-into - see the instances of tab and colls in the prose below

  (merge-into tab & colls)

  Merges multiple tables/structs into table tab. If a key appears in more than one collection in colls, then later values replace any previous ones. Returns tab.

A benefit of using code spans is being able to tell at a glance whether a word or term refers to an argument (assuming an appropriate convention is followed with regard to use of backtick strings).

Some specific situations that might be helped via the use of code spans include:

• When reading docstring prose, not having to puzzle out whether a term expressed using a code span is an argument or technical term.

• When scanning a dosctring for information about specific arguments. If an argument is expressed using a code span, locating candidate information within the docstring may be more efficient.

Tight Unordered Lists

Tight lists (vs loose lists) are currently supported.

Example

• int/to-bytes - see the unordered list in the latter part of the prose below

  (int/to-bytes value &opt endianness buffer)

  Write the bytes of an int/s64 or int/u64 into a buffer. The buffer parameter specifies an existing buffer to write to, if unset a new buffer will be created. Returns the modified buffer. The endianness parameter indicates the byte order:

  • nil (unset): system byte order
  • :le: little-endian, least significant byte first
  • :be: big-endian, most significant byte first

Pseudo-Loose Unordered Lists

Loose lists might be nice in certain cases, but they are not directly supported. Currently, a "pseudo-loose" list effect can be achieved.

Example

• file/seek - the actual rendering in HTML is multiple single item lists

  (file/seek f &opt whence n)

  Jump to a relative location in the file f. whence must be one of:

  • :cur - jump relative to the current file location

  • :set - jump relative to the beginning of the file

  • :end - jump relative to the end of the file

  By default, whence is :cur. Optionally a value n may be passed for the relative number of bytes to seek in the file. n may be a real number to handle large files of more than 4GB. Returns the file handle.

Note that compared to the "tight list" example, there is more space between the list items. As the text for each list item gets longer, it may be that this "loose" effect may help with perception of content.