Render examples.

8 files changed, 49 insertions, 48 deletions

diff --git a/core/encoding/base32/base32.odin b/core/encoding/base32/base32.odin
index d49d62f77..f50db12b3 100644
--- a/core/encoding/base32/base32.odin
+++ b/core/encoding/base32/base32.odin
@@ -1,22 +1,22 @@
-// `Base32` encoding and decoding, as specified in `RFC 4648`.
-package encoding_base32
+/*
+`Base32` encoding and decoding, as specified in `RFC 4648`.
+
+[[ RFC 4648; https://www.rfc-editor.org/rfc/rfc4648.html ]]
 
-// Base32 encoding/decoding implementation as specified in RFC 4648.
-// [[ More; https://www.rfc-editor.org/rfc/rfc4648.html ]]
+A secondary param can be used to supply a custom alphabet to `encode` and a matching decoding table to `decode`.
 
+If none is supplied it just uses the standard Base32 alphabet.
+In case your specific version does not use padding, you may
+truncate it from the encoded output.
 
-// @note(zh): Encoding utility for Base32
-// A secondary param can be used to supply a custom alphabet to
-// @link(encode) and a matching decoding table to @link(decode).
-// If none is supplied it just uses the standard Base32 alphabet.
-// In case your specific version does not use padding, you may
-// truncate it from the encoded output.
+Error represents errors that can occur during base32 decoding operations.
+As per RFC 4648:
+- Section 3.3: Invalid character handling
+- Section 3.2: Padding requirements
+- Section 6: Base32 encoding specifics (including block size requirements)
+*/
+package encoding_base32
 
