Commit c45af2af61

@@ -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;
 

@@ -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 {

@@ -969,21 +969,21 @@ pub const Loop = struct {
         /// This argument is a socket that has been created with `socket`, bound to a local address
         /// with `bind`, and is listening for connections after a `listen`.
         sockfd: os.socket_t,
-        /// This argument is a pointer to a sockaddr structure.  This structure is filled in with  the
-        /// address  of  the  peer  socket, as known to the communications layer.  The exact format of the
-        /// address returned addr is determined by the socket's address  family  (see  `socket`  and  the
-        /// respective  protocol  man  pages).
+        /// This argument is a pointer to a sockaddr structure.  This structure is filled in with the
+        /// address of the peer socket, as known to the communications layer.  The exact format of the
+        /// address returned addr is determined by the socket's address family (see `socket` and the
+        /// respective protocol man pages).
         addr: *os.sockaddr,
-        /// This argument is a value-result argument: the caller must initialize it to contain  the
+        /// This argument is a value-result argument: the caller must initialize it to contain the
         /// size (in bytes) of the structure pointed to by addr; on return it will contain the actual size
         /// of the peer address.
         ///
-        /// The returned address is truncated if the buffer provided is too small; in this  case,  `addr_size`
+        /// The returned address is truncated if the buffer provided is too small; in this case, `addr_size`
         /// will return a value greater than was supplied to the call.
         addr_size: *os.socklen_t,
         /// The following values can be bitwise ORed in flags to obtain different behavior:
-        /// * `SOCK.CLOEXEC`  - Set the close-on-exec (`FD_CLOEXEC`) flag on the new file descriptor.   See  the
-        ///   description  of the `O.CLOEXEC` flag in `open` for reasons why this may be useful.
+        /// * `SOCK.CLOEXEC` - Set the close-on-exec (`FD_CLOEXEC`) flag on the new file descriptor. See the
+        ///   description of the `O.CLOEXEC` flag in `open` for reasons why this may be useful.
         flags: u32,
     ) os.AcceptError!os.socket_t {
         while (true) {

@@ -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;

@@ -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();

@@ -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 };

@@ -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

@@ -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);
     }

@@ -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;
 //!

@@ -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,

@@ -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;

@@ -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 {

@@ -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");

@@ -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 {

@@ -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);

@@ -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);

@@ -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();

@@ -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.

@@ -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) {

@@ -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 {

@@ -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);
 }

@@ -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,