commit a3b3752e3e543bf5c76c7cc73b9733ec113ed8e1
parent 879bec9d5b01f33bcf01ffa93802c7967b5a451d
Author: Drew DeVault <sir@cmpwn.com>
Date: Tue, 20 Apr 2021 10:48:05 -0400
hare:: improve docs
Diffstat:
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)?;