-// Error represents errors that can occur during base32 decoding operations.
-// As per RFC 4648:
-// - Section 3.3: Invalid character handling
-// - Section 3.2: Padding requirements
-// - Section 6: Base32 encoding specifics (including block size requirements)
 Error :: enum {
 	None,
 	Invalid_Character, // Input contains characters outside the specified alphabet
diff --git a/core/encoding/base64/base64.odin b/core/encoding/base64/base64.odin
index 1960b4b55..2cd7227b5 100644
--- a/core/encoding/base64/base64.odin
+++ b/core/encoding/base64/base64.odin
@@ -1,17 +1,18 @@
-// `Base64` encoding and decoding.
+/*
+`Base64` encoding and decoding.
+
+A secondary param can be used to supply a custom alphabet to `encode` and a matching decoding table to `decode`.
+
+If none is supplied it just uses the standard Base64 alphabet.
+In case your specific version does not use padding, you may
+truncate it from the encoded output.
+*/
 package encoding_base64
 
 import "core:io"
 import "core:mem"
 import "core:strings"
 
-// @note(zh): Encoding utility for Base64
-// A secondary param can be used to supply a custom alphabet to
-// @link(encode) and a matching decoding table to @link(decode).
-// If none is supplied it just uses the standard Base64 alphabet.
-// Incase your specific version does not use padding, you may
-// truncate it from the encoded output.
-
 ENC_TABLE := [64]byte {
     'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H',
     'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P',
diff --git a/core/encoding/cbor/doc.odin b/core/encoding/cbor/doc.odin
index 4acc63139..4967a079a 100644
--- a/core/encoding/cbor/doc.odin
+++ b/core/encoding/cbor/doc.odin
@@ -1,7 +1,6 @@
-// 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.
+Encodes and decodes types from/into `RCF 8949` compatible `CBOR` binary.
+
 Also provided are conversion to and from JSON and the CBOR diagnostic format.
 
 **Allocations:**
@@ -166,4 +165,5 @@ Output:
 		"renamed :)": 123123.12500000,
 		"str": "Hello, World!"
 	}
-*/
\ No newline at end of file
+*/
+package encoding_cbor
\ No newline at end of file
diff --git a/core/encoding/json/types.odin b/core/encoding/json/types.odin
index a5f9daa02..75a66f646 100644
--- a/core/encoding/json/types.odin
+++ b/core/encoding/json/types.odin
@@ -1,15 +1,13 @@
-// Encoding and decoding JSON in strict `JSON`, `JSON5` and `BitSquid` variants.
-package encoding_json
-
-import "core:strings"
-
 /*
-	JSON 
+Encoding and decoding JSON in strict `JSON`, `JSON5` and `BitSquid` variants.
+
+Using one of these `Specification`s.
+	JSON
 		strict JSON
-	JSON5 
+	JSON5
 		pure superset of JSON and valid JavaScript
 		https://json5.org/
-		
+
 		* Object keys may be an ECMAScript 5.1 IdentifierName.
 		* Objects may have a single trailing comma.
 		* Arrays may have a single trailing comma.
@@ -22,17 +20,21 @@ import "core:strings"
 		* Numbers may begin with an explicit plus sign.
 		* Single and multi-line comments are allowed.
 		* Additional white space characters are allowed.
-		
+
 	MJSON
 		pure superset of JSON5, may not be valid JavaScript
 		https://bitsquid.blogspot.com/2009/10/simplified-json-notation.html
-		
+
 		* All the same features as JSON5 plus extras.
 		* Assume an object definition at the root level (no need to surround entire file with { } ).
 		* Commas are optional, using comma insertion rules with newlines.
 		* Quotes around object keys are optional if the keys are valid identifiers.
 		* : can be replaced with =
 */
+package encoding_json
+
+import "core:strings"
+
 Specification :: enum {
 	JSON,
 	JSON5, // https://json5.org/
diff --git a/core/encoding/varint/doc.odin b/core/encoding/varint/doc.odin
index 23a28f913..e17faec49 100644
--- a/core/encoding/varint/doc.odin
+++ b/core/encoding/varint/doc.odin
@@ -1,8 +1,6 @@
 /*
 `LEB128` variable integer encoding and decoding, as used by `DWARF` & `DEX` files.
 
-Author of this Odin package: Jeroen van Rijn
-
 Example:
 	package main
 
@@ -24,4 +22,4 @@ Example:
 		fmt.printf("Decoded as %v, using %v byte%v\n", decoded_val, decode_size, "" if decode_size == 1 else "s")
 	}
 */
-package encoding_varint
+package encoding_varint
\ No newline at end of file
diff --git a/core/encoding/varint/leb128.odin b/core/encoding/varint/leb128.odin
index 606c57ba7..876a1ba76 100644
--- a/core/encoding/varint/leb128.odin
+++ b/core/encoding/varint/leb128.odin
@@ -1,3 +1,5 @@
+package encoding_varint
+
 /*
 	Copyright 2022 Jeroen van Rijn <nom@duclavier.com>.
 	Made available under Odin's BSD-3 license.
@@ -6,8 +8,6 @@
 		Jeroen van Rijn: Initial implementation.
 */
 
-package encoding_varint
-
 // In theory we should use the bigint package. In practice, varints bigger than this indicate a corrupted file.
 // Instead we'll set limits on the values we'll encode/decode
 // 18 * 7 bits = 126, which means that a possible 19th byte may at most be `0b0000_0011`.
diff --git a/core/encoding/xml/doc.odin b/core/encoding/xml/doc.odin
index 79d960847..9030cd400 100644
--- a/core/encoding/xml/doc.odin
+++ b/core/encoding/xml/doc.odin
@@ -1,7 +1,7 @@
 /*
 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 ]].
+A from-scratch `XML` implementation, loosely modelled on the [[ spec; https://www.w3.org/TR/2006/REC-xml11-20060816 ]].
 
 Features:
 - Supports enough of the XML 1.0/1.1 spec to handle the 99.9% of XML documents in common current usage.
@@ -11,8 +11,8 @@ Caveats:
 - We do NOT support HTML in this package, as that may or may not be valid XML.
   If it works, great. If it doesn't, that's not considered a bug.
 
-- We do NOT support UTF-16. If you have a UTF-16 XML file, please convert it to UTF-8 first. Also, our condolences.
-- <[!ELEMENT and <[!ATTLIST are not supported, and will be either ignored or return an error depending on the parser options.
+- We do NOT support `UTF-16`. If you have a `UTF-16` XML file, please convert it to `UTF-8` first. Also, our condolences.
+- `<[!ELEMENT` and `<[!ATTLIST` are not supported, and will be either ignored or return an error depending on the parser options.
 
 MAYBE:
 - XML writer?
diff --git a/core/encoding/xml/xml_reader.odin b/core/encoding/xml/xml_reader.odin
index 707d2b3f3..621c9c2d0 100644
--- a/core/encoding/xml/xml_reader.odin
+++ b/core/encoding/xml/xml_reader.odin
@@ -1,4 +1,7 @@
+package encoding_xml
 /*
+	An XML 1.0 / 1.1 parser
+
 	2021-2022 Jeroen van Rijn <nom@duclavier.com>.
 	available under Odin's BSD-3 license.
 
@@ -6,9 +9,6 @@
 	- Jeroen van Rijn: Initial implementation.
 */
 
-package encoding_xml
-// An XML 1.0 / 1.1 parser
-
 import "core:bytes"
 import "core:encoding/entity"
 import "base:intrinsics"