Further overhaul of package line comments.

17 files changed, 15 insertions, 19 deletions

diff --git a/core/encoding/base32/base32.odin b/core/encoding/base32/base32.odin
index 6c3abf29c..d49d62f77 100644
--- a/core/encoding/base32/base32.odin
+++ b/core/encoding/base32/base32.odin
@@ -1,3 +1,4 @@
+// `Base32` encoding and decoding, as specified in `RFC 4648`.
 package encoding_base32
 
 // Base32 encoding/decoding implementation as specified in RFC 4648.
diff --git a/core/encoding/base32/doc.odin b/core/encoding/base32/doc.odin
deleted file mode 100644
index 34d12e657..000000000
--- a/core/encoding/base32/doc.odin
+++ /dev/null
@@ -1,2 +0,0 @@
-// package base32 implements Base32 encoding and decoding, as specified in RFC 4648.
-package encoding_base32
\ No newline at end of file
diff --git a/core/encoding/base64/base64.odin b/core/encoding/base64/base64.odin
index 1013a7d0b..1960b4b55 100644
--- a/core/encoding/base64/base64.odin
+++ b/core/encoding/base64/base64.odin
@@ -1,3 +1,4 @@
+// `Base64` encoding and decoding.
 package encoding_base64
 
 import "core:io"
