diff options
147 files changed, 155 insertions, 186 deletions
diff --git a/core/bufio/doc.odin b/core/bufio/doc.odin index f725e83dc..683f68f07 100644 --- a/core/bufio/doc.odin +++ b/core/bufio/doc.odin @@ -1,2 +1,2 @@ -// package bufio implements buffered I/O. It wraps an `io.Stream` interface to provide buffering. +// Wraps an `io.Stream` interface to provide buffered I/O. package bufio
\ No newline at end of file diff --git a/core/bytes/bytes.odin b/core/bytes/bytes.odin index d4a0804b5..79de89d2f 100644 --- a/core/bytes/bytes.odin +++ b/core/bytes/bytes.odin @@ -1,4 +1,4 @@ -// package bytes implements procedures for manipulation of byte slices. +// Procedures for manipulation of `[]byte` slices. package bytes import "base:intrinsics" diff --git a/core/c/c.odin b/core/c/c.odin index c609cefd1..8266bf38a 100644 --- a/core/c/c.odin +++ b/core/c/c.odin @@ -1,4 +1,4 @@ -// package c just defines the basic types used by C programs. +// Defines the basic types used by `C` programs for foreign function and data structure interop. package c import builtin "base:builtin" diff --git a/core/c/libc/doc.odin b/core/c/libc/doc.odin index 29fb40a30..856ee41c6 100644 --- a/core/c/libc/doc.odin +++ b/core/c/libc/doc.odin @@ -1,2 +1,2 @@ -// package libc declares the commonly used things in "libc" (C standard library). +// Declares the commonly used things in `libc` (`C` standard library). package libc diff --git a/core/compress/common.odin b/core/compress/common.odin index 917dcfba5..796a60071 100644 --- a/core/compress/common.odin +++ b/core/compress/common.odin @@ -1,4 +1,4 @@ -// package compress is a collection of utilities to aid with other compression packages. +// A collection of utilities to aid with other `compress`ion packages. package compress /* diff --git a/core/compress/gzip/doc.odin b/core/compress/gzip/doc.odin index c35f205e5..8a04c41bd 100644 --- a/core/compress/gzip/doc.odin +++ b/core/compress/gzip/doc.odin @@ -1,4 +1,4 @@ -// package gzip implements a small GZIP unpacker as an example. +// A small `GZIP` unpacker. package compress_gzip /* Copyright 2021 Jeroen van Rijn <nom@duclavier.com>. diff --git a/core/compress/shoco/doc.odin b/core/compress/shoco/doc.odin deleted file mode 100644 index 78ab01776..000000000 --- a/core/compress/shoco/doc.odin +++ /dev/null @@ -1,2 +0,0 @@ -// package shoco is an implementation of the shoco short string compressor. -package compress_shoco
\ No newline at end of file diff --git a/core/compress/shoco/shoco.odin b/core/compress/shoco/shoco.odin index d8810e532..be079df19 100644 --- a/core/compress/shoco/shoco.odin +++ b/core/compress/shoco/shoco.odin @@ -1,4 +1,4 @@ -// package shoco is an implementation of the shoco short string compressor. +// `Shoco` short string compression and decompression. package compress_shoco /* diff --git a/core/compress/zlib/doc.odin b/core/compress/zlib/doc.odin index f143073a3..9c3893e2f 100644 --- a/core/compress/zlib/doc.odin +++ b/core/compress/zlib/doc.odin @@ -1,4 +1,4 @@ -// package zlib implements Deflate decompression. +// `Deflate` decompression of raw and `ZLIB`-type streams. package compress_zlib /* Copyright 2021 Jeroen van Rijn <nom@duclavier.com>. diff --git a/core/container/avl/avl.odin b/core/container/avl/avl.odin index 8a9d1f3d9..6c7216c29 100644 --- a/core/container/avl/avl.odin +++ b/core/container/avl/avl.odin @@ -1,8 +1,4 @@ -/* -package avl implements an AVL tree. - -The implementation is non-intrusive, and non-recursive. -*/ +// A non-intrusive and non-recursive implementation of `AVL` trees. package container_avl @(require) import "base:intrinsics" diff --git a/core/container/bit_array/doc.odin b/core/container/bit_array/doc.odin index 3ff6f5765..aa27817e8 100644 --- a/core/container/bit_array/doc.odin +++ b/core/container/bit_array/doc.odin @@ -1,4 +1,4 @@ -// package bit_array implements a dynamically-sized array of bits. +// A dynamically-sized array of bits. package container_dynamic_bit_array /* diff --git a/core/container/intrusive/list/doc.odin b/core/container/intrusive/list/doc.odin index 78502e35d..b84e32bd9 100644 --- a/core/container/intrusive/list/doc.odin +++ b/core/container/intrusive/list/doc.odin @@ -1,4 +1,4 @@ -// package list implements an intrusive doubly-linked list. +// An intrusive doubly-linked list. package container_intrusive_list /* diff --git a/core/container/lru/doc.odin b/core/container/lru/doc.odin deleted file mode 100644 index 540487bc6..000000000 --- a/core/container/lru/doc.odin +++ /dev/null @@ -1,2 +0,0 @@ -// package lru implements an LRU cache. It automatically removes older entries if its capacity is reached. -package container_lru
\ No newline at end of file diff --git a/core/container/lru/lru_cache.odin b/core/container/lru/lru_cache.odin index d95e8e1d2..23d3e1eb9 100644 --- a/core/container/lru/lru_cache.odin +++ b/core/container/lru/lru_cache.odin @@ -1,3 +1,4 @@ +// A least-recently-used (`LRU`) cache. It automatically removes older entries if its capacity is reached. package container_lru import "base:runtime" diff --git a/core/container/priority_queue/doc.odin b/core/container/priority_queue/doc.odin deleted file mode 100644 index 7cba4af8d..000000000 --- a/core/container/priority_queue/doc.odin +++ /dev/null @@ -1,2 +0,0 @@ -// package priority_queue implements a Priority Queue data structure. -package container_priority_queue
\ No newline at end of file diff --git a/core/container/priority_queue/priority_queue.odin b/core/container/priority_queue/priority_queue.odin index c62a821f4..c9ef807c5 100644 --- a/core/container/priority_queue/priority_queue.odin +++ b/core/container/priority_queue/priority_queue.odin @@ -1,3 +1,4 @@ +// A priority queue data structure. package container_priority_queue import "base:builtin" diff --git a/core/container/queue/doc.odin b/core/container/queue/doc.odin deleted file mode 100644 index efb29fc2a..000000000 --- a/core/container/queue/doc.odin +++ /dev/null @@ -1,2 +0,0 @@ -// package queue implements a dynamically resizable double-ended queue/ring-buffer. -package container_queue
\ No newline at end of file diff --git a/core/container/queue/queue.odin b/core/container/queue/queue.odin index 8de8d55c0..37f3a923f 100644 --- a/core/container/queue/queue.odin +++ b/core/container/queue/queue.odin @@ -1,3 +1,4 @@ +// A dynamically resizable double-ended queue/ring-buffer. package container_queue import "base:builtin" diff --git a/core/container/rbtree/doc.odin b/core/container/rbtree/doc.odin deleted file mode 100644 index 3ff154d18..000000000 --- a/core/container/rbtree/doc.odin +++ /dev/null @@ -1,2 +0,0 @@ -// package rbtree implements a red-black tree. -package container_rbtree
\ No newline at end of file diff --git a/core/container/rbtree/rbtree.odin b/core/container/rbtree/rbtree.odin index 6a3b9c9ea..35ce21413 100644 --- a/core/container/rbtree/rbtree.odin +++ b/core/container/rbtree/rbtree.odin @@ -1,3 +1,4 @@ +// A red-black tree with the same API as our AVL tree. package container_rbtree @(require) import "base:intrinsics" diff --git a/core/container/small_array/doc.odin b/core/container/small_array/doc.odin index a57caf798..12ad6b134 100644 --- a/core/container/small_array/doc.odin +++ b/core/container/small_array/doc.odin @@ -1,4 +1,4 @@ -// package small_array implements a dynamic array-like interface on a stack-allocated, fixed-size array. +// A dynamic array-like interface on a stack-allocated, fixed-size array. package container_small_array /* diff --git a/core/container/topological_sort/doc.odin b/core/container/topological_sort/doc.odin deleted file mode 100644 index cd79e0e54..000000000 --- a/core/container/topological_sort/doc.odin +++ /dev/null @@ -1,2 +0,0 @@ -// package topological_sort implements a generic O(V+E) topological sorter. -package container_topological_sort
\ No newline at end of file diff --git a/core/container/topological_sort/topological_sort.odin b/core/container/topological_sort/topological_sort.odin index 6afe9c453..a49d04b49 100644 --- a/core/container/topological_sort/topological_sort.odin +++ b/core/container/topological_sort/topological_sort.odin @@ -1,11 +1,7 @@ +// A generic `O(V+E)` topological sorter implementation. This is the fastest known method for topological sorting. +// Odin's map type is being used to accelerate lookups. package container_topological_sort -/* - The following is a generic O(V+E) topological sorter implementation. - This is the fastest known method for topological sorting and Odin's - map type is being used to accelerate lookups. -*/ - import "base:intrinsics" import "base:runtime" _ :: intrinsics diff --git a/core/crypto/aead/doc.odin b/core/crypto/aead/doc.odin index 687b4deae..811dd564d 100644 --- a/core/crypto/aead/doc.odin +++ b/core/crypto/aead/doc.odin @@ -1,6 +1,5 @@ - /* -package aead implements a generic interface to Authenticated Encryption with Associated Data algorithms. +A generic interface to Authenticated Encryption with Associated Data (`AEAD`) algorithms. Both a one-shot and context based interface are provided, with similar usage. If multiple messages are to be sealed/opened via the same key, diff --git a/core/crypto/aegis/aegis.odin b/core/crypto/aegis/aegis.odin index c0d8bf4ee..41b7ad5be 100644 --- a/core/crypto/aegis/aegis.odin +++ b/core/crypto/aegis/aegis.odin @@ -1,5 +1,5 @@ /* -package aegis implements the AEGIS-128L and AEGIS-256 AEAD algorithms. +`AEGIS-128L` and `AEGIS-256` AEAD algorithms. Where AEAD stands for Authenticated Encryption with Additional Data. diff --git a/core/crypto/aes/aes.odin b/core/crypto/aes/aes.odin index 57f49acf4..661acd88f 100644 --- a/core/crypto/aes/aes.odin +++ b/core/crypto/aes/aes.odin @@ -1,5 +1,5 @@ /* -package aes implements the AES block cipher and some common modes. +The `AES` block cipher and some common modes. See: - [[ https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197-upd1.pdf ]] diff --git a/core/crypto/blake2b/blake2b.odin b/core/crypto/blake2b/blake2b.odin index 3b3fc6649..c2822cbaf 100644 --- a/core/crypto/blake2b/blake2b.odin +++ b/core/crypto/blake2b/blake2b.odin @@ -1,5 +1,5 @@ /* -package blake2b implements the BLAKE2b hash algorithm. +`BLAKE2b` hash algorithm. See: - [[ https://datatracker.ietf.org/doc/html/rfc7693 ]] diff --git a/core/crypto/blake2s/blake2s.odin b/core/crypto/blake2s/blake2s.odin index 9bbd44541..c2a07a6dc 100644 --- a/core/crypto/blake2s/blake2s.odin +++ b/core/crypto/blake2s/blake2s.odin @@ -1,5 +1,5 @@ /* -package blake2s implements the BLAKE2s hash algorithm. +`BLAKE2s` hash algorithm. See: - [[ https://datatracker.ietf.org/doc/html/rfc7693 ]] diff --git a/core/crypto/chacha20/chacha20.odin b/core/crypto/chacha20/chacha20.odin index e8d67eb3e..a91c6a24a 100644 --- a/core/crypto/chacha20/chacha20.odin +++ b/core/crypto/chacha20/chacha20.odin @@ -1,5 +1,5 @@ /* -package chacha20 implements the ChaCha20 and XChaCha20 stream ciphers. +`ChaCha20` and `XChaCha20` stream ciphers. See: - [[ https://datatracker.ietf.org/doc/html/rfc8439 ]] diff --git a/core/crypto/chacha20poly1305/chacha20poly1305.odin b/core/crypto/chacha20poly1305/chacha20poly1305.odin index f6f375a84..9840d357e 100644 --- a/core/crypto/chacha20poly1305/chacha20poly1305.odin +++ b/core/crypto/chacha20poly1305/chacha20poly1305.odin @@ -1,5 +1,5 @@ /* -package chacha20poly1305 implements the CHACHA20_POLY1305 and XChaCha20_Poly1305 AEAD algorithms. +`AEAD_CHACHA20_POLY1305` and `AEAD_XChaCha20_Poly1305` algorithms. Where AEAD stands for Authenticated Encryption with Additional Data. diff --git a/core/crypto/crypto.odin b/core/crypto/crypto.odin index 52ccb00de..89e92e35f 100644 --- a/core/crypto/crypto.odin +++ b/core/crypto/crypto.odin @@ -1,4 +1,4 @@ -// package crypto implements a selection of cryptography algorithms and useful helper routines. +// A selection of cryptography algorithms and useful helper routines. package crypto import "base:runtime" diff --git a/core/crypto/deoxysii/deoxysii.odin b/core/crypto/deoxysii/deoxysii.odin index db72ff194..3ebcfea30 100644 --- a/core/crypto/deoxysii/deoxysii.odin +++ b/core/crypto/deoxysii/deoxysii.odin @@ -1,5 +1,5 @@ /* -package deoxysii implements the Deoxys-II-256 Authenticated Encryption with Additional Data algorithm. +`Deoxys-II-256` Authenticated Encryption with Additional Data (`AEAD`) algorithm. - [[ https://sites.google.com/view/deoxyscipher ]] - [[ https://thomaspeyrin.github.io/web/assets/docs/papers/Jean-etal-JoC2021.pdf ]] diff --git a/core/crypto/ed25519/ed25519.odin b/core/crypto/ed25519/ed25519.odin index deeb80685..0382a6739 100644 --- a/core/crypto/ed25519/ed25519.odin +++ b/core/crypto/ed25519/ed25519.odin @@ -1,5 +1,5 @@ /* -package ed25519 implements the Ed25519 EdDSA signature algorithm. +`Ed25519` EdDSA signature algorithm. See: - [[ https://datatracker.ietf.org/doc/html/rfc8032 ]] diff --git a/core/crypto/hash/doc.odin b/core/crypto/hash/doc.odin index 1dfd97de2..992e47e86 100644 --- a/core/crypto/hash/doc.odin +++ b/core/crypto/hash/doc.odin @@ -1,5 +1,5 @@ /* -package hash provides a generic interface to the supported hash algorithms. +A generic interface to the supported hash algorithms. A high-level convenience procedure group `hash` is provided to easily accomplish common tasks. diff --git a/core/crypto/hkdf/hkdf.odin b/core/crypto/hkdf/hkdf.odin index 9d9497668..b3a6bf303 100644 --- a/core/crypto/hkdf/hkdf.odin +++ b/core/crypto/hkdf/hkdf.odin @@ -1,5 +1,5 @@ /* -package hkdf implements the HKDF HMAC-based Extract-and-Expand Key Derivation Function. +`HKDF` HMAC-based Extract-and-Expand Key Derivation Function. See: [[ https://www.rfc-editor.org/rfc/rfc5869 ]] */ diff --git a/core/crypto/hmac/hmac.odin b/core/crypto/hmac/hmac.odin index f74d6492f..1427baf34 100644 --- a/core/crypto/hmac/hmac.odin +++ b/core/crypto/hmac/hmac.odin @@ -1,5 +1,5 @@ /* -package hmac implements the HMAC MAC algorithm. +`HMAC` message authentication code (`MAC`) algorithm. See: - [[ https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.198-1.pdf ]] diff --git a/core/crypto/kmac/kmac.odin b/core/crypto/kmac/kmac.odin index 6f58e20a7..4ecff4f12 100644 --- a/core/crypto/kmac/kmac.odin +++ b/core/crypto/kmac/kmac.odin @@ -1,5 +1,5 @@ /* -package kmac implements the KMAC MAC algorithm. +`KMAC` message authentication code (`MAC`) algorithm. See: - [[ https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf ]] diff --git a/core/crypto/legacy/keccak/keccak.odin b/core/crypto/legacy/keccak/keccak.odin index 40fc2729f..369eee0d9 100644 --- a/core/crypto/legacy/keccak/keccak.odin +++ b/core/crypto/legacy/keccak/keccak.odin @@ -1,5 +1,5 @@ /* -package keccak implements the Keccak hash algorithm family. +`Keccak` hash algorithm family. During the SHA-3 standardization process, the padding scheme was changed thus Keccac and SHA-3 produce different outputs. Most users should use diff --git a/core/crypto/legacy/md5/md5.odin b/core/crypto/legacy/md5/md5.odin index 050501d98..2d58837c3 100644 --- a/core/crypto/legacy/md5/md5.odin +++ b/core/crypto/legacy/md5/md5.odin @@ -1,5 +1,5 @@ /* -package md5 implements the MD5 hash algorithm. +`MD5` hash algorithm. WARNING: The MD5 algorithm is known to be insecure and should only be used for interoperating with legacy applications. diff --git a/core/crypto/legacy/sha1/sha1.odin b/core/crypto/legacy/sha1/sha1.odin index 5a2b57005..ea74997af 100644 --- a/core/crypto/legacy/sha1/sha1.odin +++ b/core/crypto/legacy/sha1/sha1.odin @@ -1,5 +1,5 @@ /* -package sha1 implements the SHA1 hash algorithm. +`SHA1` hash algorithm. WARNING: The SHA1 algorithm is known to be insecure and should only be used for interoperating with legacy applications. diff --git a/core/crypto/pbkdf2/pbkdf2.odin b/core/crypto/pbkdf2/pbkdf2.odin index 8bb5cb73e..c96855b9c 100644 --- a/core/crypto/pbkdf2/pbkdf2.odin +++ b/core/crypto/pbkdf2/pbkdf2.odin @@ -1,5 +1,5 @@ /* -package pbkdf2 implements the PBKDF2 password-based key derivation function. +`PBKDF2` password-based key derivation function. See: [[ https://www.rfc-editor.org/rfc/rfc2898 ]] */ diff --git a/core/crypto/poly1305/poly1305.odin b/core/crypto/poly1305/poly1305.odin index 3dd915da7..d90f2ad54 100644 --- a/core/crypto/poly1305/poly1305.odin +++ b/core/crypto/poly1305/poly1305.odin @@ -1,5 +1,5 @@ /* -package poly1305 implements the Poly1305 one-time MAC algorithm. +`Poly1305` one-time MAC algorithm. See: - [[ https://datatracker.ietf.org/doc/html/rfc8439 ]] diff --git a/core/crypto/ristretto255/ristretto255.odin b/core/crypto/ristretto255/ristretto255.odin index 20a002900..78bf45c28 100644 --- a/core/crypto/ristretto255/ristretto255.odin +++ b/core/crypto/ristretto255/ristretto255.odin @@ -1,5 +1,5 @@ /* -package ristretto255 implement the ristretto255 prime-order group. +Ristretto255 prime-order group. See: - [[ https://www.rfc-editor.org/rfc/rfc9496 ]] diff --git a/core/crypto/sha2/sha2.odin b/core/crypto/sha2/sha2.odin index bf9b81601..9290650e7 100644 --- a/core/crypto/sha2/sha2.odin +++ b/core/crypto/sha2/sha2.odin @@ -1,5 +1,5 @@ /* -package sha2 implements the SHA2 hash algorithm family. +`SHA2` hash algorithm family. See: - [[ https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf ]] diff --git a/core/crypto/sha3/sha3.odin b/core/crypto/sha3/sha3.odin index 3b7bdedd7..738e7be0d 100644 --- a/core/crypto/sha3/sha3.odin +++ b/core/crypto/sha3/sha3.odin @@ -1,5 +1,5 @@ /* -package sha3 implements the SHA3 hash algorithm family. +`SHA3` hash algorithm family. The SHAKE XOF can be found in crypto/shake. While discouraged if the pre-standardization Keccak algorithm is required, it can be found in diff --git a/core/crypto/shake/shake.odin b/core/crypto/shake/shake.odin index e20795b43..6fcf5dd8d 100644 --- a/core/crypto/shake/shake.odin +++ b/core/crypto/shake/shake.odin @@ -1,5 +1,5 @@ /* -package shake implements the SHAKE and cSHAKE XOF algorithm families. +`SHAKE` and `cSHAKE` XOF algorithm families. The SHA3 hash algorithm can be found in the crypto/sha3. diff --git a/core/crypto/siphash/siphash.odin b/core/crypto/siphash/siphash.odin index f9fe50cb0..a091dfd4d 100644 --- a/core/crypto/siphash/siphash.odin +++ b/core/crypto/siphash/siphash.odin @@ -1,5 +1,5 @@ /* -package siphash Implements the SipHash hashing algorithm. +`SipHash` hashing algorithm. Use the specific procedures for a certain setup. The generic procedures will default to Siphash 2-4. diff --git a/core/crypto/sm3/sm3.odin b/core/crypto/sm3/sm3.odin index 6487c5e8c..ce62cfe49 100644 --- a/core/crypto/sm3/sm3.odin +++ b/core/crypto/sm3/sm3.odin @@ -1,5 +1,5 @@ /* -package sm3 implements the SM3 hash algorithm. +`SM3` hash algorithm. See: - [[ https://datatracker.ietf.org/doc/html/draft-sca-cfrg-sm3-02 ]] diff --git a/core/crypto/tuplehash/tuplehash.odin b/core/crypto/tuplehash/tuplehash.odin index e5caaa9c9..5c8d8e39b 100644 --- a/core/crypto/tuplehash/tuplehash.odin +++ b/core/crypto/tuplehash/tuplehash.odin @@ -1,5 +1,5 @@ /* -package tuplehash implements the TupleHash and TupleHashXOF algorithms. +`TupleHash` and `TupleHashXOF` algorithms. See: - [[ https://nvlpubs.nist.gov/nistpubs/specialpublications/nist.sp.800-185.pdf ]] diff --git a/core/crypto/x25519/x25519.odin b/core/crypto/x25519/x25519.odin index 8c0c6570d..e25d1831f 100644 --- a/core/crypto/x25519/x25519.odin +++ b/core/crypto/x25519/x25519.odin @@ -1,5 +1,5 @@ /* -package x25519 implements the X25519 (aka curve25519) Elliptic-Curve Diffie-Hellman key exchange protocol. +`X25519` (aka `curve25519`) Elliptic-Curve Diffie-Hellman key exchange protocol. See: - [[ https://www.rfc-editor.org/rfc/rfc7748 ]] diff --git a/core/crypto/x448/x448.odin b/core/crypto/x448/x448.odin index 727bacf27..75693e055 100644 --- a/core/crypto/x448/x448.odin +++ b/core/crypto/x448/x448.odin @@ -1,5 +1,5 @@ /* -package x448 implements the X448 (aka curve448) Elliptic-Curve Diffie-Hellman key exchange protocol. +`X448` (aka `curve448`) Elliptic-Curve Diffie-Hellman key exchange protocol. See: - [[ https://www.rfc-editor.org/rfc/rfc7748 ]] diff --git a/core/debug/pe/doc.odin b/core/debug/pe/doc.odin index 5de03446b..7590d328f 100644 --- a/core/debug/pe/doc.odin +++ b/core/debug/pe/doc.odin @@ -1,2 +1,2 @@ -// package pe implements a reader for the PE executable format for debug purposes. +// A reader for the Windows `PE` executable format for debug purposes. package debug_pe
\ No newline at end of file diff --git a/core/debug/trace/doc.odin b/core/debug/trace/doc.odin index 40f055161..c9b715653 100644 --- a/core/debug/trace/doc.odin +++ b/core/debug/trace/doc.odin @@ -1,4 +1,4 @@ -// package debug implements a stack trace library. Only works when debug symbols are enabled `-debug`. +// Stack trace library. Only works when debug symbols are enabled using `-debug`. package debug_trace /* Example: diff --git a/core/dynlib/doc.odin b/core/dynlib/doc.odin index 6cb443092..f727a299c 100644 --- a/core/dynlib/doc.odin +++ b/core/dynlib/doc.odin @@ -1,5 +1,5 @@ /* -package dynlib implements loading of shared libraries/DLLs and their symbols. +Cross-platform loading of shared libraries/DLLs and their symbols. The behaviour of dynamically loaded libraries is specific to the target platform of the program. For in depth detail on the underlying behaviour please refer to your target platform's documentation. 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 ]]. diff --git a/core/flags/doc.odin b/core/flags/doc.odin index 440acd52c..183b86f41 100644 --- a/core/flags/doc.odin +++ b/core/flags/doc.odin @@ -1,5 +1,5 @@ /* -package flags implements a command-line argument parser. +Command-line argument parser. It works by using Odin's run-time type information to determine where and how to store data on a struct provided by the program. Type conversion is handled diff --git a/core/fmt/doc.odin b/core/fmt/doc.odin index eeebd33f7..c0d6d5289 100644 --- a/core/fmt/doc.odin +++ b/core/fmt/doc.odin @@ -1,5 +1,5 @@ /* -package fmt implements formatted I/O with procedures similar to C's printf and Python's format. +Formatted `I/O` with procedures similar to `C`'s printf and `Python`'s format. The format 'verbs' are derived from C's but simpler. Printing diff --git a/core/hash/doc.odin b/core/hash/doc.odin index 5fdc79cb7..d7531a4c2 100644 --- a/core/hash/doc.odin +++ b/core/hash/doc.odin @@ -1,2 +1,2 @@ -// package hash implements crc32, crc64, adler32, djb, fnv, jenkins, murmur and other hashes. +// `crc32`, `crc64`, `adler32`, `djb`, `fnv`, `jenkins`, `murmur` and other hashes. package hash
\ No newline at end of file diff --git a/core/hash/xxhash/common.odin b/core/hash/xxhash/common.odin index a0f26fe4e..ce98f21f9 100644 --- a/core/hash/xxhash/common.odin +++ b/core/hash/xxhash/common.odin @@ -1,4 +1,4 @@ -// package xxhash implements Yann Collet's xxhash. +// Yann Collet's `xxhash`. // // [[ xxhash Fast Hash Algorithm; https://cyan4973.github.io/xxHash/ ]] package xxhash diff --git a/core/image/bmp/bmp.odin b/core/image/bmp/bmp.odin index 189e371de..efb0dd7d9 100644 --- a/core/image/bmp/bmp.odin +++ b/core/image/bmp/bmp.odin @@ -1,4 +1,4 @@ -// package bmp implements a Microsoft BMP image reader and writer. +// Reader and writer for Microsoft `BMP` images. package core_image_bmp import "core:image" diff --git a/core/image/doc.odin b/core/image/doc.odin index cb6bc4d96..1e44cca59 100644 --- a/core/image/doc.odin +++ b/core/image/doc.odin @@ -1,2 +1,2 @@ -// package image implements a general 2D image library to be used with other image related packages. +// General 2D image types and procedures to be used with other image related packages. package image
\ No newline at end of file diff --git a/core/image/jpeg/jpeg.odin b/core/image/jpeg/jpeg.odin index b95f6ef99..241066273 100644 --- a/core/image/jpeg/jpeg.odin +++ b/core/image/jpeg/jpeg.odin @@ -1,4 +1,4 @@ -// package jpeg implements a reader for baseline JPEG images. +// Reader for baseline `JPEG` images. package jpeg import "core:bytes" diff --git a/core/image/netpbm/doc.odin b/core/image/netpbm/doc.odin index 720a7dc2a..bac893b0f 100644 --- a/core/image/netpbm/doc.odin +++ b/core/image/netpbm/doc.odin @@ -1,5 +1,5 @@ /* -package netpbm implements readers and writers for PBM, PGM, PPM, PAM and PFM images. +Readers and writers for `PBM`, `PGM`, `PPM`, `PAM` and `PFM` images. Formats: diff --git a/core/image/png/doc.odin b/core/image/png/doc.odin index 6b402dcb2..034a6775f 100644 --- a/core/image/png/doc.odin +++ b/core/image/png/doc.odin @@ -1,5 +1,5 @@ /* -package png implements a PNG image reader. +Reader for `PNG` images. The PNG specification is at [[ https://www.w3.org/TR/PNG/ ]]. diff --git a/core/image/qoi/qoi.odin b/core/image/qoi/qoi.odin index 8e4ff03e0..a2b38a7a6 100644 --- a/core/image/qoi/qoi.odin +++ b/core/image/qoi/qoi.odin @@ -1,4 +1,4 @@ -// package qoi implements a QOI image reader. +// Reader and writer for `QOI` images. // // The QOI specification is at [[ https://qoiformat.org ]]. package qoi diff --git a/core/image/tga/tga.odin b/core/image/tga/tga.odin index f2e34484b..ad939e7ff 100644 --- a/core/image/tga/tga.odin +++ b/core/image/tga/tga.odin @@ -1,4 +1,4 @@ -// package tga implements a TGA image reader and writer for 8-bit RGB and RGBA images. +// Reader and writer for 8-bit RGB and RGBA `TGA` images. package tga /* diff --git a/core/io/io.odin b/core/io/io.odin index c4eb6a073..2c9b4379f 100644 --- a/core/io/io.odin +++ b/core/io/io.odin @@ -1,4 +1,4 @@ -// package io provides basic interfaces for generic data stream primitives. +// Basic interfaces for generic data stream primitives. // The purpose of this package is wrap existing data structures and their // operations into an abstracted stream interface. package io diff --git a/core/log/log.odin b/core/log/log.odin index 892132255..4209a2850 100644 --- a/core/log/log.odin +++ b/core/log/log.odin @@ -1,4 +1,4 @@ -// package log implements the context.Logger interface. +// Implementations of the `context.Logger` interface. package log import "base:runtime" diff --git a/core/math/big/doc.odin b/core/math/big/doc.odin deleted file mode 100644 index 04650d6dc..000000000 --- a/core/math/big/doc.odin +++ /dev/null @@ -1,7 +0,0 @@ -// package big implements arbitrary precision integers and rationals. -package math_big - -/* -For the theoretical underpinnings, see Knuth's The Art of Computer Programming, Volume 2, section 4.3. -The code started out as an idiomatic source port of libTomMath, which is in the public domain, with thanks. -*/
\ No newline at end of file diff --git a/core/math/big/public.odin b/core/math/big/public.odin index ed929a09d..dfefbc91a 100644 --- a/core/math/big/public.odin +++ b/core/math/big/public.odin @@ -1,3 +1,4 @@ +// Arbitrary precision integers and rationals.
package math_big
/*
diff --git a/core/math/bits/bits.odin b/core/math/bits/bits.odin index f9059f7d8..effcf4985 100644 --- a/core/math/bits/bits.odin +++ b/core/math/bits/bits.odin @@ -1,4 +1,4 @@ -// package bits implements bit-level operations, including the ability to set or toggle individual bits in an integer. +// Bit-level operations, including the ability to set or toggle individual bits in an integer. package math_bits import "base:intrinsics" diff --git a/core/math/cmplx/cmplx.odin b/core/math/cmplx/cmplx.odin index 3249cc4b4..f5c572cc6 100644 --- a/core/math/cmplx/cmplx.odin +++ b/core/math/cmplx/cmplx.odin @@ -1,4 +1,4 @@ -// package cmplx implements trigonometric and other mathematic operations on complex numbers. +// Trigonometric and other mathematic operations on complex numbers. package math_cmplx import "base:builtin" diff --git a/core/math/ease/ease.odin b/core/math/ease/ease.odin index 2d6a7c924..c6dd56dbc 100644 --- a/core/math/ease/ease.odin +++ b/core/math/ease/ease.odin @@ -1,4 +1,4 @@ -// package ease implements easing procedures and flux easing used for animations. +// Easing procedures and flux easing used for animations. package ease import "core:math" diff --git a/core/math/fixed/fixed.odin b/core/math/fixed/fixed.odin index 0f0555e4e..28f87b6d2 100644 --- a/core/math/fixed/fixed.odin +++ b/core/math/fixed/fixed.odin @@ -1,4 +1,4 @@ -// package fixed implements fixed-point rational numbers and conversion to/from `f64`. +// Fixed-point rational numbers and conversion to/from `f64`. package math_fixed import "core:math" diff --git a/core/math/linalg/doc.odin b/core/math/linalg/doc.odin index be1686bb8..38a894148 100644 --- a/core/math/linalg/doc.odin +++ b/core/math/linalg/doc.odin @@ -1,2 +1,2 @@ -// package linalg implements linear algebra procedures useful for 3D spatial transformations. +// Linear algebra procedures useful for 3D spatial transformations. package linalg diff --git a/core/math/linalg/glsl/linalg_glsl.odin b/core/math/linalg/glsl/linalg_glsl.odin index c24908b0f..46ee7a6f7 100644 --- a/core/math/linalg/glsl/linalg_glsl.odin +++ b/core/math/linalg/glsl/linalg_glsl.odin @@ -1,4 +1,4 @@ -// package glsl implements a GLSL-like mathematics library plus numerous other utility procedures. +// `GLSL`-like mathematics library plus numerous other utility procedures. package math_linalg_glsl import "base:builtin" diff --git a/core/math/linalg/hlsl/linalg_hlsl.odin b/core/math/linalg/hlsl/linalg_hlsl.odin index 3993f7055..5c78bd8b1 100644 --- a/core/math/linalg/hlsl/linalg_hlsl.odin +++ b/core/math/linalg/hlsl/linalg_hlsl.odin @@ -1,4 +1,4 @@ -// package hlsl implements a HLSL-like mathematics library plus numerous other utility procedures. +// `HLSL`-like mathematics library plus numerous other utility procedures. package math_linalg_hlsl import "base:builtin" diff --git a/core/math/math.odin b/core/math/math.odin index 39f2be42c..34642049c 100644 --- a/core/math/math.odin +++ b/core/math/math.odin @@ -1,4 +1,4 @@ -// package math implements typical trignometric and other basic math routines. +// Typical trignometric and other basic math routines. package math import "base:intrinsics" diff --git a/core/math/noise/opensimplex2.odin b/core/math/noise/opensimplex2.odin index 08ff3c938..ef12a26fa 100644 --- a/core/math/noise/opensimplex2.odin +++ b/core/math/noise/opensimplex2.odin @@ -1,5 +1,5 @@ /* - package noise implements the OpenSimplex2 noise algorithm. + `OpenSimplex2` noise algorithm. Ported from [[ https://github.com/KdotJPG/OpenSimplex2 }]. Copyright 2022 Yuki2 [[ https://github.com/NoahR02 ]] diff --git a/core/math/rand/rand.odin b/core/math/rand/rand.odin index 4feecc8bb..8e270b7df 100644 --- a/core/math/rand/rand.odin +++ b/core/math/rand/rand.odin @@ -1,4 +1,4 @@ -// package rand implements various random number generators. +// Random number generators. package rand import "base:intrinsics" diff --git a/core/mem/doc.odin b/core/mem/doc.odin index 8b4a77b6c..657251902 100644 --- a/core/mem/doc.odin +++ b/core/mem/doc.odin @@ -1,5 +1,5 @@ /* -package mem implements various allocators and provides helpers for dealing with memory, pointers and slices. +Various allocators and provides helpers for dealing with memory, pointers and slices. The documentation below describes basic concepts, applicable to the `mem` package. diff --git a/core/mem/tlsf/tlsf.odin b/core/mem/tlsf/tlsf.odin index 792abb08e..37c6858ec 100644 --- a/core/mem/tlsf/tlsf.odin +++ b/core/mem/tlsf/tlsf.odin @@ -1,4 +1,4 @@ -// package tlsf implements a Two Level Segregated Fit memory allocator. +// Two Level Segregated Fit memory allocator. package mem_tlsf /* diff --git a/core/mem/virtual/doc.odin b/core/mem/virtual/doc.odin index b423afde6..614e290c3 100644 --- a/core/mem/virtual/doc.odin +++ b/core/mem/virtual/doc.odin @@ -1,5 +1,5 @@ /* -package virtual implements a platform agnostic way to reserve/commit/decommit virtual memory. +A platform agnostic way to reserve/commit/decommit virtual memory. virtual.Arena usage diff --git a/core/net/doc.odin b/core/net/doc.odin index 1d6ad776a..082a1497a 100644 --- a/core/net/doc.odin +++ b/core/net/doc.odin @@ -1,5 +1,5 @@ /* -package net implements cross-platform Berkeley Sockets, DNS resolution and associated procedures. +Cross-platform Berkeley Sockets, `DNS` resolution and associated procedures. Features: - Supports Windows, Linux and OSX. diff --git a/core/odin/ast/ast.odin b/core/odin/ast/ast.odin index d69a51f92..4dcc1f215 100644 --- a/core/odin/ast/ast.odin +++ b/core/odin/ast/ast.odin @@ -1,4 +1,4 @@ -// package ast implements the Abstract Syntax Tree for the Odin parser packages. +// Abstract Syntax Tree for the `Odin` parser packages. package odin_ast import "core:odin/tokenizer" diff --git a/core/odin/doc-format/doc_format.odin b/core/odin/doc-format/doc_format.odin index b9a9cc2d3..e37092948 100644 --- a/core/odin/doc-format/doc_format.odin +++ b/core/odin/doc-format/doc_format.odin @@ -1,4 +1,4 @@ -// package doc-format implements the .odin-doc file format, as used by these package docs at pkg.odin-lang.org. +// The `.odin-doc` file format, as used by these package docs at `pkg.odin-lang.org`. package odin_doc_format import "core:mem" diff --git a/core/odin/doc.odin b/core/odin/doc.odin index 69c40ccaf..40aeaea7f 100644 --- a/core/odin/doc.odin +++ b/core/odin/doc.odin @@ -1,2 +1,2 @@ -// package odin implements a lexer and parser for the Odin language for the purposes of writing tooling. +// A lexer and parser for the `Odin` language for the purposes of writing tooling. package odin
\ No newline at end of file diff --git a/core/odin/parser/parser.odin b/core/odin/parser/parser.odin index e898b030f..94ea649f9 100644 --- a/core/odin/parser/parser.odin +++ b/core/odin/parser/parser.odin @@ -1,4 +1,4 @@ -// package parser implements the *.odin file parser to be used in tooling. +// The `Odin` file parser to be used in tooling. package odin_parser import "core:odin/ast" diff --git a/core/odin/tokenizer/tokenizer.odin b/core/odin/tokenizer/tokenizer.odin index 6f4d4eb16..9f46f2ed6 100644 --- a/core/odin/tokenizer/tokenizer.odin +++ b/core/odin/tokenizer/tokenizer.odin @@ -1,4 +1,4 @@ -// package tokenizer implements the tokenizer (lexer) for *.odin files, used to create tooling. +// The tokenizer (lexer) for `Odin` files, used to create tooling. package odin_tokenizer import "core:fmt" diff --git a/core/os/os.odin b/core/os/os.odin index 0c437c5ff..da7b0c151 100644 --- a/core/os/os.odin +++ b/core/os/os.odin @@ -1,4 +1,4 @@ -// package os implements cross-platform OS interactions like file I/O. +// Cross-platform `OS` interactions like file `I/O`. package os import "base:intrinsics" diff --git a/core/path/filepath/path.odin b/core/path/filepath/path.odin index d23fa1ff1..14a9181c3 100644 --- a/core/path/filepath/path.odin +++ b/core/path/filepath/path.odin @@ -1,4 +1,4 @@ -// package filepath package uses either forward slashes or backslashes depending on the operating system. +// Process paths using either forward slashes or backslashes depending on the operating system. // To process paths such as URLs that depend on forward slashes regardless of the OS, use the slashpath package. package filepath diff --git a/core/path/slashpath/path.odin b/core/path/slashpath/path.odin index 5067fa147..1d2a24453 100644 --- a/core/path/slashpath/path.odin +++ b/core/path/slashpath/path.odin @@ -1,4 +1,4 @@ -// package slashpath is only to be used for paths separated by forward slashes, e.g. paths in URLs.
+// Process paths separated by forward slashes only, e.g. paths in `URL`s.
//
// This package does not deal with Windows/NT paths with volume letters or backslashes
// To manipulate operating system specific paths, use the path/filepath package
diff --git a/core/prof/spall/doc.odin b/core/prof/spall/doc.odin index 597527b84..2098a12d6 100644 --- a/core/prof/spall/doc.odin +++ b/core/prof/spall/doc.odin @@ -1,5 +1,5 @@ /* -package spall is a package that is used for profiling using the "spall" format. +Profiling using the "`spall`" format. Example: package main diff --git a/core/reflect/doc.odin b/core/reflect/doc.odin index eb8bd7030..5ec5e7070 100644 --- a/core/reflect/doc.odin +++ b/core/reflect/doc.odin @@ -1,4 +1,4 @@ -// package reflect provides utility procedures and types to perform runtime type introspection/reflection (RTTI). +// Utility procedures and types to perform runtime type introspection/reflection (`RTTI`). // // WARNING! THIS IS ADVANCED BEHAVIOUR FOR ODIN! THIS SHOULD NOT BE USED BY BEGINNERS TO ODIN! // diff --git a/core/relative/relative.odin b/core/relative/relative.odin index c3e55971b..791ac6f7d 100644 --- a/core/relative/relative.odin +++ b/core/relative/relative.odin @@ -1,4 +1,4 @@ -// package relative implements relative pointers and slices. +// Relative pointers and slices. package relative_types import "base:intrinsics" diff --git a/core/simd/simd.odin b/core/simd/simd.odin index 3aee09944..bca661757 100644 --- a/core/simd/simd.odin +++ b/core/simd/simd.odin @@ -1,5 +1,5 @@ /* -package simd implements cross-platform SIMD support types and procedures. +Cross-platform `SIMD` support types and procedures. SIMD (Single Instruction Multiple Data), is a CPU hardware feature that introduce special registers and instructions which operate on multiple units diff --git a/core/simd/x86/doc.odin b/core/simd/x86/doc.odin index 1a43fa3aa..dcdc30abd 100644 --- a/core/simd/x86/doc.odin +++ b/core/simd/x86/doc.odin @@ -1,2 +1,2 @@ -// package x86 implements SIMD intrinsics specific to the Intel x86 and AMD64 architectures. +// `SIMD` intrinsics specific to the Intel `x86` and `AMD64` architectures. package simd_x86
\ No newline at end of file diff --git a/core/slice/heap/heap.odin b/core/slice/heap/heap.odin index f3c016656..dd088f250 100644 --- a/core/slice/heap/heap.odin +++ b/core/slice/heap/heap.odin @@ -1,4 +1,4 @@ -// package heap implements a generic in-place max heap on a slice for any type. +// A generic in-place max heap on a slice for any type. package heap /* diff --git a/core/slice/slice.odin b/core/slice/slice.odin index b103473b7..0d0cadefa 100644 --- a/core/slice/slice.odin +++ b/core/slice/slice.odin @@ -1,4 +1,4 @@ -// package slice implements utility procedures for working with slices, including sorting and searching them. +// Utility procedures for working with slices, including sorting and searching them. package slice import "base:intrinsics" diff --git a/core/sort/sort.odin b/core/sort/sort.odin index c4aca4188..63cb50490 100644 --- a/core/sort/sort.odin +++ b/core/sort/sort.odin @@ -1,3 +1,4 @@ +// A sorting interface and algorithms. package sort import "core:mem" diff --git a/core/strconv/decimal/decimal.odin b/core/strconv/decimal/decimal.odin index 5a878d0e1..98891a548 100644 --- a/core/strconv/decimal/decimal.odin +++ b/core/strconv/decimal/decimal.odin @@ -1,5 +1,6 @@ -// Multiple precision decimal numbers -// NOTE: This is only for floating point printing and nothing else +// Multiple precision decimal numbers for use by the `strconv` package. +// +// NOTE: This is only for floating point printing and nothing else. package strconv_decimal Decimal :: struct { diff --git a/core/strconv/strconv.odin b/core/strconv/strconv.odin index 5634f1712..48a75d972 100644 --- a/core/strconv/strconv.odin +++ b/core/strconv/strconv.odin @@ -1,4 +1,4 @@ -// package strconv implements conversions to and from string represnetations of other data types +// Conversions to and from `string` representations of other data types like integers and booleans. package strconv import "core:unicode/utf8" diff --git a/core/strings/strings.odin b/core/strings/strings.odin index 79a8cec29..d13b45022 100644 --- a/core/strings/strings.odin +++ b/core/strings/strings.odin @@ -1,4 +1,4 @@ -// Procedures to manipulate UTF-8 encoded strings +// A `string` builder, as well as procedures to manipulate `UTF-8` encoded strings. package strings import "base:intrinsics" diff --git a/core/sync/chan/doc.odin b/core/sync/chan/doc.odin index 5d65d7410..63e633531 100644 --- a/core/sync/chan/doc.odin +++ b/core/sync/chan/doc.odin @@ -1,6 +1,5 @@ /* -This package provides both high-level and low-level channel types -for thread-safe communication. +High-level and low-level channel types for thread-safe communication. While channels are essentially thread-safe queues under the hood, their primary purpose is to facilitate safe communication between diff --git a/core/sync/doc.odin b/core/sync/doc.odin index 320732ea7..faae245c4 100644 --- a/core/sync/doc.odin +++ b/core/sync/doc.odin @@ -1,11 +1,7 @@ /* -Synchronization primitives +Various synchronization primitives useful to mediate threads' access to shared memory. -This package implements various synchronization primitives that can be used to -synchronize threads' access to shared memory. - -To limit or control the threads' access to shared memory typically the -following approaches are used: +To limit or control the threads' access to shared memory typically the following approaches are used: - Locks - Lock-free diff --git a/core/sys/info/doc.odin b/core/sys/info/doc.odin index 2a4f71642..d19bb13a0 100644 --- a/core/sys/info/doc.odin +++ b/core/sys/info/doc.odin @@ -1,15 +1,5 @@ /* -Copyright 2022 Jeroen van Rijn <nom@duclavier.com>. -Made available under Odin's BSD-3 license. - -List of contributors: - Jeroen van Rijn: Initial implementation. - Laytan: ARM and RISC-V CPU feature detection, iOS/macOS platform overhaul. -*/ - -/* -Package `core:sys/info` gathers system information on: -Windows, Linux, macOS, FreeBSD & OpenBSD. +Gathers system information on `Windows`, `Linux`, `macOS`, `FreeBSD` & `OpenBSD`. Simply import the package and you'll have access to the OS version, RAM amount and CPU information. @@ -87,3 +77,12 @@ Example: RAM: 8.0 GiB */ package sysinfo + +/* +Copyright 2022 Jeroen van Rijn <nom@duclavier.com>. +Made available under Odin's BSD-3 license. + +List of contributors: + Jeroen van Rijn: Initial implementation. + Laytan: ARM and RISC-V CPU feature detection, iOS/macOS platform overhaul. +*/
\ No newline at end of file diff --git a/core/sys/orca/macros.odin b/core/sys/orca/macros.odin index 12adfdb91..60dbdae99 100644 --- a/core/sys/orca/macros.odin +++ b/core/sys/orca/macros.odin @@ -1,4 +1,4 @@ -// File contains implementations of the Orca API that are defined as macros in Orca. +// Implementations of the `Orca` API that are defined as macros in Orca. package orca diff --git a/core/sys/posix/posix.odin b/core/sys/posix/posix.odin index 3dcf36a5e..49353e875 100644 --- a/core/sys/posix/posix.odin +++ b/core/sys/posix/posix.odin @@ -1,5 +1,5 @@ /* -Raw bindings for most POSIX APIs. +Raw bindings for most `POSIX` APIs. Targets glibc and musl compatibility. diff --git a/core/terminal/ansi/doc.odin b/core/terminal/ansi/doc.odin index 966e6be00..7f1d30b1b 100644 --- a/core/terminal/ansi/doc.odin +++ b/core/terminal/ansi/doc.odin @@ -1,7 +1,6 @@ /* -package ansi implements constant references to many widely-supported ANSI -escape codes, primarily used in terminal emulators for enhanced graphics, such -as colors, text styling, and animated displays. +Constant references to many widely-supported `ANSI` escape codes. +Primarily used in terminal emulators for enhanced graphics, such as colors, text styling, and animated displays. For example, you can print out a line of cyan text like this: fmt.println(ansi.CSI + ansi.FG_CYAN + ansi.SGR + "Hellope!" + ansi.CSI + ansi.RESET + ansi.SGR) diff --git a/core/terminal/doc.odin b/core/terminal/doc.odin deleted file mode 100644 index 490e9d398..000000000 --- a/core/terminal/doc.odin +++ /dev/null @@ -1,4 +0,0 @@ -/* -This package is for interacting with the command line interface of the system. -*/ -package terminal diff --git a/core/terminal/terminal.odin b/core/terminal/terminal.odin index 1e5566295..37fdaff36 100644 --- a/core/terminal/terminal.odin +++ b/core/terminal/terminal.odin @@ -1,3 +1,4 @@ +// Interaction with the command line interface (`CLI`) of the system. package terminal import "core:os" diff --git a/core/testing/testing.odin b/core/testing/testing.odin index 1357a4683..a0b046a46 100644 --- a/core/testing/testing.odin +++ b/core/testing/testing.odin @@ -1,3 +1,4 @@ +// The implementation of the `odin test` runner and procedures user tests can use for this purpose. package testing /* 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: diff --git a/core/thread/thread.odin b/core/thread/thread.odin index c5018a5fe..26c1a3e27 100644 --- a/core/thread/thread.odin +++ b/core/thread/thread.odin @@ -1,4 +1,4 @@ -// package thread implements multi-threading operations so spawn threads and thread pools +// Multi-threading operations to spawn threads and thread pools. package thread import "base:runtime" diff --git a/core/time/time.odin b/core/time/time.odin index b488f951c..ac68346b3 100644 --- a/core/time/time.odin +++ b/core/time/time.odin @@ -1,3 +1,4 @@ +// `Time`-related procedures and types, including `sleep`, `now`, and string formatting of moments. package time import "base:intrinsics" diff --git a/core/time/timezone/tzdate.odin b/core/time/timezone/tzdate.odin index 8e900ec11..f01553573 100644 --- a/core/time/timezone/tzdate.odin +++ b/core/time/timezone/tzdate.odin @@ -1,3 +1,4 @@ +// Timezone lookup. package timezone import "core:fmt" diff --git a/core/unicode/doc.odin b/core/unicode/doc.odin index 4d9ff78f5..302fd59e1 100644 --- a/core/unicode/doc.odin +++ b/core/unicode/doc.odin @@ -1,2 +1,2 @@ -// package unicode provides data and procedures to test properties of Unicode code points +// Data and procedures to test properties of `Unicode` code points. package unicode
\ No newline at end of file diff --git a/core/unicode/utf16/utf16.odin b/core/unicode/utf16/utf16.odin index 75c553f62..990d5bafa 100644 --- a/core/unicode/utf16/utf16.odin +++ b/core/unicode/utf16/utf16.odin @@ -1,4 +1,4 @@ -// package utf16 implements procedures and constants to support text-encoding in the UTF-16 character encoding +// Procedures and constants to support text-encoding in the `UTF-16` character encoding. package utf16 import "core:unicode/utf8" diff --git a/core/unicode/utf8/utf8.odin b/core/unicode/utf8/utf8.odin index 5740ae71e..281e36f43 100644 --- a/core/unicode/utf8/utf8.odin +++ b/core/unicode/utf8/utf8.odin @@ -1,4 +1,4 @@ -// package utf8 implements procedures and constants to support text-encoding in the UTF-8 character encoding +// Procedures and constants to support text-encoding in the `UTF-8` character encoding. package utf8 RUNE_ERROR :: '\ufffd' diff --git a/core/unicode/utf8/utf8string/string.odin b/core/unicode/utf8/utf8string/string.odin index 7d067a9bf..7ece469a4 100644 --- a/core/unicode/utf8/utf8string/string.odin +++ b/core/unicode/utf8/utf8string/string.odin @@ -1,4 +1,4 @@ -// package utf8string provides a convenient and efficient way to index strings by Unicode code point (rune) rather than byte +// A convenient and efficient way to index strings by `Unicode` code point (`rune`) rather than byte. package utf8string import "core:unicode/utf8" |