Documenting Code

Documenting Code

JsonPatcher comes with a tool to generate markdown documentation from code comments. It's currently most convenient to use in the VSCode Extension.

Doc comments are comments that begin with #|. The first line defines the symbol being documented, and the rest is markdown. The comments don't have to be placed at the corresponding symbols, although it is good practice whenever possible.

Module Docs

The definition of a module starts with the module keyword and then a name, optionally followed by a separate location.

#| module example
#| This is an example module.
#| Descriptions have **markdown** support.

#| module example2 at "location"
#| This module has a location.
#| This is required whenever the module location can't be expressed in the module name.

Value Docs

Values, which are usually functions, belong to a module or type. Their definitions consist of the value keyword, their owner, their name and their type.

#| value example.func: (s: string) -> number
#| This values is a function, taking a single string and returning a number.

Type Docs

Custom types can also be defined in doc comments. They generally don't correlate to any actual symbols, and exist purely to make docs cleaner and more expressive.

Their definitions consist of the value keyword, their name and their type.

#| type MyType: object
#| A type, which is some object

#| value MyType.myMethod: () -> null
#| A method on a type

Types in Docs

Value and type docs have a type assigned to them. This type is defined using a syntax exclusive to doc comments, which is described here.

Special Types

Special types are specific keywords mapping to the basic type system of the language:

• any: Any value of any type is allowed
• number
• string
• boolean
• array: An array containing items of any type, equivalent to [any]
• object: An object containing unknown properties. Usually used as a base for custom types.
• function: Any function, without knowledge about its arguments
• null
• unknown: An unknown type. This shouldn't be written in docs.

Functions

Function types look like arrow functions. Function types consist of a list of arguments and a return type. Arguments consist of their name, followed by their type. Arguments can also be marked optional with ? and varargs with *.

# Examples:
(a: string, b: number) -> boolean
(a*: boolean) -> boolean
(a?: number) -> string
# Function types can be nested
(fun: (a: any) -> any) -> (a: any) -> any

Objects and Arrays with Contents

Objects and arrays can in addition to their special types be specified with content types. For arrays the type is simply the contained element type; for objects it's the type of values.

[string]
{number}
[[number]] # two dimensional array

Unions

Multiple types can be combined using unions. They consist of types separated by |.

string | number | null