API documentation

Documentation on modules installed on your system, including the standard library and third-party modules, is available in your terminal via the haredoc command.

Note

For full details on the usage of the haredoc command, see its manpage: man haredoc.

Writing documentation

To document a declaration in Hare (a function, type, constant, etc), simply write a comment directly above the declaration, like so:

// This is an example function.
export fn example() void = {
        // ...
};

Hare documentation uses a very simple markup format, with the following features:

Referencing other Hare symbols

To reference other Hare symbols, wrap them in two square brackets, like so:

// This is an example function.
//
// See also [[os::exit]]
export fn example() void = {
        // ...
};

You can reference entire modules with [[module::]], using a trailing namespace separator (::).

Bulleted lists

You may add a bulleted list by opening each line with “-”, ending with an empty line, like so:

// This is a list:
//
// - foo
// - bar
// - baz
//
// It has three items.
export fn example() void = {
        // ...
};

Code samples

You can add code samples to your documentation by prefixing each line with at least two whitespace characters, or at least one tab character:

// This is a code sample:
//
//   let x = 1337;
//   example(x);
//
// It is simply indented from the body of the comment.
export fn example() void = {
        // ...
};

README

You may include a file in your module directory named “README” to provide an introduction to your module, using the same markup format as documentation comments.