Render examples.

core/compress/gzip/doc.odin

@@ -1,17 +1,6 @@
-// A small `GZIP` unpacker.
-package compress_gzip
 /*
-	Copyright 2021 Jeroen van Rijn <[email protected]>.
-	Made available under Odin's BSD-3 license.
-
-	List of contributors:
-		Jeroen van Rijn: Initial implementation.
-		Ginger Bill:     Cosmetic changes.
-
-	A small GZIP implementation as an example.
-*/
+A small `GZIP` unpacker.
 
-/*
 Example:
 	import "core:bytes"
 	import "core:os"
@@ -88,4 +77,16 @@ Example:
 		}
 		bytes.buffer_destroy(&buf)
 	}
+*/
+package compress_gzip
+
+/*
+	Copyright 2021 Jeroen van Rijn <[email protected]>.
+	Made available under Odin's BSD-3 license.
+
+	List of contributors:
+		Jeroen van Rijn: Initial implementation.
+		Ginger Bill:     Cosmetic changes.
+
+	A small GZIP implementation as an example.
 */

core/compress/zlib/doc.odin

@@ -1,16 +1,6 @@
-// `Deflate` decompression of raw and `ZLIB`-type streams.
-package compress_zlib
 /*
-	Copyright 2021 Jeroen van Rijn <[email protected]>.
-	Made available under Odin's BSD-3 license.
-
-	List of contributors:
-		Jeroen van Rijn: Initial implementation.
+`Deflate` decompression of raw and `ZLIB`-type streams.
 
-	An example of how to use `zlib.inflate`.
-*/
-
-/*
 Example:
 	package main
 
@@ -49,4 +39,15 @@ Example:
 		fmt.printf("Input: %v bytes, output (%v bytes):\n%v\n", len(ODIN_DEMO), len(s), s)
 		assert(len(s) == OUTPUT_SIZE)
 	}
+*/
+package compress_zlib
+
+/*
+	Copyright 2021 Jeroen van Rijn <[email protected]>.
+	Made available under Odin's BSD-3 license.
+
+	List of contributors:
+		Jeroen van Rijn: Initial implementation.
+
+	An example of how to use `zlib.inflate`.
 */

core/container/bit_array/doc.odin

@@ -1,10 +1,9 @@
-// A dynamically-sized array of bits.
-package container_dynamic_bit_array
-
 /*
+A dynamically-sized array of bits.
+
 The Bit Array can be used in several ways:
 
-By default you don't need to instantiate a Bit Array.
+By default you don't need to instantiate a `Bit_Array`.
 Example:
 	package test
 
@@ -21,11 +20,11 @@ Example:
 
 		// returns `false`, `false`, because this Bit Array wasn't created to allow negative indices.
 		was_set, was_retrieved := get(&bits, -1)
-		fmt.println(was_set, was_retrieved) 
+		fmt.println(was_set, was_retrieved)
 		destroy(&bits)
 	}
 
-A Bit Array can optionally allow for negative indices, if the minimum value was given during creation.
+A `Bit_Array` can optionally allow for negative indices, if the minimum value was given during creation.
 Example:
 	package test
 
@@ -51,4 +50,5 @@ Example:
 		fmt.printf("Get(Negative_Test): %v, %v\n", get(bits, Foo.Negative_Test))
 		fmt.printf("Freed.\n")
 	}
-*/
+*/
+package container_dynamic_bit_array

core/container/intrusive/list/doc.odin

@@ -1,10 +1,7 @@
-// An intrusive doubly-linked list.
-package container_intrusive_list
-
 /*
-Package list implements an intrusive doubly-linked list.
+An intrusive doubly-linked list.
 
-An intrusive container requires a `Node` to be embedded in your own structure, like this.
+The intrusive container requires a `Node` to be embedded in your own structure, like this.
 Example:
 	My_String :: struct {
 		node:  list.Node,
@@ -48,4 +45,5 @@ Example:
 Output:
 	Hello
 	World
-*/
+*/
+package container_intrusive_list

core/container/small_array/doc.odin

@@ -1,8 +1,7 @@
-// A dynamic array-like interface on a stack-allocated, fixed-size array.
-package container_small_array
-
 /*
-The Small_Array type is optimal for scenarios where you need
+A dynamic array-like interface on a stack-allocated, fixed-size array.
+
+The `Small_Array` type is optimal for scenarios where you need
 a container for a fixed number of elements of a specific type,
 with the total number known at compile time but the exact
 number to be used determined at runtime.
@@ -33,7 +32,7 @@ Example:
 		return
 	}
 
-	// the Small_Array can be an ordinary parameter 'generic' over
+	// the `Small_Array` can be an ordinary parameter 'generic' over
 	// the actual length to be usable with different sizes
 	print_elements :: proc(arr: ^small_array.Small_Array($N, rune)) {
 		for r in small_array.slice(arr) {
@@ -51,4 +50,5 @@ Output:
 
 	Hellope
 
-*/
+*/
+package container_small_array

