hare

commit 959470bd4a59ef2cb5674f1924dc8801f9887a38
parent aab34844ae8e365330ab7b682055a4e30d8112bf
Author: Sebastian <sebastian@sebsite.pw>
Date:   Sat,  9 Dec 2023 21:16:05 -0500

hare::parse::doc: add docs

Signed-off-by: Sebastian <sebastian@sebsite.pw>

Diffstat:
A
hare/parse/doc/README
 | 
2
++
M
hare/parse/doc/doc.ha
 | 
10
++++++++++

2 files changed, 12 insertions(+), 0 deletions(-)
diff --git a/hare/parse/doc/README b/hare/parse/doc/README
@@ -0,0 +1,2 @@
+hare::parse::doc parses haredoc markup into an abstract representation. The
+haredoc markup format is documented in haredoc(5).
diff --git a/hare/parse/doc/doc.ha b/hare/parse/doc/doc.ha
@@ -11,24 +11,34 @@ use memio;
 use strings;
 use types;
 
+// A representation of a complete haredoc document.
 export type doc = [](paragraph | list | code_sample);
 
+// A paragraph of text.
 export type paragraph = [](str | decl_ref | mod_ref);
 
+// A bulleted list.
 export type list = []paragraph;
 
+// A code sample.
 export type code_sample = str;
 
+// A reference to a declaration.
 export type decl_ref = ast::ident;
 
+// A reference to a module.
 export type mod_ref = ast::ident;
 
+// All possible error types.
 export type error = !lex::error;
 
 // Converts an error into a human-friendly string. The result may be statically
 // allocated.
 export fn strerror(err: error) const str = lex::strerror(err);
 
+// Parses a haredoc document from an [[io::handle]]. 'start' is the location of
+// the top-left corner of the document, for accurate locations in error messages
+// (e.g. declaration documentation starts at col=3; READMEs start at col=1).
 export fn parse(in: io::handle, start: lex::location) (doc | error) = {
 	let sc = bufio::newscanner(in, types::SIZE_MAX);
 	defer bufio::finish(&sc);