authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-03-10 18:10:51-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-03-10 18:13:30-07:00
logaa852f737b7504e01d0a4cd08c115ae508bb81c7
tree026250727cfe4dcfe1e06a2f9fec411b4dd60034
parentb13a55db97b14fac0462d2a1cb83be8dcb2eb335

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.

12 files changed, 28 insertions(+), 97 deletions(-)

lib/std/base64.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! Base64 encoding/decoding.
2
1const std = @import("std.zig");3const std = @import("std.zig");
2const assert = std.debug.assert;4const assert = std.debug.assert;
3const builtin = @import("builtin");5const builtin = @import("builtin");
lib/std/builtin.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! Types and values provided by the Zig language.
2
1const builtin = @import("builtin");3const builtin = @import("builtin");
24
3/// `explicit_subsystem` is missing when the subsystem is automatically detected,5/// `explicit_subsystem` is missing when the subsystem is automatically detected,
lib/std/compress.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! Compression algorithms.
2
1const std = @import("std.zig");3const std = @import("std.zig");
24
3pub const flate = @import("compress/flate.zig");5pub const flate = @import("compress/flate.zig");
lib/std/crypto.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! Cryptography.
2
1const root = @import("root");3const root = @import("root");
24
3/// Authenticated Encryption with Associated Data5/// Authenticated Encryption with Associated Data
lib/std/dwarf.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! DWARF debugging data format.
2
1const builtin = @import("builtin");3const builtin = @import("builtin");
2const std = @import("std.zig");4const std = @import("std.zig");
3const debug = std.debug;5const debug = std.debug;
lib/std/elf.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! Executable and Linkable Format.
2
1const std = @import("std.zig");3const std = @import("std.zig");
2const math = std.math;4const math = std.math;
3const mem = std.mem;5const mem = std.mem;
lib/std/fmt.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! String formatting and parsing.
2
1const std = @import("std.zig");3const std = @import("std.zig");
2const builtin = @import("builtin");4const builtin = @import("builtin");
35
lib/std/fs.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! File System.
2
1const std = @import("std.zig");3const std = @import("std.zig");
2const builtin = @import("builtin");4const builtin = @import("builtin");
3const root = @import("root");5const root = @import("root");
lib/std/net.zig+2
...@@ -1,3 +1,5 @@...@@ -1,3 +1,5 @@
1//! Cross-platform networking abstractions.
2
1const std = @import("std.zig");3const std = @import("std.zig");
2const builtin = @import("builtin");4const builtin = @import("builtin");
3const assert = std.debug.assert;5const assert = std.debug.assert;
lib/std/simd.zig+6-4
...@@ -1,7 +1,9 @@...@@ -1,7 +1,9 @@
1//! This module provides functions for working conveniently with SIMD (Single Instruction; Multiple Data),1//! SIMD (Single Instruction; Multiple Data) convenience functions.
2//! which may offer a potential boost in performance on some targets by performing the same operations on2//!
3//! multiple elements at once.3//! May offer a potential boost in performance on some targets by performing
4//! Please be aware that some functions are known to not work on MIPS.4//! the same operations on multiple elements at once.
5//!
6//! Some functions are known to not work on MIPS.
57
6const std = @import("std");8const std = @import("std");
7const builtin = @import("builtin");9const builtin = @import("builtin");
lib/std/std.zig-93
...@@ -55,149 +55,56 @@ pub const Tz = tz.Tz;...@@ -55,149 +55,56 @@ pub const Tz = tz.Tz;
55pub const Uri = @import("Uri.zig");55pub const Uri = @import("Uri.zig");
5656
57pub const array_hash_map = @import("array_hash_map.zig");57pub const array_hash_map = @import("array_hash_map.zig");
58
59/// Memory ordering, atomic data structures, and operations.
60pub const atomic = @import("atomic.zig");58pub const atomic = @import("atomic.zig");
61
62/// Base64 encoding/decoding.
63pub const base64 = @import("base64.zig");59pub const base64 = @import("base64.zig");
64
65/// Bit manipulation data structures.
66pub const bit_set = @import("bit_set.zig");60pub const bit_set = @import("bit_set.zig");
67
68/// Comptime-available information about the build environment, such as the target and optimize mode.
69pub const builtin = @import("builtin.zig");61pub const builtin = @import("builtin.zig");
70
71pub const c = @import("c.zig");62pub const c = @import("c.zig");
72
73/// COFF format.
74pub const coff = @import("coff.zig");63pub const coff = @import("coff.zig");
75
76/// Compression algorithms such as zlib, zstd, etc.
77pub const compress = @import("compress.zig");64pub const compress = @import("compress.zig");
78
79pub const comptime_string_map = @import("comptime_string_map.zig");65pub const comptime_string_map = @import("comptime_string_map.zig");
80
81/// Cryptography.
82pub const crypto = @import("crypto.zig");66pub const crypto = @import("crypto.zig");
83
84/// Debug printing, allocation and other debug helpers.
85pub const debug = @import("debug.zig");67pub const debug = @import("debug.zig");
86
87/// DWARF debugging data format.
88pub const dwarf = @import("dwarf.zig");68pub const dwarf = @import("dwarf.zig");
89
90/// ELF format.
91pub const elf = @import("elf.zig");69pub const elf = @import("elf.zig");
92
93/// Enum-related metaprogramming helpers.
94pub const enums = @import("enums.zig");70pub const enums = @import("enums.zig");
95
96/// First in, first out data structures.
97pub const fifo = @import("fifo.zig");71pub const fifo = @import("fifo.zig");
98
99/// String formatting and parsing (e.g. parsing numbers out of strings).
100pub const fmt = @import("fmt.zig");72pub const fmt = @import("fmt.zig");
101
102/// File system-related functionality.
103pub const fs = @import("fs.zig");73pub const fs = @import("fs.zig");
104
105/// GPU programming helpers.
106pub const gpu = @import("gpu.zig");74pub const gpu = @import("gpu.zig");
107
108/// Fast hashing functions (i.e. not cryptographically secure).
109pub const hash = @import("hash.zig");75pub const hash = @import("hash.zig");
110pub const hash_map = @import("hash_map.zig");76pub const hash_map = @import("hash_map.zig");
111
112/// Allocator implementations.
113pub const heap = @import("heap.zig");77pub const heap = @import("heap.zig");
114
115/// HTTP client and server.
116pub const http = @import("http.zig");78pub const http = @import("http.zig");
117
118/// I/O streams, reader/writer interfaces and common helpers.
119pub const io = @import("io.zig");79pub const io = @import("io.zig");
120
121/// JSON parsing and serialization.
122pub const json = @import("json.zig");80pub const json = @import("json.zig");
123
124/// LEB128 encoding.
125pub const leb = @import("leb128.zig");81pub const leb = @import("leb128.zig");
126
127/// A standardized interface for logging.
128pub const log = @import("log.zig");82pub const log = @import("log.zig");
129
130/// Mach-O format.
131pub const macho = @import("macho.zig");83pub const macho = @import("macho.zig");
132
133/// Mathematical constants and operations.
134pub const math = @import("math.zig");84pub const math = @import("math.zig");
135
136/// Functions for comparing, searching, and manipulating memory.
137pub const mem = @import("mem.zig");85pub const mem = @import("mem.zig");
138
139/// Metaprogramming helpers.
140pub const meta = @import("meta.zig");86pub const meta = @import("meta.zig");
141
142/// Networking.
143pub const net = @import("net.zig");87pub const net = @import("net.zig");
144
145/// POSIX-like API layer.
146pub const posix = @import("os.zig");88pub const posix = @import("os.zig");
147
148/// Non-portable Operating System-specific API.89/// Non-portable Operating System-specific API.
149pub const os = @import("os.zig");90pub const os = @import("os.zig");
150
151pub const once = @import("once.zig").once;91pub const once = @import("once.zig").once;
152
153/// A set of array and slice types that bit-pack integer elements.
154pub const packed_int_array = @import("packed_int_array.zig");92pub const packed_int_array = @import("packed_int_array.zig");
155
156/// PDB file format.
157pub const pdb = @import("pdb.zig");93pub const pdb = @import("pdb.zig");
158
159/// Accessors for process-related info (e.g. command line arguments)
160/// and spawning of child processes.
161pub const process = @import("process.zig");94pub const process = @import("process.zig");
162
163/// Deprecated: use `Random` instead.95/// Deprecated: use `Random` instead.
164pub const rand = Random;96pub const rand = Random;
165
166/// Sorting.
167pub const sort = @import("sort.zig");97pub const sort = @import("sort.zig");
168
169/// Single Instruction Multiple Data (SIMD) helpers.
170pub const simd = @import("simd.zig");98pub const simd = @import("simd.zig");
171
172/// ASCII text processing.
173pub const ascii = @import("ascii.zig");99pub const ascii = @import("ascii.zig");
174
175/// Tar archive format compression/decompression.
176pub const tar = @import("tar.zig");100pub const tar = @import("tar.zig");
177
178/// Testing allocator, testing assertions, and other helpers for testing code.
179pub const testing = @import("testing.zig");101pub const testing = @import("testing.zig");
180
181/// Sleep, obtaining the current time, conversion constants, and more.
182pub const time = @import("time.zig");102pub const time = @import("time.zig");
183
184/// Time zones.
185pub const tz = @import("tz.zig");103pub const tz = @import("tz.zig");
186
187/// UTF-8 and UTF-16LE encoding/decoding.
188pub const unicode = @import("unicode.zig");104pub const unicode = @import("unicode.zig");
189
190/// Helpers for integrating with Valgrind.
191pub const valgrind = @import("valgrind.zig");105pub const valgrind = @import("valgrind.zig");
192
193/// Constants and types representing the Wasm binary format.
194pub const wasm = @import("wasm.zig");106pub const wasm = @import("wasm.zig");
195
196/// Builds of the Zig compiler are distributed partly in source form. That
197/// source lives here. These APIs are provided as-is and have absolutely no API
198/// guarantees whatsoever.
199pub const zig = @import("zig.zig");107pub const zig = @import("zig.zig");
200
201pub const start = @import("start.zig");108pub const start = @import("start.zig");
202109
203const root = @import("root");110const root = @import("root");
lib/std/zig.zig+4
...@@ -1,3 +1,7 @@...@@ -1,3 +1,7 @@
1//! Builds of the Zig compiler are distributed partly in source form. That
2//! source lives here. These APIs are provided as-is and have absolutely no API
3//! guarantees whatsoever.
4
1pub const ErrorBundle = @import("zig/ErrorBundle.zig");5pub const ErrorBundle = @import("zig/ErrorBundle.zig");
2pub const Server = @import("zig/Server.zig");6pub const Server = @import("zig/Server.zig");
3pub const Client = @import("zig/Client.zig");7pub const Client = @import("zig/Client.zig");