core/debug/pe/doc.odin

@@ -1,2 +0,0 @@
-// A reader for the Windows `PE` executable format for debug purposes.
-package debug_pe

core/debug/pe/pe.odin

@@ -1,3 +1,4 @@
+// A reader for the Windows `PE` executable format for debug purposes.
 package debug_pe
 
 PE_SIGNATURE_OFFSET_INDEX_POS :: 0x3c

core/debug/trace/doc.odin

@@ -1,6 +1,6 @@
-// Stack trace library. Only works when debug symbols are enabled using `-debug`.
-package debug_trace
 /*
+Stack trace library. Only works when debug symbols are enabled using `-debug`.
+
 Example:
 	import "base:runtime"
 	import "core:debug/trace"
@@ -47,4 +47,5 @@ Example:
 		...
 	}
 
-*/
+*/
+package debug_trace

core/dynlib/example/example.odin

@@ -44,4 +44,4 @@ main :: proc() {
 		fmt.println("84 - 13 =", sym.sub(84, 13))
 		fmt.println("hellope =", sym.hellope^)
 	}
-}
+}

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

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',

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!"
 	}
-*/
+*/
+package encoding_cbor

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/

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

core/encoding/varint/leb128.odin

@@ -1,3 +1,5 @@
+package encoding_varint
+
 /*
 	Copyright 2022 Jeroen van Rijn <[email protected]>.
 	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`.

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?

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 <[email protected]>.
 	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"

core/hash/xxhash/streaming.odin

@@ -1,3 +1,5 @@
+package xxhash
+
 /*
 	An implementation of Yann Collet's [xxhash Fast Hash Algorithm](https://cyan4973.github.io/xxHash/).
 	Copyright 2021 Jeroen van Rijn <[email protected]>.
@@ -8,8 +10,6 @@
 		Jeroen van Rijn: Initial implementation.
 */
 
-package xxhash
-
 import "core:mem"
 import "base:intrinsics"
 

core/hash/xxhash/xxhash_3.odin

@@ -1,3 +1,5 @@
+package xxhash
+
 /*
 	An implementation of Yann Collet's [xxhash Fast Hash Algorithm](https://cyan4973.github.io/xxHash/).
 	Copyright 2021 Jeroen van Rijn <[email protected]>.
@@ -8,8 +10,6 @@
 		Jeroen van Rijn: Initial implementation.
 */
 
-package xxhash
-
 import "base:intrinsics"
 
 /*

core/hash/xxhash/xxhash_32.odin

@@ -1,3 +1,5 @@
+package xxhash
+
 /*
 	An implementation of Yann Collet's [xxhash Fast Hash Algorithm](https://cyan4973.github.io/xxHash/).
 	Copyright 2021 Jeroen van Rijn <[email protected]>.
@@ -8,8 +10,6 @@
 		Jeroen van Rijn: Initial implementation.
 */
 
-package xxhash
-
 import "base:intrinsics"
 
 /*

core/hash/xxhash/xxhash_64.odin

@@ -1,3 +1,5 @@
+package xxhash
+
 /*
 	An implementation of Yann Collet's [xxhash Fast Hash Algorithm](https://cyan4973.github.io/xxHash/).
 	Copyright 2021 Jeroen van Rijn <[email protected]>.
@@ -8,8 +10,6 @@
 		Jeroen van Rijn: Initial implementation.
 */
 
-package xxhash
-
 import "base:intrinsics"
 
 /*

core/image/png/helpers.odin

@@ -1,3 +1,5 @@
+package png
+
 /*
 	Copyright 2021 Jeroen van Rijn <[email protected]>.
 	Made available under Odin's BSD-2 license.
@@ -9,8 +11,6 @@
 	These are a few useful utility functions to work with PNG images.
 */
 
-package png
-
 import "core:image"
 import "core:compress/zlib"
 import coretime "core:time"

core/image/png/png.odin

@@ -1,3 +1,6 @@
+#+vet !using-stmt
+package png
+
 /*
 	Copyright 2021 Jeroen van Rijn <[email protected]>.
 	Made available under Odin's BSD-3 license.
@@ -7,10 +10,6 @@
 		Ginger Bill:     Cosmetic changes.
 */
 
-
-#+vet !using-stmt
-package png
-
 import "core:compress"
 import "core:compress/zlib"
 import "core:image"

