From aa852f737b7504e01d0a4cd08c115ae508bb81c7 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Sun, 10 Mar 2024 18:10:51 -0700 Subject: [PATCH] improve documentation in std A lot of these "shorthand" doc comments were redundant, low quality filler content. Better to let the actual modules speak for themselves with top level doc comments rather than trying to document their aliases. --- lib/std/base64.zig | 2 + lib/std/builtin.zig | 2 + lib/std/compress.zig | 2 + lib/std/crypto.zig | 2 + lib/std/dwarf.zig | 2 + lib/std/elf.zig | 2 + lib/std/fmt.zig | 2 + lib/std/fs.zig | 2 + lib/std/net.zig | 2 + lib/std/simd.zig | 10 +++-- lib/std/std.zig | 93 -------------------------------------------- lib/std/zig.zig | 4 ++ 12 files changed, 28 insertions(+), 97 deletions(-) diff --git a/lib/std/base64.zig b/lib/std/base64.zig index ce84e640d1e21a3b9aea048385d81a03ed3b850b..2627480295bd7e14a05a706a7556c14f20d7f0ad 100644 --- a/lib/std/base64.zig +++ b/lib/std/base64.zig @@ -1,3 +1,5 @@ +//! Base64 encoding/decoding. + const std = @import("std.zig"); const assert = std.debug.assert; const builtin = @import("builtin"); diff --git a/lib/std/builtin.zig b/lib/std/builtin.zig index fc85d32d5225ed4dec973beb68e44882319616cd..3339a5337e61f7d898795d54e53f3da21ae8281b 100644 --- a/lib/std/builtin.zig +++ b/lib/std/builtin.zig @@ -1,3 +1,5 @@ +//! Types and values provided by the Zig language. + const builtin = @import("builtin"); /// `explicit_subsystem` is missing when the subsystem is automatically detected, diff --git a/lib/std/compress.zig b/lib/std/compress.zig index a6d0a40b26ef7d5ff28795b1c43e4ffcabc56280..200489c18ab5de09f179076225ab250aa7ad50ad 100644 --- a/lib/std/compress.zig +++ b/lib/std/compress.zig @@ -1,3 +1,5 @@ +//! Compression algorithms. + const std = @import("std.zig"); pub const flate = @import("compress/flate.zig"); diff --git a/lib/std/crypto.zig b/lib/std/crypto.zig index c548f01c07f6cfbf7578c43cf7a4361e0c2b29d0..fe6e96c2dddbad9820ad2b7b597bd72c98b07bb1 100644 --- a/lib/std/crypto.zig +++ b/lib/std/crypto.zig @@ -1,3 +1,5 @@ +//! Cryptography. + const root = @import("root"); /// Authenticated Encryption with Associated Data diff --git a/lib/std/dwarf.zig b/lib/std/dwarf.zig index 2544f35c420970efcbe4ae0953b568b1208c0f6b..aeeff5f41d98204fcd7c76a21a8628916faaa446 100644 --- a/lib/std/dwarf.zig +++ b/lib/std/dwarf.zig @@ -1,3 +1,5 @@ +//! DWARF debugging data format. + const builtin = @import("builtin"); const std = @import("std.zig"); const debug = std.debug; diff --git a/lib/std/elf.zig b/lib/std/elf.zig index e40c215e83dc8b4c1b58aa16846790d84d404b87..bdb84f51719a7465ac107fd11ec6e95ceef91983 100644 --- a/lib/std/elf.zig +++ b/lib/std/elf.zig @@ -1,3 +1,5 @@ +//! Executable and Linkable Format. + const std = @import("std.zig"); const math = std.math; const mem = std.mem; diff --git a/lib/std/fmt.zig b/lib/std/fmt.zig index 262d51bcee6c2d68fc874040e1f81ecdee88ea06..359451628733bee7175cf42d2878ae08ee962cc4 100644 --- a/lib/std/fmt.zig +++ b/lib/std/fmt.zig @@ -1,3 +1,5 @@ +//! String formatting and parsing. + const std = @import("std.zig"); const builtin = @import("builtin"); diff --git a/lib/std/fs.zig b/lib/std/fs.zig index 6eba6fcb922db02872f91c880c9970b81cb63a1d..c9294e727a6b47843fcd608f6384cee458dadfe4 100644 --- a/lib/std/fs.zig +++ b/lib/std/fs.zig @@ -1,3 +1,5 @@ +//! File System. + const std = @import("std.zig"); const builtin = @import("builtin"); const root = @import("root"); diff --git a/lib/std/net.zig b/lib/std/net.zig index 66b90867c642b60568c591728035acc287b59808..e68adc4207ff6442d5101c07265309c496f3d5cc 100644 --- a/lib/std/net.zig +++ b/lib/std/net.zig @@ -1,3 +1,5 @@ +//! Cross-platform networking abstractions. + const std = @import("std.zig"); const builtin = @import("builtin"); const assert = std.debug.assert; diff --git a/lib/std/simd.zig b/lib/std/simd.zig index c3ae2d8dbecd1c3bd3a60cfe0bcd8fd8b5fde55e..7fe9b839cc0d9f2ea06fda9ed37edb9b378d493f 100644 --- a/lib/std/simd.zig +++ b/lib/std/simd.zig @@ -1,7 +1,9 @@ -//! This module provides functions for working conveniently with SIMD (Single Instruction; Multiple Data), -//! which may offer a potential boost in performance on some targets by performing the same operations on -//! multiple elements at once. -//! Please be aware that some functions are known to not work on MIPS. +//! SIMD (Single Instruction; Multiple Data) convenience functions. +//! +//! May offer a potential boost in performance on some targets by performing +//! the same operations on multiple elements at once. +//! +//! Some functions are known to not work on MIPS. const std = @import("std"); const builtin = @import("builtin"); diff --git a/lib/std/std.zig b/lib/std/std.zig index 0781c877cfa40eede762e5a25deb2a56d9cb0d75..557b320c244e97c67aa4bc219cc2d551ef0b62eb 100644 --- a/lib/std/std.zig +++ b/lib/std/std.zig @@ -55,149 +55,56 @@ pub const Tz = tz.Tz; pub const Uri = @import("Uri.zig"); pub const array_hash_map = @import("array_hash_map.zig"); - -/// Memory ordering, atomic data structures, and operations. pub const atomic = @import("atomic.zig"); - -/// Base64 encoding/decoding. pub const base64 = @import("base64.zig"); - -/// Bit manipulation data structures. pub const bit_set = @import("bit_set.zig"); - -/// Comptime-available information about the build environment, such as the target and optimize mode. pub const builtin = @import("builtin.zig"); - pub const c = @import("c.zig"); - -/// COFF format. pub const coff = @import("coff.zig"); - -/// Compression algorithms such as zlib, zstd, etc. pub const compress = @import("compress.zig"); - pub const comptime_string_map = @import("comptime_string_map.zig"); - -/// Cryptography. pub const crypto = @import("crypto.zig"); - -/// Debug printing, allocation and other debug helpers. pub const debug = @import("debug.zig"); - -/// DWARF debugging data format. pub const dwarf = @import("dwarf.zig"); - -/// ELF format. pub const elf = @import("elf.zig"); - -/// Enum-related metaprogramming helpers. pub const enums = @import("enums.zig"); - -/// First in, first out data structures. pub const fifo = @import("fifo.zig"); - -/// String formatting and parsing (e.g. parsing numbers out of strings). pub const fmt = @import("fmt.zig"); - -/// File system-related functionality. pub const fs = @import("fs.zig"); - -/// GPU programming helpers. pub const gpu = @import("gpu.zig"); - -/// Fast hashing functions (i.e. not cryptographically secure). pub const hash = @import("hash.zig"); pub const hash_map = @import("hash_map.zig"); - -/// Allocator implementations. pub const heap = @import("heap.zig"); - -/// HTTP client and server. pub const http = @import("http.zig"); - -/// I/O streams, reader/writer interfaces and common helpers. pub const io = @import("io.zig"); - -/// JSON parsing and serialization. pub const json = @import("json.zig"); - -/// LEB128 encoding. pub const leb = @import("leb128.zig"); - -/// A standardized interface for logging. pub const log = @import("log.zig"); - -/// Mach-O format. pub const macho = @import("macho.zig"); - -/// Mathematical constants and operations. pub const math = @import("math.zig"); - -/// Functions for comparing, searching, and manipulating memory. pub const mem = @import("mem.zig"); - -/// Metaprogramming helpers. pub const meta = @import("meta.zig"); - -/// Networking. pub const net = @import("net.zig"); - -/// POSIX-like API layer. pub const posix = @import("os.zig"); - /// Non-portable Operating System-specific API. pub const os = @import("os.zig"); - pub const once = @import("once.zig").once; - -/// A set of array and slice types that bit-pack integer elements. pub const packed_int_array = @import("packed_int_array.zig"); - -/// PDB file format. pub const pdb = @import("pdb.zig"); - -/// Accessors for process-related info (e.g. command line arguments) -/// and spawning of child processes. pub const process = @import("process.zig"); - /// Deprecated: use `Random` instead. pub const rand = Random; - -/// Sorting. pub const sort = @import("sort.zig"); - -/// Single Instruction Multiple Data (SIMD) helpers. pub const simd = @import("simd.zig"); - -/// ASCII text processing. pub const ascii = @import("ascii.zig"); - -/// Tar archive format compression/decompression. pub const tar = @import("tar.zig"); - -/// Testing allocator, testing assertions, and other helpers for testing code. pub const testing = @import("testing.zig"); - -/// Sleep, obtaining the current time, conversion constants, and more. pub const time = @import("time.zig"); - -/// Time zones. pub const tz = @import("tz.zig"); - -/// UTF-8 and UTF-16LE encoding/decoding. pub const unicode = @import("unicode.zig"); - -/// Helpers for integrating with Valgrind. pub const valgrind = @import("valgrind.zig"); - -/// Constants and types representing the Wasm binary format. pub const wasm = @import("wasm.zig"); - -/// Builds of the Zig compiler are distributed partly in source form. That -/// source lives here. These APIs are provided as-is and have absolutely no API -/// guarantees whatsoever. pub const zig = @import("zig.zig"); - pub const start = @import("start.zig"); const root = @import("root"); diff --git a/lib/std/zig.zig b/lib/std/zig.zig index 46fb5623102ab52d3a0e5055351c75b8970bb858..c887030ae691f10c55546516d2d91a89184ee81e 100644 --- a/lib/std/zig.zig +++ b/lib/std/zig.zig @@ -1,3 +1,7 @@ +//! Builds of the Zig compiler are distributed partly in source form. That +//! source lives here. These APIs are provided as-is and have absolutely no API +//! guarantees whatsoever. + pub const ErrorBundle = @import("zig/ErrorBundle.zig"); pub const Server = @import("zig/Server.zig"); pub const Client = @import("zig/Client.zig"); -- 2.54.0