hare

commit a3b3752e3e543bf5c76c7cc73b9733ec113ed8e1
parent 879bec9d5b01f33bcf01ffa93802c7967b5a451d
Author: Drew DeVault <sir@cmpwn.com>
Date:   Tue, 20 Apr 2021 10:48:05 -0400

hare:: improve docs

Diffstat:
M
hare/lex/README
 | 
6
+++++-
A
hare/parse/README
 | 
9
+++++++++
M
hare/parse/decl.ha
 | 
2
+-
M
hare/parse/ident.ha
 | 
5
+++--
M
hare/parse/parse.ha
 | 
4
++--
M
hare/parse/type.ha
 | 
2
+-
M
hare/parse/unit.ha
 | 
1
+

7 files changed, 22 insertions(+), 7 deletions(-)
diff --git a/hare/lex/README b/hare/lex/README
@@ -1 +1,5 @@
-hare::lex provides a lexer for Hare source code.
+hare::lex provides a lexer for Hare source code. A lexer takes an [[io::stream]]
+and returns a series of Hare [[token]]s. See the Hare specification for more
+details:
+
+https://harelang.org/specification
diff --git a/hare/parse/README b/hare/parse/README
@@ -0,0 +1,9 @@
+hare::parse provides a parser for Hare source code. The [[subunit]] function
+will parse a single Hare source file and return a [[hare::ast::subunit]]. Other
+functions provide parsers for various important Hare sub-terminals, such as
+[[expression]]s and [[imports]]. See the Hare specification for more details:
+
+https://harelang.org/specification
+
+Most of these functions require the caller to provide a Hare lexer, see
+[[hare::lex]] for details.
diff --git a/hare/parse/decl.ha b/hare/parse/decl.ha
@@ -140,7 +140,7 @@ fn decl_func(lexer: *lex::lexer) (ast::decl_func | error) = {
 	};
 };
 
-// Parses the declarations for a sub-unit
+// Parses the declarations for a sub-unit.
 export fn decls(lexer: *lex::lexer) ([]ast::decl | error) = {
 	let decls: []ast::decl = [];
 	for (true) {
diff --git a/hare/parse/ident.ha b/hare/parse/ident.ha
@@ -29,14 +29,15 @@ fn ident_trailing(lexer: *lex::lexer) ((ast::ident, bool) | error) = {
 	return (ident: ast::ident, false);
 };
 
-// Parses a single identifier, i.e. foo::bar::baz
+// Parses a single identifier, i.e. 'foo::bar::baz'.
 export fn ident(lexer: *lex::lexer) (ast::ident | error) = {
 	let ident = ident_trailing(lexer)?;
 	synassert(mkloc(lexer), !ident.1, "Unexpected trailing :: in ident")?;
 	return ident.0;
 };
 
-// Parses an identifier from a string.
+// A convenience function which parses an identifier from a string, so the
+// caller needn't provide a lexer instance.
 export fn identstr(in: str) (ast::ident | error) = {
 	const buf = bufio::fixed(strings::toutf8(in), io::mode::READ);
 	defer io::close(buf);
diff --git a/hare/parse/parse.ha b/hare/parse/parse.ha
@@ -4,10 +4,10 @@ use hare::lex;
 use io;
 use strio;
 
-// All possible error types
+// All possible error types.
 export type error = lex::error!;
 
-// Convert an error into a human-friendly string
+// Convert an error into a human-friendly string.
 export fn strerror(err: error) const str = lex::strerror(err: lex::error);
 
 fn syntaxerr(
diff --git a/hare/parse/type.ha b/hare/parse/type.ha
@@ -379,7 +379,7 @@ fn enum_type(lexer: *lex::lexer) (ast::_type | error) = {
 	};
 };
 
-// Parses a type
+// Parses a type, e.g. '[]int'.
 export fn _type(lexer: *lex::lexer) (ast::_type | error) = {
 	let flags: ast::type_flags = match (try(lexer, ltok::CONST)?) {
 		_: void => 0,
diff --git a/hare/parse/unit.ha b/hare/parse/unit.ha
@@ -1,6 +1,7 @@
 use hare::ast;
 use hare::lex;
 
+// Parses an entire subunit (i.e. one Hare source file).
 export fn subunit(lexer: *lex::lexer) (ast::subunit | error) = {
 	let i = imports(lexer)?;
 	let d = decls(lexer)?;