core/prof/spall/doc.odin

@@ -1,6 +1,8 @@
 /*
 Profiling using the "`spall`" format.
 
+See: [[ https://gravitymoth.com/spall/ ]]
+
 Example:
 	package main
 

core/sys/info/doc.odin

@@ -23,9 +23,6 @@ Example:
 		fmt.printfln("CPU cores: %vc/%vt", si.cpu.physical_cores, si.cpu.logical_cores)
 		fmt.printfln("RAM:       %#.1M",   si.ram.total_ram)
 
-		// fmt.printfln("Features: %v",      si.cpu.features)
-		// fmt.printfln("MacOS version: %v", si.macos_version)
-
 		fmt.println()
 		for gpu, i in si.gpus {
 			fmt.printfln("GPU #%v:", i)
@@ -37,26 +34,30 @@ Example:
 
 - Example Windows output:
 
-	Odin:  dev-2022-09
-	OS:    Windows 10 Professional (version: 20H2), build: 19042.1466
-	OS:    OS_Version{
+	Odin:      dev-2025-10
+	OS:        Windows 10 Professional (version: 22H2), build: 19045.6396
+	OS:        OS_Version{
 		platform = "Windows",
-		major = 10,
-		minor = 0,
-		patch = 0,
+		_ = Version{
+			major = 10,
+			minor = 0,
+			patch = 0,
+		},
 		build = [
-			19042,
-			1466,
+			19045,
+			6396,
 		],
-		version = "20H2",
-		as_string = "Windows 10 Professional (version: 20H2), build: 19042.1466",
+		version = "22H2",
+		as_string = "Windows 10 Professional (version: 22H2), build: 19045.6396",
 	}
-	CPU:   AMD Ryzen 7 1800X Eight-Core Processor
-	RAM:   64.0 GiB
+	CPU:       AMD Ryzen 9 5950X 16-Core Processor
+	CPU cores: 16c/32t
+	RAM:       63.9 GiB
+
 	GPU #0:
 		Vendor: Advanced Micro Devices, Inc.
-		Model:  Radeon RX Vega
-		VRAM:   8.0 GiB
+		Model:  AMD Radeon RX 9070
+		VRAM:   15.9 GiB
 
 - Example macOS output:
 

core/sys/info/platform_windows.odin

@@ -285,25 +285,26 @@ init_gpu_info :: proc "contextless" () {
 	context = runtime.default_context()
 
 	gpu_list: [dynamic]GPU
-	gpu_index: int
 
-	for {
+	// TODO: Use registry APIs to iterate over entries instead of trying 0000..0009.
+	for gpu_index in 0..<10 {
 		key := fmt.tprintf("%v\\%04d", GPU_INFO_BASE, gpu_index)
 
+		gpu: ^GPU
 		if vendor, ok := read_reg_string(sys.HKEY_LOCAL_MACHINE, key, "ProviderName"); ok {
 			append(&gpu_list, GPU{vendor_name = vendor})
+			gpu = &gpu_list[len(gpu_list) - 1]
 		} else {
-			break
+			continue
 		}
 
 		if desc, ok := read_reg_string(sys.HKEY_LOCAL_MACHINE, key, "DriverDesc"); ok {
-			gpu_list[gpu_index].model_name = desc
+			gpu.model_name = desc
 		}
 
 		if vram, ok := read_reg_i64(sys.HKEY_LOCAL_MACHINE, key, "HardwareInformation.qwMemorySize"); ok {
-			gpu_list[gpu_index].total_ram = int(vram)
+			gpu.total_ram = int(vram)
 		}
-		gpu_index += 1
 	}
 	gpus = gpu_list[:]
 }

core/sys/orca/macros.odin

@@ -1,7 +1,7 @@
-// Implementations of the `Orca` API that are defined as macros in Orca.
-
 package orca
 
+// Implementations of the `Orca` API that are defined as macros in Orca.
+
 ////////////////////////////////////////////////////////////////////////////////
 // Helpers for logging, asserting and aborting.
 ////////////////////////////////////////////////////////////////////////////////

core/sys/orca/odin.odin

@@ -1,7 +1,7 @@
-// File contains Odin specific helpers.
-
 package orca
 
+// File contains Odin specific helpers.
+
 import "base:runtime"
 
 create_odin_logger :: proc(lowest := runtime.Logger_Level.Debug, ident := "") -> runtime.Logger {

core/sys/orca/orca.odin

@@ -1,3 +1,6 @@
+// Bindings for the Orca platform
+//
+// See: [[ https://orca-app.dev ]]
 package orca
 
 import "core:c"