Further overhaul of package line comments.

12 files changed, 16 insertions, 15 deletions

diff --git a/core/text/edit/text_edit.odin b/core/text/edit/text_edit.odin
index 49adad4d9..8713f6eff 100644
--- a/core/text/edit/text_edit.odin
+++ b/core/text/edit/text_edit.odin
@@ -1,4 +1,6 @@
 /*
+Text edit primitives to use in a text box.
+
 Based off the articles by rxi:
 - [[ https://rxi.github.io/textbox_behaviour.html ]]
 - [[ https://rxi.github.io/a_simple_undo_system.html ]]
diff --git a/core/text/i18n/doc.odin b/core/text/i18n/doc.odin
index d590fd123..f316c5a6d 100644
--- a/core/text/i18n/doc.odin
+++ b/core/text/i18n/doc.odin
@@ -1,6 +1,6 @@
 
 /*
-The `i18n` package is a flexible and easy to use way to localise applications.
+A flexible and easy way to add translations/internationalization (`i18n`) to applications.
 
 It has two calls to get a translation: `get()` and `get_n()`, which the user can alias into something like `T` and `Tn`
 with statements like:
diff --git a/core/text/match/strlib.odin b/core/text/match/strlib.odin
index 05f907bb6..c836253ec 100644
--- a/core/text/match/strlib.odin
+++ b/core/text/match/strlib.odin
@@ -1,3 +1,4 @@
+// A Lua-like string match algorithm.
 package text_match
 
 import "base:runtime"
diff --git a/core/text/regex/common/common.odin b/core/text/regex/common/common.odin
index e60bef58f..0abd48e4b 100644
--- a/core/text/regex/common/common.odin
+++ b/core/text/regex/common/common.odin
@@ -1,4 +1,4 @@
-// This package helps break dependency cycles.
+// This package helps break dependency cycles for the regular expression engine.
 package regex_common
 
 /*
diff --git a/core/text/regex/compiler/doc.odin b/core/text/regex/compiler/doc.odin
index 8c876d837..ec33ae8c9 100644
--- a/core/text/regex/compiler/doc.odin
+++ b/core/text/regex/compiler/doc.odin
@@ -1,6 +1,5 @@
 /*
-package regex_compiler implements a bytecode compiler for the virtual machine
-included alongside it.
+A bytecode compiler for the virtual machine included alongside it.
 
 Operands larger than u8 are written in system endian order.
 
diff --git a/core/text/regex/doc.odin b/core/text/regex/doc.odin
index 61ab8b80e..ba29659dc 100644
--- a/core/text/regex/doc.odin
+++ b/core/text/regex/doc.odin
@@ -1,6 +1,5 @@
 /*
-package regex implements a complete suite for using Regular Expressions to
-match and capture text.
+A complete suite for using Regular Expressions to match and capture text.
 
 Regular expressions are used to describe how a piece of text can match to
 another, using a pattern language.
diff --git a/core/text/regex/optimizer/doc.odin b/core/text/regex/optimizer/doc.odin
index 7f2c84c8d..279cbafba 100644
--- a/core/text/regex/optimizer/doc.odin
+++ b/core/text/regex/optimizer/doc.odin
@@ -1,6 +1,7 @@
 /*
-package regex_optimizer implements an optimizer which acts upon the AST of a
-parsed regular expression pattern, transforming it in-place without moving to a
+An optimizer for the regular expression AST.
+
+Acts upon the AST of a parsed regular expression pattern, transforming it in-place without moving to a
 compilation step.
 
 Where possible, it aims to reduce branching as much as possible in the
diff --git a/core/text/regex/parser/doc.odin b/core/text/regex/parser/doc.odin
index f518e518d..1f78a0b99 100644
--- a/core/text/regex/parser/doc.odin
+++ b/core/text/regex/parser/doc.odin
@@ -1,6 +1,5 @@
 /*
-package regex_parser implements a Pratt parser, also known as a Top-Down
-Operator Precedence parser, for parsing tokenized regular expression patterns.
+A `Pratt` parser (a.k.a. Top-Down Operator Precedence parser) for parsing tokenized regular expression patterns.
 
 References:
 - https://dl.acm.org/doi/10.1145/512927.512931
diff --git a/core/text/regex/tokenizer/tokenizer.odin b/core/text/regex/tokenizer/tokenizer.odin
index 447fe4329..556423a07 100644
--- a/core/text/regex/tokenizer/tokenizer.odin
+++ b/core/text/regex/tokenizer/tokenizer.odin
@@ -1,3 +1,4 @@
+// Tokenizes regular expressions.
 package regex_tokenizer
 
 /*
diff --git a/core/text/regex/virtual_machine/doc.odin b/core/text/regex/virtual_machine/doc.odin
index d599dbb1c..ba7441399 100644
--- a/core/text/regex/virtual_machine/doc.odin
+++ b/core/text/regex/virtual_machine/doc.odin
@@ -1,7 +1,6 @@
 /*
-package regex_vm implements a threaded virtual machine for interpreting
-regular expressions, based on the designs described by Russ Cox and attributed
-to both Ken Thompson and Rob Pike.
+A threaded virtual machine for interpreting regular expressions.
+Based on the designs described by Russ Cox and attributed to both Ken Thompson and Rob Pike.
 
 The virtual machine executes all threads in lock step, i.e. the string pointer
 does not advance until all threads have finished processing the current rune.
diff --git a/core/text/scanner/scanner.odin b/core/text/scanner/scanner.odin
index 96109f614..649b4d2d7 100644
--- a/core/text/scanner/scanner.odin
+++ b/core/text/scanner/scanner.odin
@@ -1,4 +1,4 @@
-// package text/scanner provides a scanner and tokenizer for UTF-8-encoded text.
+// A scanner and tokenizer for UTF-8-encoded text.
 // It takes a string providing the source, which then can be tokenized through
 // repeated calls to the scan procedure.
 // For compatibility with existing tooling and languages, the NUL character is not allowed.
diff --git a/core/text/table/doc.odin b/core/text/table/doc.odin
index 63275bbc1..4b8d76893 100644
--- a/core/text/table/doc.odin
+++ b/core/text/table/doc.odin
@@ -1,5 +1,5 @@
 /*
-The package `table` implements plain-text/markdown/HTML/custom rendering of tables.
+Plain-text/markdown/HTML/custom rendering of tables.
 
 **Custom rendering.**
 Example: