From aa852f737b7504e01d0a4cd08c115ae508bb81c7 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
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 ce84e640d1..2627480295 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 fc85d32d52..3339a5337e 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 a6d0a40b26..200489c18a 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 c548f01c07..fe6e96c2dd 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 2544f35c42..aeeff5f41d 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 e40c215e83..bdb84f5171 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 262d51bcee..3594516287 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 6eba6fcb92..c9294e727a 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 66b90867c6..e68adc4207 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 c3ae2d8dbe..7fe9b839cc 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 0781c877cf..557b320c24 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 46fb562310..c887030ae6 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");