.\" Generated by scdoc 1.11.4
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "haredoc" "5" "2026-06-01"
.PP
.SH NAME
.PP
haredoc - Hare documentation format
.PP
.SH DESCRIPTION
.PP
Hare documentation is written in a simple markup language.\& By default,
\fBharedoc\fR(1) will display the documentation literally, without any additional
formatting.\& Other tools may format Hare documentation into other formats.\&
.PP
Text may be written normally, broken into several lines to conform to the
80-column limit.\& To begin a new paragraph, insert an empty line.\&
.PP
References to other declarations and modules may be written in brackets, like
this: [[os::stdout]].\& References to modules should include a trailing :: in the
identifier: [[os::exec::]].\&
.PP
A bulleted list can be started by opening a line with "-", optionally preceded
by a space.\& Each line opened like this begins a new list item.\& To complete the
list, insert an empty line.\&
.PP
Code samples may be used by starting a line with a single tab, optionally
preceded by a space.\&
.PP
This markup language is extracted from Hare comments preceding exported symbols
in your source code, and from a file named "README" in your module directory, if
present.\&
.PP
.SH README
.PP
A file named "README" at the root directory of a Hare module is used as a
summary of the entire module.\& It should start with a brief one-line summary of
the module using the module'\&s name (the last item in its identifier), a colon, a
space, and a summary, as follows:
.PP
.nf
.RS 4
memio: memory-backed I/O functions
.fi
.RE
.PP
This may be followed by an empty line, then a long-form summary of the module
using the documentation format described abovce.\&
.PP
.SH EXAMPLE
.PP
.nf
.RS 4
// Foos the bars\&. See also [[foobar]]\&.
//
// If you instead want to bar the foos, use one of the functions in
// [[bar::foo::]]\&.
//
// - First, the bars are obtained\&.
// - They are then fooed\&.
// - Finally, the result is returned\&.
//
//      let x = example();
//      assert(x == 0);
export fn example() int = 0;
.fi
.RE
.PP
.SH NOTES
.PP
It'\&s expected that tools which parse documentation for the purpose of converting
it into another format will perform additional processing to decouple the
content from its original textual representation:
.PP
.PD 0
.IP \(bu 4
Line breaks within a paragraph or list item should be ignored.\&
.IP \(bu 4
Repeated whitespace outside of a code sample should be collapsed.\&
.IP \(bu 4
Multiple code samples separated by empty lines should be collapsed into one
code sample, so the empty lines are moved into the code sample itself.\&
.PD
.PP
\fBhare::parse::doc::\fR in the standard library handles all of this processing for
you.\&
.PP
Parsers are permitted (and encouraged) to error out on invalid input, such as a
malformed or unterminated [[reference]].\&
.PP
.SH SEE ALSO
.PP
\fBharedoc\fR(1)