diff --git a/core/encoding/base64/doc.odin b/core/encoding/base64/doc.odin
deleted file mode 100644
index 0eab8ae09..000000000
--- a/core/encoding/base64/doc.odin
+++ /dev/null
@@ -1,2 +0,0 @@
-// package base64 implements Base64 encoding and decoding.
-package encoding_base64
\ No newline at end of file
diff --git a/core/encoding/cbor/doc.odin b/core/encoding/cbor/doc.odin
index f0388daa9..4acc63139 100644
--- a/core/encoding/cbor/doc.odin
+++ b/core/encoding/cbor/doc.odin
@@ -1,4 +1,4 @@
-// package cbor implements encoding and decoding types from/into RCF 8949 compatible CBOR binary.
+// Encoding and decoding types from/into `RCF 8949` compatible `CBOR` binary.
 package encoding_cbor
 /*
 Package cbor encodes, decodes, marshals and unmarshals types from/into RCF 8949 compatible CBOR binary.
diff --git a/core/encoding/csv/doc.odin b/core/encoding/csv/doc.odin
index 7abe2be49..2b9fdd849 100644
--- a/core/encoding/csv/doc.odin
+++ b/core/encoding/csv/doc.odin
@@ -1,5 +1,5 @@
 /*
-package csv reads and writes comma-separated values (CSV) files.
+Reader and writer for comma-separated values (`CSV`) files, per `RFC 4180`.
 This package supports the format described in [[ RFC 4180; https://tools.ietf.org/html/rfc4180.html ]]
 
 Example:
diff --git a/core/encoding/endian/doc.odin b/core/encoding/endian/doc.odin
index 0c397b29f..7cc9da1b7 100644
--- a/core/encoding/endian/doc.odin
+++ b/core/encoding/endian/doc.odin
@@ -1,5 +1,5 @@
 /*
-    Package endian implements a simple translation between bytes and numbers with specific endian encodings.
+    A simple translation between bytes and numbers with specific endian encodings.
 
 Example:
 	buf: [100]u8
diff --git a/core/encoding/entity/entity.odin b/core/encoding/entity/entity.odin
index 45841d125..28ff58170 100644
--- a/core/encoding/entity/entity.odin
+++ b/core/encoding/entity/entity.odin
@@ -1,5 +1,5 @@
 /*
-	package entity implements a unicode `&entity;` encoder and decoder.
+	Encode and decode `rune`s to/from a Unicode `&entity;`.
 
 	This code has several procedures to map unicode runes to/from different textual encodings.
 	- SGML/XML/HTML entity
diff --git a/core/encoding/hex/hex.odin b/core/encoding/hex/hex.odin
index 9e0837450..318e52ace 100644
--- a/core/encoding/hex/hex.odin
+++ b/core/encoding/hex/hex.odin
@@ -1,4 +1,4 @@
-// package hex implements encoding and decoding of hex-encoded binary, e.g. `0x23` -> `#`.
+// Encoding and decoding of hex-encoded binary, e.g. `0x23` -> `#`.
 package encoding_hex
 
 import "core:io"
diff --git a/core/encoding/hxa/doc.odin b/core/encoding/hxa/doc.odin
index bfca89d3c..902428668 100644
--- a/core/encoding/hxa/doc.odin
+++ b/core/encoding/hxa/doc.odin
@@ -1,5 +1,5 @@
 /*
-package hxa implements Eskil Steenberg's HxA 3D asset interchange format.
+Eskil Steenberg's `HxA` 3D asset interchange format.
 
 HxA is a interchangeable graphics asset format.
 Designed by Eskil Steenberg. @quelsolaar / eskil 'at' obsession 'dot' se / www.quelsolaar.com
diff --git a/core/encoding/ini/ini.odin b/core/encoding/ini/ini.odin
index f58aaed4d..a119b0f2e 100644
--- a/core/encoding/ini/ini.odin
+++ b/core/encoding/ini/ini.odin
@@ -1,4 +1,4 @@
-// package ini implements a variant of the `.ini` file format with `key = value` entries in `[sections]`.
+// Reader and writer for a variant of the `.ini` file format with `key = value` entries in `[sections]`.
 package encoding_ini
 
 import "base:runtime"
diff --git a/core/encoding/json/doc.odin b/core/encoding/json/doc.odin
deleted file mode 100644
index 04c38d142..000000000
--- a/core/encoding/json/doc.odin
+++ /dev/null
@@ -1,2 +0,0 @@
-// package json implements encoding and decoding JSON in strict JSON, JSON5 and BitSquid variants.
-package encoding_json
\ No newline at end of file
diff --git a/core/encoding/json/types.odin b/core/encoding/json/types.odin
index 41eb21377..a5f9daa02 100644
--- a/core/encoding/json/types.odin
+++ b/core/encoding/json/types.odin
@@ -1,3 +1,4 @@
+// Encoding and decoding JSON in strict `JSON`, `JSON5` and `BitSquid` variants.
 package encoding_json
 
 import "core:strings"
diff --git a/core/encoding/uuid/doc.odin b/core/encoding/uuid/doc.odin
index 373740a8e..c2622c56b 100644
--- a/core/encoding/uuid/doc.odin
+++ b/core/encoding/uuid/doc.odin
@@ -1,5 +1,5 @@
 /*
-package uuid implements Universally Unique Identifiers according to RFC 4122, with additions from RFC 9562.
+Universally Unique Identifiers (`UUID`) according to `RFC 4122`, with additions from `RFC 9562`.
 
 The UUIDs are textually represented and read in the following string format:
 `00000000-0000-v000-V000-000000000000`
diff --git a/core/encoding/uuid/legacy/legacy.odin b/core/encoding/uuid/legacy/legacy.odin
index d5f3df617..fe5c88e23 100644
--- a/core/encoding/uuid/legacy/legacy.odin
+++ b/core/encoding/uuid/legacy/legacy.odin
@@ -1,7 +1,6 @@
 /*
-package uuid/legacy implements versions 3 and 5 of UUID generation, both of
-which are using hashing algorithms (MD5 and SHA1, respectively) that are known
-these days to no longer be secure.
+Versions 3 and 5 of `UUID` generation, both of which use legacy (`MD5` + `SHA1`) hashes.
+Those are known these days to no longer be secure.
 */
 package uuid_legacy
 
diff --git a/core/encoding/varint/doc.odin b/core/encoding/varint/doc.odin
index ccc9493cd..23a28f913 100644
--- a/core/encoding/varint/doc.odin
+++ b/core/encoding/varint/doc.odin
@@ -1,5 +1,5 @@
 /*
-package varint implements LEB128 variable integer encoding and decoding, as used by DWARF & DEX files.
+`LEB128` variable integer encoding and decoding, as used by `DWARF` & `DEX` files.
 
 Author of this Odin package: Jeroen van Rijn
 
diff --git a/core/encoding/xml/doc.odin b/core/encoding/xml/doc.odin
index 8746fae02..79d960847 100644
--- a/core/encoding/xml/doc.odin
+++ b/core/encoding/xml/doc.odin
@@ -1,5 +1,5 @@
 /*
-package xml implements a parser for a useful subset of the XML specification.
+A parser for a useful subset of the `XML` specification.
 
 A from-scratch XML implementation, loosely modelled on the [[ spec; https://www.w3.org/TR/2006/REC-xml11-20060816 ]].