Fix simple doc mistakes. (#17624)

* Add missing period in Stack's description

This looks fine in the source, but looks bad when seen on the documentation website.

* Correct documentation for attachSegfaultHandler()

The description for attachSegfaultHandler() looks pretty bad without indicating that the stuff at the end is code

* Added missing 'the's in Queue.put's documentation

* Fixed several errors in Stack's documentation

`push()` and `pop()` were not styled as code

There was no period after `pop()`, which looks bad on the documentation.

* Fix multiple problems in base64.zig

Both "invalid"s in Base64.decoder were not capitalized.

Missing period in documentation of Base64DecoderWithIgnore.calcSizeUpperBound.

* Fix capitalization typos in bit_set.zig

In DynamicBitSetUnmanaged.deinit's and DynamicBitSet.deinit's documentation, "deinitializes" was uncapitalized.

* Fix typos in fifo.zig's documentation

Added a previously missing period to the end of the first line of LinearFifo.writableSlice's documentation.
Added missing periods to both lines of LinearFifo.pump's documentation.

* Fix typos in fmt.bufPrint's documentation

The starts of both lines were not capitalized.

* Fix minor documentation problems in fs/file.zig

Missing periods in documentation for Permissions.setReadOnly, PermissionsWindows.setReadOnly, MetadataUnix.created, MetadataLinux.created, and MetadataWindows.created.

* Fix a glaring typo in enums.zig

* Correct errors in fs.zig

* Fixed documentation problems in hash_map.zig

The added empty line in verify_context's documentation is needed, otherwise autodoc for some reason assumes that the list hasn't been terminated and continues reading off the rest of the documentation as if it were part of the second list item.

* Added lines between consecutive URLs in http.zig

Makes the documentation conform closer to what was intended.

* Fix wrongfully ended sentence in Uri.zig

* Handle wrongly entered comma in valgrind.zig.

* Add missing periods in wasm.zig's documentation

* Fix odd spacing in event/loop.zig

* Add missing period in http/Headers.zig

* Added missing period in io/limited_reader.zig

This isn't in the documentation due to what I guess is a limitation of autodoc, but it's clearly supposed to be. If it was, it would look pretty bad.

* Correct documentation in math/big/int.zig

* Correct formatting in math/big/rational.zig

* Create an actual link to ZIGNOR's paper.

* Fixed grammatical issues in sort/block.zig

This will not show up in the documentation currently.

* Fix typo in hash_map.zig

lib/std/Uri.zig

@@ -129,7 +129,7 @@ pub fn unescapeString(allocator: std.mem.Allocator, input: []const u8) error{Out
 pub const ParseError = error{ UnexpectedCharacter, InvalidFormat, InvalidPort };
 
 /// Parses the URI or returns an error. This function is not compliant, but is required to parse
-/// some forms of URIs in the wild. Such as HTTP Location headers.
+/// some forms of URIs in the wild, such as HTTP Location headers.
 /// The return value will contain unescaped strings pointing into the
 /// original `text`. Each component that is provided, will be non-`null`.
 pub fn parseWithoutScheme(text: []const u8) ParseError!Uri {

lib/std/atomic/queue.zig

@@ -27,7 +27,7 @@ pub fn Queue(comptime T: type) type {
         }
 
         /// Appends `node` to the queue.
-        /// The lifetime of `node` must be longer than lifetime of queue.
+        /// The lifetime of `node` must be longer than the lifetime of the queue.
         pub fn put(self: *Self, node: *Node) void {
             node.next = null;
 

lib/std/atomic/stack.zig

@@ -3,8 +3,8 @@ const builtin = @import("builtin");
 const assert = std.debug.assert;
 const expect = std.testing.expect;
 
-/// Many reader, many writer, non-allocating, thread-safe
-/// Uses a spinlock to protect push() and pop()
+/// Many reader, many writer, non-allocating, thread-safe.
+/// Uses a spinlock to protect `push()` and `pop()`.
 /// When building in single threaded mode, this is a simple linked list.
 pub fn Stack(comptime T: type) type {
     return struct {

lib/std/base64.zig

@@ -203,8 +203,8 @@ pub const Base64Decoder = struct {
     }
 
     /// dest.len must be what you get from ::calcSize.
-    /// invalid characters result in error.InvalidCharacter.
-    /// invalid padding results in error.InvalidPadding.
+    /// Invalid characters result in `error.InvalidCharacter`.
+    /// Invalid padding results in `error.InvalidPadding`.
     pub fn decode(decoder: *const Base64Decoder, dest: []u8, source: []const u8) Error!void {
         if (decoder.pad_char != null and source.len % 4 != 0) return error.InvalidPadding;
         var dest_idx: usize = 0;
@@ -291,7 +291,7 @@ pub const Base64DecoderWithIgnore = struct {
         return result;
     }
 
-    /// Return the maximum possible decoded size for a given input length - The actual length may be less if the input includes padding
+    /// Return the maximum possible decoded size for a given input length - The actual length may be less if the input includes padding.
     /// `InvalidPadding` is returned if the input length is not valid.
     pub fn calcSizeUpperBound(decoder_with_ignore: *const Base64DecoderWithIgnore, source_len: usize) Error!usize {
         var result = source_len / 4 * 3;

lib/std/bit_set.zig

@@ -753,7 +753,7 @@ pub const DynamicBitSetUnmanaged = struct {
         self.bit_length = new_len;
     }
 
-    /// deinitializes the array and releases its memory.
+    /// Deinitializes the array and releases its memory.
     /// The passed allocator must be the same one used for
     /// init* or resize in the past.
     pub fn deinit(self: *Self, allocator: Allocator) void {
@@ -1058,7 +1058,7 @@ pub const DynamicBitSet = struct {
         try self.unmanaged.resize(self.allocator, new_len, fill);
     }
 
-    /// deinitializes the array and releases its memory.
+    /// Deinitializes the array and releases its memory.
     /// The passed allocator must be the same one used for
     /// init* or resize in the past.
     pub fn deinit(self: *Self) void {

lib/std/debug.zig

@@ -2340,7 +2340,7 @@ pub fn updateSegfaultHandler(act: ?*const os.Sigaction) error{OperationNotSuppor
     try os.sigaction(os.SIG.FPE, act, null);
 }
 
-/// Attaches a global SIGSEGV handler which calls @panic("segmentation fault");
+/// Attaches a global SIGSEGV handler which calls `@panic("segmentation fault");`
 pub fn attachSegfaultHandler() void {
     if (!have_segfault_handling_support) {
         @compileError("segfault handler not supported for this target");

lib/std/enums.zig

@@ -425,7 +425,7 @@ pub fn BoundedEnumMultiset(comptime E: type, comptime CountSize: type) type {
             }
         }
 
-        /// Deccreases the all key counts by given multiset. If
+        /// Decreases the all key counts by given multiset. If
         /// the given multiset has more key counts than this,
         /// then that key will have a key count of zero.
         pub fn removeSet(self: *Self, other: Self) void {

lib/std/fifo.zig

@@ -242,7 +242,7 @@ pub fn LinearFifo(
             return self.buf.len - self.count;
         }
 
-        /// Returns the first section of writable buffer
+        /// Returns the first section of writable buffer.
         /// Note that this may be of length 0
         pub fn writableSlice(self: SliceSelfArg, offset: usize) []T {
             if (offset > self.buf.len) return &[_]T{};
@@ -371,8 +371,8 @@ pub fn LinearFifo(
             return self.buf[index];
         }
 
-        /// Pump data from a reader into a writer
-        /// stops when reader returns 0 bytes (EOF)
+        /// Pump data from a reader into a writer.
+        /// Stops when reader returns 0 bytes (EOF).
         /// Buffer size must be set before calling; a buffer length of 0 is invalid.
         pub fn pump(self: *Self, src_reader: anytype, dest_writer: anytype) !void {
             assert(self.buf.len > 0);

lib/std/fmt.zig

@@ -1989,8 +1989,8 @@ pub const BufPrintError = error{
     NoSpaceLeft,
 };
 
-/// print a Formatter string into `buf`. Actually just a thin wrapper around `format` and `fixedBufferStream`.
-/// returns a slice of the bytes printed to.
+/// Print a Formatter string into `buf`. Actually just a thin wrapper around `format` and `fixedBufferStream`.
+/// Returns a slice of the bytes printed to.
 pub fn bufPrint(buf: []u8, comptime fmt: []const u8, args: anytype) BufPrintError![]u8 {
     var fbs = std.io.fixedBufferStream(buf);
     try format(fbs.writer(), fmt, args);

lib/std/fs.zig

@@ -204,7 +204,7 @@ pub const AtomicFile = struct {
         }
     }
 
-    /// always call deinit, even after successful finish()
+    /// Always call deinit, even after a successful finish().
     pub fn deinit(self: *AtomicFile) void {
         if (self.file_open) {
             self.file.close();

lib/std/fs/file.zig

@@ -453,7 +453,7 @@ pub const File = struct {
         }
 
         /// Sets whether write permissions are provided.
-        /// On Unix, this affects *all* classes. If this is undesired, use `unixSet`
+        /// On Unix, this affects *all* classes. If this is undesired, use `unixSet`.
         /// This method *DOES NOT* set permissions on the filesystem: use `File.setPermissions(permissions)`
         pub fn setReadOnly(self: *Self, read_only: bool) void {
             self.inner.setReadOnly(read_only);
@@ -493,7 +493,7 @@ pub const File = struct {
         }
 
         /// Sets whether write permissions are provided.
-        /// This affects *all* classes. If this is undesired, use `unixSet`
+        /// This affects *all* classes. If this is undesired, use `unixSet`.
         /// This method *DOES NOT* set permissions on the filesystem: use `File.setPermissions(permissions)`
         pub fn setReadOnly(self: *Self, read_only: bool) void {
             if (read_only) {
@@ -706,7 +706,7 @@ pub const File = struct {
             return @as(i128, mtime.tv_sec) * std.time.ns_per_s + mtime.tv_nsec;
         }
 
-        /// Returns the time the file was created in nanoseconds since UTC 1970-01-01
+        /// Returns the time the file was created in nanoseconds since UTC 1970-01-01.
         /// Returns null if this is not supported by the OS or filesystem
         pub fn created(self: Self) ?i128 {
             if (!@hasDecl(@TypeOf(self.stat), "birthtime")) return null;
@@ -772,7 +772,7 @@ pub const File = struct {
             return @as(i128, self.statx.mtime.tv_sec) * std.time.ns_per_s + self.statx.mtime.tv_nsec;
         }
 
-        /// Returns the time the file was created in nanoseconds since UTC 1970-01-01
+        /// Returns the time the file was created in nanoseconds since UTC 1970-01-01.
         /// Returns null if this is not supported by the filesystem, or on kernels before than version 4.11
         pub fn created(self: Self) ?i128 {
             if (self.statx.mask & os.linux.STATX_BTIME == 0) return null;
@@ -825,7 +825,7 @@ pub const File = struct {
             return self.modified_time;
         }
 
-        /// Returns the time the file was created in nanoseconds since UTC 1970-01-01
+        /// Returns the time the file was created in nanoseconds since UTC 1970-01-01.
         /// This never returns null, only returning an optional for compatibility with other OSes
         pub fn created(self: Self) ?i128 {
             return self.creation_time;

lib/std/hash_map.zig

@@ -126,6 +126,7 @@ pub const default_max_load_percentage = 80;
 /// member functions:
 ///   - hash(self, PseudoKey) Hash
 ///   - eql(self, PseudoKey, Key) bool
+///
 /// If you are passing a context to a *Adapted function, PseudoKey is the type
 /// of the key parameter.  Otherwise, when creating a HashMap or HashMapUnmanaged
 /// type, PseudoKey = Key = K.
@@ -469,7 +470,7 @@ pub fn HashMap(
         }
 
         /// If key exists this function cannot fail.
-        /// If there is an existing item with `key`, then the result
+        /// If there is an existing item with `key`, then the result's
         /// `Entry` pointers point to it, and found_existing is true.
         /// Otherwise, puts a new item with undefined value, and
         /// the `Entry` pointers point to it. Caller should then initialize
@@ -479,7 +480,7 @@ pub fn HashMap(
         }
 
         /// If key exists this function cannot fail.
-        /// If there is an existing item with `key`, then the result
+        /// If there is an existing item with `key`, then the result's
         /// `Entry` pointers point to it, and found_existing is true.
         /// Otherwise, puts a new item with undefined key and value, and
         /// the `Entry` pointers point to it. Caller must then initialize
@@ -488,7 +489,7 @@ pub fn HashMap(
             return self.unmanaged.getOrPutContextAdapted(self.allocator, key, ctx, self.ctx);
         }
 
-        /// If there is an existing item with `key`, then the result
+        /// If there is an existing item with `key`, then the result's
         /// `Entry` pointers point to it, and found_existing is true.
         /// Otherwise, puts a new item with undefined value, and
         /// the `Entry` pointers point to it. Caller should then initialize
@@ -499,7 +500,7 @@ pub fn HashMap(
             return self.unmanaged.getOrPutAssumeCapacityContext(key, self.ctx);
         }
 
-        /// If there is an existing item with `key`, then the result
+        /// If there is an existing item with `key`, then the result's
         /// `Entry` pointers point to it, and found_existing is true.
         /// Otherwise, puts a new item with undefined value, and
         /// the `Entry` pointers point to it. Caller must then initialize
@@ -565,7 +566,7 @@ pub fn HashMap(
         }
 
         /// Inserts a new `Entry` into the hash map, returning the previous one, if any.
-        /// If insertion happuns, asserts there is enough capacity without allocating.
+        /// If insertion happens, asserts there is enough capacity without allocating.
         pub fn fetchPutAssumeCapacity(self: *Self, key: K, value: V) ?KV {
             return self.unmanaged.fetchPutAssumeCapacityContext(key, value, self.ctx);
         }
@@ -684,7 +685,7 @@ pub fn HashMap(
 }
 
 /// A HashMap based on open addressing and linear probing.
-/// A lookup or modification typically occurs only 2 cache misses.
+/// A lookup or modification typically incurs only 2 cache misses.
 /// No order is guaranteed and any modification invalidates live iterators.
 /// It achieves good performance with quite high load factors (by default,
 /// grow is triggered at 80% full) and only one byte of overhead per element.

lib/std/http.zig

@@ -14,7 +14,9 @@ pub const Version = enum {
 };
 
 /// https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
+///
 /// https://datatracker.ietf.org/doc/html/rfc7231#section-4 Initial definition
+///
 /// https://datatracker.ietf.org/doc/html/rfc5789#section-2 PATCH
 pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is supported by the C backend, and therefore cannot pass CI
     GET = parse("GET"),
@@ -68,7 +70,9 @@ pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is s
     }
 
     /// An HTTP method is safe if it doesn't alter the state of the server.
+    ///
     /// https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP
+    ///
     /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.1
     pub fn safe(self: Method) bool {
         return switch (self) {
@@ -79,7 +83,9 @@ pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is s
     }
 
     /// An HTTP method is idempotent if an identical request can be made once or several times in a row with the same effect while leaving the server in the same state.
+    ///
     /// https://developer.mozilla.org/en-US/docs/Glossary/Idempotent
+    ///
     /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2
     pub fn idempotent(self: Method) bool {
         return switch (self) {
@@ -90,7 +96,9 @@ pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is s
     }
 
     /// A cacheable response is an HTTP response that can be cached, that is stored to be retrieved and used later, saving a new request to the server.
+    ///
     /// https://developer.mozilla.org/en-US/docs/Glossary/cacheable
+    ///
     /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.3
     pub fn cacheable(self: Method) bool {
         return switch (self) {

lib/std/http/Headers.zig

@@ -249,7 +249,7 @@ pub const Headers = struct {
         try out_stream.writeAll("\r\n");
     }
 
-    /// Frees all `HeaderIndexList`s within `index`
+    /// Frees all `HeaderIndexList`s within `index`.
     /// Frees names and values of all fields if they are owned.
     fn deallocateIndexListsAndFields(headers: *Headers) void {
         var it = headers.index.iterator();

lib/std/io/limited_reader.zig

@@ -26,7 +26,7 @@ pub fn LimitedReader(comptime ReaderType: type) type {
     };
 }
 
-/// Returns an initialised `LimitedReader`
+/// Returns an initialised `LimitedReader`.
 /// `bytes_left` is a `u64` to be able to take 64 bit file offsets
 pub fn limitedReader(inner_reader: anytype, bytes_left: u64) LimitedReader(@TypeOf(inner_reader)) {
     return .{ .inner_reader = inner_reader, .bytes_left = bytes_left };

lib/std/math/big/int.zig

@@ -452,6 +452,7 @@ pub const Mutable = struct {
     }
 
     /// r = a + b
+    ///
     /// r, a and b may be aliases.
     ///
     /// Asserts the result fits in `r`. An upper bound on the number of limbs needed by
@@ -1869,7 +1870,7 @@ pub const Mutable = struct {
         }
     }
 
-    /// Read the value of `x` from `buffer`
+    /// Read the value of `x` from `buffer`.
     /// Asserts that `buffer` is large enough to contain a value of bit-size `bit_count`.
     ///
     /// The contents of `buffer` are interpreted as if they were the contents of

lib/std/math/big/rational.zig

@@ -333,8 +333,8 @@ pub const Rational = struct {
         r.q.swap(&other.q);
     }
 
-    /// Returns math.Order.lt, math.Order.eq, math.Order.gt if a < b, a == b or a
-    /// > b respectively.
+    /// Returns math.Order.lt, math.Order.eq, math.Order.gt if a < b, a == b or
+    /// a > b respectively.
     pub fn order(a: Rational, b: Rational) !math.Order {
         return cmpInternal(a, b, false);
     }

lib/std/rand/ziggurat.zig

@@ -1,7 +1,6 @@
-//! Implements ZIGNOR [1].
+//! Implements [ZIGNOR][1] (Jurgen A. Doornik, 2005, Nuffield College, Oxford).
 //!
-//! [1]: Jurgen A. Doornik (2005). [*An Improved Ziggurat Method to Generate Normal Random Samples*]
-//! (https://www.doornik.com/research/ziggurat.pdf). Nuffield College, Oxford.
+//! [1]: https://www.doornik.com/research/ziggurat.pdf
 //!
 //! rust/rand used as a reference;
 //!

lib/std/sort/block.zig

@@ -95,7 +95,7 @@ const Pull = struct {
 /// O(1) memory (no allocator required).
 /// Sorts in ascending order with respect to the given `lessThan` function.
 ///
-/// NOTE: the algorithm only work when the comparison is less-than or greater-than
+/// NOTE: The algorithm only works when the comparison is less-than or greater-than.
 ///       (See https://github.com/ziglang/zig/issues/8289)
 pub fn block(
     comptime T: type,

lib/std/valgrind.zig

@@ -250,7 +250,7 @@ pub fn disableErrorReporting() void {
     doClientRequestStmt(.ChangeErrDisablement, 1, 0, 0, 0, 0);
 }
 
-/// Re-enable error reporting, (see disableErrorReporting())
+/// Re-enable error reporting. (see disableErrorReporting())
 pub fn enableErrorReporting() void {
     doClientRequestStmt(.ChangeErrDisablement, math.maxInt(usize), 0, 0, 0, 0);
 }

lib/std/wasm.zig

@@ -216,7 +216,7 @@ test "Wasm - opcodes" {
     try testing.expectEqual(@as(u16, 0xC4), i64_extend32_s);
 }
 
-/// Opcodes that require a prefix `0xFC`
+/// Opcodes that require a prefix `0xFC`.
 /// Each opcode represents a varuint32, meaning
 /// they are encoded as leb128 in binary.
 pub const MiscOpcode = enum(u32) {
@@ -793,7 +793,7 @@ pub fn section(val: Section) u8 {
     return @intFromEnum(val);
 }
 
-/// The kind of the type when importing or exporting to/from the host environment
+/// The kind of the type when importing or exporting to/from the host environment.
 /// https://webassembly.github.io/spec/core/syntax/modules.html
 pub const ExternalKind = enum(u8) {
     function,