hare

commit a0454dd2c7bdd93ee38e7a750a503a1d27fca80a
parent 451e953eb40ea49a25ef48a2c30274a76c78420c
Author: Drew DeVault <sir@cmpwn.com>
Date:   Wed, 21 Apr 2021 11:52:12 -0400

encoding: doc improvements

Diffstat:
M
encoding/hex/hex.ha
 | 
3
++-
M
encoding/utf8/decode.ha
 | 
15
++++++---------
M
encoding/utf8/encode.ha
 | 
5
+++--

3 files changed, 11 insertions(+), 12 deletions(-)
diff --git a/encoding/hex/hex.ha b/encoding/hex/hex.ha
@@ -6,7 +6,8 @@ use strconv;
 use strings;
 use strio;
 
-// Error returned when attempting to decode an invalid hex string.
+// Returned when attempting to decode a string which contains invalid hex
+// characters.
 export type invalid = void!;
 
 // Encodes a byte slice as a hexadecimal string and writes it to a stream.
diff --git a/encoding/utf8/decode.ha b/encoding/utf8/decode.ha
@@ -2,7 +2,6 @@ use types;
 
 fn toutf8(in: str) []u8 = *(&in: *[]u8);
 
-// The state for the UTF-8 decoder.
 export type decoder = struct {
 	offs: size,
 	src: []u8,
@@ -14,16 +13,15 @@ export fn decode(src: (str | []u8)) decoder = match (src) {
 	b: []u8 => decoder { src = b, ...  },
 };
 
-// Indicates that more data is needed, i.e. that a partial UTF-8 sequence was
+// Returned when more data is needed, i.e. when an incomplete UTF-8 sequence is
 // encountered.
 export type more = void;
 
-// An error indicating that an invalid UTF-8 sequence was found.
+// Returned when an invalid UTF-8 sequence was found.
 export type invalid = void!;
 
-// Returns the next rune from a decoder. If the slice ends with a complete UTF-8
-// sequence, void is returned. If an incomplete sequence is encountered, more is
-// returned. And if an invalid sequence is encountered, invalid is returned.
+// Returns the next rune from a decoder. void is returned when there are no
+// remaining codepoints.
 export fn next(d: *decoder) (rune | void | more | invalid) = {
 	assert(d.offs <= len(d.src));
 	if (d.offs == len(d.src)) {
@@ -55,9 +53,8 @@ export fn next(d: *decoder) (rune | void | more | invalid) = {
 	return r: rune;
 };
 
-// Returns the previous rune from a decoder. If the slice starts with a complete UTF-8
-// sequence, void is returned. If an incomplete sequence is encountered, more is
-// returned. And if an invalid sequence is encountered, invalid is returned.
+// Returns the previous rune from a decoder. void is returned when there are no
+// previous codepoints.
 export fn prev(d: *decoder) (rune | void | more | invalid) = {
 	if (d.offs == 0) {
 		return;
diff --git a/encoding/utf8/encode.ha b/encoding/utf8/encode.ha
@@ -1,5 +1,6 @@
-// Encodes a rune as UTF-8 and returns the result as a slice. The result is
-// statically allocated; duplicate it if you aren't using it right away.
+// Encodes a rune as UTF-8 and returns the result as a slice. The return value
+// is statically allocated, and will not be consistent after subsequent calls to
+// encoderune.
 export fn encoderune(r: rune) []u8 = {
 	let ch = r: u32, n = 0z, first = 0u8;
 	if (ch < 0x80) {