commit 2bbeede9c1a3f6b17824e267aad9accabfd47ad6
parent 59e3dfbef782f8b8640a119bc2aecf64a645a72c
Author: Drew DeVault <sir@cmpwn.com>
Date: Mon, 19 Apr 2021 11:49:24 -0400
all: move docs.ha => README
Diffstat:
12 files changed, 43 insertions(+), 50 deletions(-)
diff --git a/errors/README b/errors/README
@@ -0,0 +1,6 @@
+The error module provides a number of error types which describe error
+conditions common to many types of code, as well as convenience functions for
+turning these errors into strings, and an error type which may be used to wrap
+some implementation-defined error data. If your program's error cases can be
+modelled by the errors offered in this module, you may use them to make your
+error types compatible with a wider range of support modules.
diff --git a/errors/docs.ha b/errors/docs.ha
@@ -1,6 +0,0 @@
-// The error module provides a number of error types which describe error
-// conditions common to many types of code, as well as convenience functions for
-// turning these errors into strings, and an error type which may be used to
-// wrap some implementation-defined error data. If your program's error cases
-// can be modelled by the errors offered in this module, you may use them to
-// make your error types compatible with a wider range of support modules.
diff --git a/format/html/README b/format/html/README
@@ -0,0 +1,2 @@
+This module provides an HTML parser. Or rather, it will provide one. Right now
+all it does is escape HTML strings for safe printing.
diff --git a/format/html/docs.ha b/format/html/docs.ha
@@ -1,2 +0,0 @@
-// This module provides an HTML parser. Or rather, it will provide one. Right
-// now all it does is escape HTML strings for safe printing.
diff --git a/format/xml/README b/format/xml/README
@@ -0,0 +1,14 @@
+encoding::xml provides a simple parser of the useful subset of the XML 1.0
+(Fifth Edition) specification as defined by the W3C. Features omitted are:
+
+- Support for user-defined entities
+- Support for UTF-16 inputs or a UTF-8 BOM
+- Any considerations for the "Namespaces in XML 1.0" specification
+
+Attempting to parse an input file which does not conform to the supported subset
+of XML will return a syntax error. The purpose of this module is to support most
+XML files found in the wild, without supporting the lesser-used features that
+lead to problems like "billion laughs" vulnerabilities. If a fully conformant
+XML parser is required for your application, you will need to use a third-party
+XML implementation. Such an implementation should be able to shadow the standard
+library version and present a compatible API.
diff --git a/format/xml/parser.ha b/format/xml/parser.ha
@@ -1,17 +1,7 @@
-// encoding::xml provides a simple parser of the useful subset of the XML 1.0
-// (Fifth Edition) specification as defined by the W3C. Features omitted are:
-//
-// - Support for user-defined entities
-// - Support for UTF-16 inputs or a UTF-8 BOM
-// - Any considerations for the "Namespaces in XML 1.0" specification
-//
-// Attempting to parse an input file which does not conform to the supported
-// subset of XML will return a syntax error. The purpose of this module is to
-// support most XML files found in the wild, without supporting the lesser-used
-// features that lead to problems like "billion laughs" vulnerabilities. If a
-// fully conformant XML parser is required for your application, you will need
-// to use a third-party XML implementation. Such an implementation should be
-// able to shadow the standard library version and present a compatible API.
+// Are you an intrepid programmer seeking to fork this module to create a more
+// sophisticated XML parser supporting a broader set of features? Good news: all
+// of the features you need to implement are annotated throughout with
+// "XXX: Deliberate ommission" comments.
use ascii;
use bufio;
use encoding::utf8;
@@ -20,11 +10,6 @@ use strconv;
use strings;
use strio;
-// Are you an intrepid programmer seeking to fork this module to create a more
-// sophisticated XML parser supporting a broader set of features? Good news: all
-// of the features you need to implement are annotated throughout with
-// "XXX: Deliberate ommission" comments.
-
// Returns an XML parser which reads from a stream. The caller must call
// [parser_free] when they are finished with it.
//
diff --git a/hare/README b/hare/README
@@ -0,0 +1,8 @@
+The hare namespace provides various modules which can be used to work with Hare
+code itself (how meta). The modules available are:
+
+- [hare::ast]: data structures representing Hare's Abstract Syntax Tree
+- [hare::lex]: a lexer for Hare programs
+- [hare::module]: module resolution and Hare cache management
+- [hare::parse]: a parser for Hare programs
+- [hare::unparse]: a Hare "unparser", converts [hare::ast] into source code
diff --git a/hare/doc.ha b/hare/doc.ha
@@ -1,8 +0,0 @@
-// The hare namespace provides various modules which can be used to work with
-// Hare code itself (how meta). The modules available are:
-//
-// - [hare::ast]: data structures representing Hare's Abstract Syntax Tree
-// - [hare::lex]: a lexer for Hare programs
-// - [hare::module]: module resolution and Hare cache management
-// - [hare::parse]: a parser for Hare programs
-// - [hare::unparse]: a Hare "unparser", converts [hare::ast] into source code
diff --git a/scripts/gen-stdlib b/scripts/gen-stdlib
@@ -246,7 +246,6 @@ endian() {
errors() {
gen_srcs errors \
common.ha \
- docs.ha \
opaque.ha \
string.ha \
rt.ha
@@ -269,8 +268,7 @@ format_elf() {
format_html() {
gen_srcs format::html \
- escape.ha \
- docs.ha
+ escape.ha
gen_ssa format::html encoding::utf8 io strings strio
}
diff --git a/slice/README b/slice/README
@@ -0,0 +1,6 @@
+The slice module provides some utility functions for working with slices. In
+order to work with a user-supplied slice of an arbitrary type, the slice must be
+cast to []void and the size of the member type passed alongside it. These
+functions provide support code for common operations such as indexing and
+appending, which are normally provided by language features, but which are not
+available for []void slices.
diff --git a/slice/docs.ha b/slice/docs.ha
@@ -1,6 +0,0 @@
-// The slice module provides some utility functions for working with slices. In
-// order to work with a user-supplied slice of an arbitrary type, the slice must
-// be cast to []void and the size of the member type passed alongside it. These
-// functions provide support code for common operations such as indexing and
-// appending, which are normally provided by language features, but which are
-// not available for []void slices.
diff --git a/stdlib.mk b/stdlib.mk
@@ -397,7 +397,6 @@ $(HARECACHE)/endian/endian.ssa: $(stdlib_endian_srcs) $(stdlib_rt)
# errors
stdlib_errors_srcs= \
$(STDLIB)/errors/common.ha \
- $(STDLIB)/errors/docs.ha \
$(STDLIB)/errors/opaque.ha \
$(STDLIB)/errors/string.ha \
$(STDLIB)/errors/rt.ha
@@ -432,8 +431,7 @@ $(HARECACHE)/format/elf/format_elf.ssa: $(stdlib_format_elf_srcs) $(stdlib_rt)
# format::html
stdlib_format_html_srcs= \
- $(STDLIB)/format/html/escape.ha \
- $(STDLIB)/format/html/docs.ha
+ $(STDLIB)/format/html/escape.ha
$(HARECACHE)/format/html/format_html.ssa: $(stdlib_format_html_srcs) $(stdlib_rt) $(stdlib_encoding_utf8) $(stdlib_io) $(stdlib_strings) $(stdlib_strio)
@printf 'HAREC \t$@\n'
@@ -1270,7 +1268,6 @@ $(TESTCACHE)/endian/endian.ssa: $(testlib_endian_srcs) $(testlib_rt)
# errors
testlib_errors_srcs= \
$(STDLIB)/errors/common.ha \
- $(STDLIB)/errors/docs.ha \
$(STDLIB)/errors/opaque.ha \
$(STDLIB)/errors/string.ha \
$(STDLIB)/errors/rt.ha
@@ -1305,8 +1302,7 @@ $(TESTCACHE)/format/elf/format_elf.ssa: $(testlib_format_elf_srcs) $(testlib_rt)
# format::html
testlib_format_html_srcs= \
- $(STDLIB)/format/html/escape.ha \
- $(STDLIB)/format/html/docs.ha
+ $(STDLIB)/format/html/escape.ha
$(TESTCACHE)/format/html/format_html.ssa: $(testlib_format_html_srcs) $(testlib_rt) $(testlib_encoding_utf8) $(testlib_io) $(testlib_strings) $(testlib_strio)
@printf 'HAREC \t$@\n'
