commit a28acf49eff5a844e03c20e6f6d5c41345094098
parent f193db1db6a935c7dc3b529d89bb06a4fe3ae5e7
Author: Drew DeVault <sir@cmpwn.com>
Date: Mon, 19 Apr 2021 17:48:37 -0400
all: move module docs into README files
Diffstat:
20 files changed, 58 insertions(+), 66 deletions(-)
diff --git a/crypto/math/README b/crypto/math/README
@@ -0,0 +1,2 @@
+crypto::math provides constant-time mathematical operations useful for
+cryptographic algorithms.
diff --git a/crypto/math/bits.ha b/crypto/math/bits.ha
@@ -1,6 +1,3 @@
-// crypto::math provides constant-time mathematical operations useful for
-// cryptographic algorithms.
-
// Rotates a 32-bit unsigned integer left by k bits. k may be negative to rotate
// right instead, or see [rotr32].
export fn rotl32(x: u32, k: int) u32 = {
diff --git a/format/elf/README b/format/elf/README
@@ -0,0 +1,2 @@
+An implementation of the ELF64 file format. Best accompanied with a reading of
+the ELF-64 Object Format (Version 1.5).
diff --git a/format/elf/types.ha b/format/elf/types.ha
@@ -1,6 +1,3 @@
-// An implementation of the ELF64 file format. Best accompanied with a reading
-// of the ELF-64 Object Format (Version 1.5).
-
// TODO:
// - Flesh out ELF32 structures
diff --git a/getopt/README b/getopt/README
@@ -0,0 +1,7 @@
+getopt provides an interface for parsing command line arguments and
+automatically generates a brief help message explaining the command usage. See
+[parse] for the main entry point.
+
+The help text is brief and should serve only as a reminder. It is recommended
+that your command line program be accompanied by a man page to provide detailed
+usage information.
diff --git a/getopt/getopts.ha b/getopt/getopts.ha
@@ -1,10 +1,3 @@
-// getopt provides an interface for parsing command line arguments and
-// automatically generates a brief help message explaining the command usage.
-// See [parse] for the main entry point.
-//
-// The help text is brief and should serve only as a reminder. It is recommended
-// that your command line program be accompanied by a man page to provide
-// detailed usage information.
use encoding::utf8;
use fmt;
use io;
diff --git a/hare/lex/README b/hare/lex/README
@@ -0,0 +1 @@
+hare::lex provides a lexer for Hare source code.
diff --git a/hare/lex/lex.ha b/hare/lex/lex.ha
@@ -1,4 +1,3 @@
-// hare::lex provides a lexer for Hare source code.
use ascii;
use bufio;
use encoding::utf8;
diff --git a/hash/adler32/README b/hash/adler32/README
@@ -0,0 +1 @@
+Implements the Adler-32 checksum algorithm. It is a non-cryptographic checksum.
diff --git a/hash/adler32/adler32.ha b/hash/adler32/adler32.ha
@@ -1,6 +1,3 @@
-// Implements the Adler-32 checksum algorithm. It is a non-cryptographic
-// checksum.
-
use endian;
use hash;
use io;
diff --git a/hash/fnv/README b/hash/fnv/README
@@ -0,0 +1,2 @@
+Implements the Fowler–Noll–Vo (FNV) hash function. This hash is recommended for
+hash map keys and similar applications. It is a non-cryptographic hash.
diff --git a/hash/fnv/fnv.ha b/hash/fnv/fnv.ha
@@ -1,5 +1,3 @@
-// Implements the Fowler–Noll–Vo (FNV) hash function. This hash is recommended
-// for hash map keys and similar applications. It is a non-cryptographic hash.
use endian;
use hash;
use io;
diff --git a/math/random/README b/math/random/README
@@ -0,0 +1,6 @@
+math::random provides a pseudorandom number generator, which yields a
+deterministic sequence of psuedo-random numbers based on a seed value.
+
+Beware! This module is NOT suitable for generating genuinely random data for
+cryptographic use. See [crypto::random] for cryptographically secure random
+number generation.
diff --git a/math/random/random.ha b/math/random/random.ha
@@ -1,10 +1,3 @@
-// math::random provides a pseudorandom number generator, which yields a
-// deterministic sequence of psuedo-random numbers based on a seed value.
-//
-// Beware! This module is NOT suitable for generating genuinely random data for
-// cryptographic use. See [crypto::random] for cryptographically secure random
-// number generation.
-
// State for a pseudorandom number generator.
export type random = u64;
diff --git a/scripts/gen-stdlib b/scripts/gen-stdlib
@@ -630,8 +630,7 @@ types() {
unicode() {
gen_srcs unicode \
- properties.ha \
- unicode.ha
+ properties.ha
gen_ssa unicode
}
diff --git a/stdlib.mk b/stdlib.mk
@@ -819,8 +819,7 @@ $(HARECACHE)/types/types.ssa: $(stdlib_types_srcs) $(stdlib_rt)
# unicode
stdlib_unicode_srcs= \
- $(STDLIB)/unicode/properties.ha \
- $(STDLIB)/unicode/unicode.ha
+ $(STDLIB)/unicode/properties.ha
$(HARECACHE)/unicode/unicode.ssa: $(stdlib_unicode_srcs) $(stdlib_rt)
@printf 'HAREC \t$@\n'
@@ -1704,8 +1703,7 @@ $(TESTCACHE)/types/types.ssa: $(testlib_types_srcs) $(testlib_rt)
# unicode
testlib_unicode_srcs= \
- $(STDLIB)/unicode/properties.ha \
- $(STDLIB)/unicode/unicode.ha
+ $(STDLIB)/unicode/properties.ha
$(TESTCACHE)/unicode/unicode.ssa: $(testlib_unicode_srcs) $(testlib_rt)
@printf 'HAREC \t$@\n'
diff --git a/unicode/README b/unicode/README
@@ -0,0 +1,30 @@
+This module provides Unicode support for Hare programs.
+
+Programs which deal with basic text manipulation are likely to be served
+sufficiently by the [encoding::utf8], [strings], [ascii], and so on. For
+example, the question of "is this character uppercase?" is often sufficiently
+answered with [ascii::isupper], and matters such as Unicode string equivalence
+are often fraught with error potential - for example, a vulnerability was once
+found in a web login form which used a Unicode equivalence comparison on
+usernames, allowing a malicious actor to register a username which was bytewise
+distinct but uniwise equal to a victim, and then use it to log into their
+account. This module also contains a copy of the Unicode Character Database,
+which is rather large, and linking to it will increase the size of your
+binaries.
+
+The purpose of this module is not to handle every day string manipulation, but
+instead to provide support code for software which is explicitly aware of
+internationalization concerns and seeking out functions which specifically
+address those concerns.
+
+This module makes little attempt to be useful without a broader understanding of
+Unicode. The module is close to a 1:1 implementation of the Unicode standard,
+and it is recommended that any reading of this module's API or source code is
+accompanied by a reading of the Unicode standard. The documentation for each
+type and function makes an effort to direct the reader to the appropriate part
+of the Unicode standard.
+
+See the [i18n] module for a high-level internationalization API.
+
+The present implementation of this module conforms to Unicode 13.0.0, which was
+released on March 11th, 2020.
diff --git a/unicode/unicode.ha b/unicode/unicode.ha
@@ -1,30 +0,0 @@
-// This module provides Unicode support for Hare programs.
-//
-// Programs which deal with basic text manipulation are likely to be served
-// sufficiently by the [encoding::utf8], [strings], [ascii], and so on. For
-// example, the question of "is this character uppercase?" is often sufficiently
-// answered with [ascii::isupper], and matters such as Unicode string
-// equivalence are often fraught with error potential - for example, a
-// vulnerability was once found in a web login form which used a Unicode
-// equivalence comparison on usernames, allowing a malicious actor to register a
-// username which was bytewise distinct but uniwise equal to a victim, and then
-// use it to log into their account. This module also contains a copy of the
-// Unicode Character Database, which is rather large, and linking to it will
-// increase the size of your binaries.
-//
-// The purpose of this module is not to handle every day string manipulation,
-// but instead to provide support code for software which is explicitly aware of
-// internationalization concerns and seeking out functions which specifically
-// address those concerns.
-//
-// This module makes little attempt to be useful without a broader understanding
-// of Unicode. The module is close to a 1:1 implementation of the Unicode
-// standard, and it is recommended that any reading of this module's API or
-// source code is accompanied by a reading of the Unicode standard. The
-// documentation for each type and function makes an effort to direct the reader
-// to the appropriate part of the Unicode standard.
-//
-// See the [i18n] module for a high-level internationalization API.
-//
-// The present implementation of this module conforms to Unicode 13.0.0, which
-// was released on March 11th, 2020.
diff --git a/uuid/README b/uuid/README
@@ -0,0 +1,4 @@
+The uuid module implements RFC 4122-compatible Univerally Unique IDentifiers.
+
+This module only generates UUID4, aka "truly random" UUIDs, due to privacy
+concerns.
diff --git a/uuid/uuid.ha b/uuid/uuid.ha
@@ -1,7 +1,3 @@
-// The uuid module implements RFC 4122-compatible Univerally Unique IDentifiers.
-//
-// This module only generates UUID4, aka "truly random" UUIDs, due to privacy
-// concerns.
use bytes;
use crypto::random;
use endian;
