authorgravatar for justintwayland+github@gmail.comJustinWayland <justintwayland+github@gmail.com> 2023-10-21 17:24:55-04:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2023-10-21 21:24:55+00:00
logc45af2af6168c7a3cf1bf9e50f6fc1a95b486ce8
treee927642afcc7cf78164901040acdd82d6a0eba15
parent3f4df8529924618ab9febb9ccaa3fa854792ec56
signaturebadge-question-mark Signed by PGP key 4AEE18F83AFDEB23

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

22 files changed, 57 insertions(+), 48 deletions(-)

lib/std/Uri.zig+1-1
......@@ -129,7 +129,7 @@ pub fn unescapeString(allocator: std.mem.Allocator, input: []const u8) error{Out
129129pub const ParseError = error{ UnexpectedCharacter, InvalidFormat, InvalidPort };
130130
131131/// Parses the URI or returns an error. This function is not compliant, but is required to parse
132/// some forms of URIs in the wild. Such as HTTP Location headers.
132/// some forms of URIs in the wild, such as HTTP Location headers.
133133/// The return value will contain unescaped strings pointing into the
134134/// original `text`. Each component that is provided, will be non-`null`.
135135pub fn parseWithoutScheme(text: []const u8) ParseError!Uri {
lib/std/atomic/queue.zig+1-1
......@@ -27,7 +27,7 @@ pub fn Queue(comptime T: type) type {
2727 }
2828
2929 /// Appends `node` to the queue.
30 /// The lifetime of `node` must be longer than lifetime of queue.
30 /// The lifetime of `node` must be longer than the lifetime of the queue.
3131 pub fn put(self: *Self, node: *Node) void {
3232 node.next = null;
3333
lib/std/atomic/stack.zig+2-2
......@@ -3,8 +3,8 @@ const builtin = @import("builtin");
33const assert = std.debug.assert;
44const expect = std.testing.expect;
55
6/// Many reader, many writer, non-allocating, thread-safe
7/// Uses a spinlock to protect push() and pop()
6/// Many reader, many writer, non-allocating, thread-safe.
7/// Uses a spinlock to protect `push()` and `pop()`.
88/// When building in single threaded mode, this is a simple linked list.
99pub fn Stack(comptime T: type) type {
1010 return struct {
lib/std/base64.zig+3-3
......@@ -203,8 +203,8 @@ pub const Base64Decoder = struct {
203203 }
204204
205205 /// dest.len must be what you get from ::calcSize.
206 /// invalid characters result in error.InvalidCharacter.
207 /// invalid padding results in error.InvalidPadding.
206 /// Invalid characters result in `error.InvalidCharacter`.
207 /// Invalid padding results in `error.InvalidPadding`.
208208 pub fn decode(decoder: *const Base64Decoder, dest: []u8, source: []const u8) Error!void {
209209 if (decoder.pad_char != null and source.len % 4 != 0) return error.InvalidPadding;
210210 var dest_idx: usize = 0;
......@@ -291,7 +291,7 @@ pub const Base64DecoderWithIgnore = struct {
291291 return result;
292292 }
293293
294 /// Return the maximum possible decoded size for a given input length - The actual length may be less if the input includes padding
294 /// Return the maximum possible decoded size for a given input length - The actual length may be less if the input includes padding.
295295 /// `InvalidPadding` is returned if the input length is not valid.
296296 pub fn calcSizeUpperBound(decoder_with_ignore: *const Base64DecoderWithIgnore, source_len: usize) Error!usize {
297297 var result = source_len / 4 * 3;
lib/std/bit_set.zig+2-2
......@@ -753,7 +753,7 @@ pub const DynamicBitSetUnmanaged = struct {
753753 self.bit_length = new_len;
754754 }
755755
756 /// deinitializes the array and releases its memory.
756 /// Deinitializes the array and releases its memory.
757757 /// The passed allocator must be the same one used for
758758 /// init* or resize in the past.
759759 pub fn deinit(self: *Self, allocator: Allocator) void {
......@@ -1058,7 +1058,7 @@ pub const DynamicBitSet = struct {
10581058 try self.unmanaged.resize(self.allocator, new_len, fill);
10591059 }
10601060
1061 /// deinitializes the array and releases its memory.
1061 /// Deinitializes the array and releases its memory.
10621062 /// The passed allocator must be the same one used for
10631063 /// init* or resize in the past.
10641064 pub fn deinit(self: *Self) void {
lib/std/debug.zig+1-1
......@@ -2340,7 +2340,7 @@ pub fn updateSegfaultHandler(act: ?*const os.Sigaction) error{OperationNotSuppor
23402340 try os.sigaction(os.SIG.FPE, act, null);
23412341}
23422342
2343/// Attaches a global SIGSEGV handler which calls @panic("segmentation fault");
2343/// Attaches a global SIGSEGV handler which calls `@panic("segmentation fault");`
23442344pub fn attachSegfaultHandler() void {
23452345 if (!have_segfault_handling_support) {
23462346 @compileError("segfault handler not supported for this target");
lib/std/enums.zig+1-1
......@@ -425,7 +425,7 @@ pub fn BoundedEnumMultiset(comptime E: type, comptime CountSize: type) type {
425425 }
426426 }
427427
428 /// Deccreases the all key counts by given multiset. If
428 /// Decreases the all key counts by given multiset. If
429429 /// the given multiset has more key counts than this,
430430 /// then that key will have a key count of zero.
431431 pub fn removeSet(self: *Self, other: Self) void {
lib/std/event/loop.zig+8-8
......@@ -969,21 +969,21 @@ pub const Loop = struct {
969969 /// This argument is a socket that has been created with `socket`, bound to a local address
970970 /// with `bind`, and is listening for connections after a `listen`.
971971 sockfd: os.socket_t,
972 /// This argument is a pointer to a sockaddr structure. This structure is filled in with the
973 /// address of the peer socket, as known to the communications layer. The exact format of the
974 /// address returned addr is determined by the socket's address family (see `socket` and the
975 /// respective protocol man pages).
972 /// This argument is a pointer to a sockaddr structure. This structure is filled in with the
973 /// address of the peer socket, as known to the communications layer. The exact format of the
974 /// address returned addr is determined by the socket's address family (see `socket` and the
975 /// respective protocol man pages).
976976 addr: *os.sockaddr,
977 /// This argument is a value-result argument: the caller must initialize it to contain the
977 /// This argument is a value-result argument: the caller must initialize it to contain the
978978 /// size (in bytes) of the structure pointed to by addr; on return it will contain the actual size
979979 /// of the peer address.
980980 ///
981 /// The returned address is truncated if the buffer provided is too small; in this case, `addr_size`
981 /// The returned address is truncated if the buffer provided is too small; in this case, `addr_size`
982982 /// will return a value greater than was supplied to the call.
983983 addr_size: *os.socklen_t,
984984 /// The following values can be bitwise ORed in flags to obtain different behavior:
985 /// * `SOCK.CLOEXEC` - Set the close-on-exec (`FD_CLOEXEC`) flag on the new file descriptor. See the
986 /// description of the `O.CLOEXEC` flag in `open` for reasons why this may be useful.
985 /// * `SOCK.CLOEXEC` - Set the close-on-exec (`FD_CLOEXEC`) flag on the new file descriptor. See the
986 /// description of the `O.CLOEXEC` flag in `open` for reasons why this may be useful.
987987 flags: u32,
988988 ) os.AcceptError!os.socket_t {
989989 while (true) {
lib/std/fifo.zig+3-3
......@@ -242,7 +242,7 @@ pub fn LinearFifo(
242242 return self.buf.len - self.count;
243243 }
244244
245 /// Returns the first section of writable buffer
245 /// Returns the first section of writable buffer.
246246 /// Note that this may be of length 0
247247 pub fn writableSlice(self: SliceSelfArg, offset: usize) []T {
248248 if (offset > self.buf.len) return &[_]T{};
......@@ -371,8 +371,8 @@ pub fn LinearFifo(
371371 return self.buf[index];
372372 }
373373
374 /// Pump data from a reader into a writer
375 /// stops when reader returns 0 bytes (EOF)
374 /// Pump data from a reader into a writer.
375 /// Stops when reader returns 0 bytes (EOF).
376376 /// Buffer size must be set before calling; a buffer length of 0 is invalid.
377377 pub fn pump(self: *Self, src_reader: anytype, dest_writer: anytype) !void {
378378 assert(self.buf.len > 0);
lib/std/fmt.zig+2-2
......@@ -1989,8 +1989,8 @@ pub const BufPrintError = error{
19891989 NoSpaceLeft,
19901990};
19911991
1992/// print a Formatter string into `buf`. Actually just a thin wrapper around `format` and `fixedBufferStream`.
1993/// returns a slice of the bytes printed to.
1992/// Print a Formatter string into `buf`. Actually just a thin wrapper around `format` and `fixedBufferStream`.
1993/// Returns a slice of the bytes printed to.
19941994pub fn bufPrint(buf: []u8, comptime fmt: []const u8, args: anytype) BufPrintError![]u8 {
19951995 var fbs = std.io.fixedBufferStream(buf);
19961996 try format(fbs.writer(), fmt, args);
lib/std/fs.zig+1-1
......@@ -204,7 +204,7 @@ pub const AtomicFile = struct {
204204 }
205205 }
206206
207 /// always call deinit, even after successful finish()
207 /// Always call deinit, even after a successful finish().
208208 pub fn deinit(self: *AtomicFile) void {
209209 if (self.file_open) {
210210 self.file.close();
lib/std/fs/file.zig+5-5
......@@ -453,7 +453,7 @@ pub const File = struct {
453453 }
454454
455455 /// Sets whether write permissions are provided.
456 /// On Unix, this affects *all* classes. If this is undesired, use `unixSet`
456 /// On Unix, this affects *all* classes. If this is undesired, use `unixSet`.
457457 /// This method *DOES NOT* set permissions on the filesystem: use `File.setPermissions(permissions)`
458458 pub fn setReadOnly(self: *Self, read_only: bool) void {
459459 self.inner.setReadOnly(read_only);
......@@ -493,7 +493,7 @@ pub const File = struct {
493493 }
494494
495495 /// Sets whether write permissions are provided.
496 /// This affects *all* classes. If this is undesired, use `unixSet`
496 /// This affects *all* classes. If this is undesired, use `unixSet`.
497497 /// This method *DOES NOT* set permissions on the filesystem: use `File.setPermissions(permissions)`
498498 pub fn setReadOnly(self: *Self, read_only: bool) void {
499499 if (read_only) {
......@@ -706,7 +706,7 @@ pub const File = struct {
706706 return @as(i128, mtime.tv_sec) * std.time.ns_per_s + mtime.tv_nsec;
707707 }
708708
709 /// Returns the time the file was created in nanoseconds since UTC 1970-01-01
709 /// Returns the time the file was created in nanoseconds since UTC 1970-01-01.
710710 /// Returns null if this is not supported by the OS or filesystem
711711 pub fn created(self: Self) ?i128 {
712712 if (!@hasDecl(@TypeOf(self.stat), "birthtime")) return null;
......@@ -772,7 +772,7 @@ pub const File = struct {
772772 return @as(i128, self.statx.mtime.tv_sec) * std.time.ns_per_s + self.statx.mtime.tv_nsec;
773773 }
774774
775 /// Returns the time the file was created in nanoseconds since UTC 1970-01-01
775 /// Returns the time the file was created in nanoseconds since UTC 1970-01-01.
776776 /// Returns null if this is not supported by the filesystem, or on kernels before than version 4.11
777777 pub fn created(self: Self) ?i128 {
778778 if (self.statx.mask & os.linux.STATX_BTIME == 0) return null;
......@@ -825,7 +825,7 @@ pub const File = struct {
825825 return self.modified_time;
826826 }
827827
828 /// Returns the time the file was created in nanoseconds since UTC 1970-01-01
828 /// Returns the time the file was created in nanoseconds since UTC 1970-01-01.
829829 /// This never returns null, only returning an optional for compatibility with other OSes
830830 pub fn created(self: Self) ?i128 {
831831 return self.creation_time;
lib/std/hash_map.zig+7-6
......@@ -126,6 +126,7 @@ pub const default_max_load_percentage = 80;
126126/// member functions:
127127/// - hash(self, PseudoKey) Hash
128128/// - eql(self, PseudoKey, Key) bool
129///
129130/// If you are passing a context to a *Adapted function, PseudoKey is the type
130131/// of the key parameter. Otherwise, when creating a HashMap or HashMapUnmanaged
131132/// type, PseudoKey = Key = K.
......@@ -469,7 +470,7 @@ pub fn HashMap(
469470 }
470471
471472 /// If key exists this function cannot fail.
472 /// If there is an existing item with `key`, then the result
473 /// If there is an existing item with `key`, then the result's
473474 /// `Entry` pointers point to it, and found_existing is true.
474475 /// Otherwise, puts a new item with undefined value, and
475476 /// the `Entry` pointers point to it. Caller should then initialize
......@@ -479,7 +480,7 @@ pub fn HashMap(
479480 }
480481
481482 /// If key exists this function cannot fail.
482 /// If there is an existing item with `key`, then the result
483 /// If there is an existing item with `key`, then the result's
483484 /// `Entry` pointers point to it, and found_existing is true.
484485 /// Otherwise, puts a new item with undefined key and value, and
485486 /// the `Entry` pointers point to it. Caller must then initialize
......@@ -488,7 +489,7 @@ pub fn HashMap(
488489 return self.unmanaged.getOrPutContextAdapted(self.allocator, key, ctx, self.ctx);
489490 }
490491
491 /// If there is an existing item with `key`, then the result
492 /// If there is an existing item with `key`, then the result's
492493 /// `Entry` pointers point to it, and found_existing is true.
493494 /// Otherwise, puts a new item with undefined value, and
494495 /// the `Entry` pointers point to it. Caller should then initialize
......@@ -499,7 +500,7 @@ pub fn HashMap(
499500 return self.unmanaged.getOrPutAssumeCapacityContext(key, self.ctx);
500501 }
501502
502 /// If there is an existing item with `key`, then the result
503 /// If there is an existing item with `key`, then the result's
503504 /// `Entry` pointers point to it, and found_existing is true.
504505 /// Otherwise, puts a new item with undefined value, and
505506 /// the `Entry` pointers point to it. Caller must then initialize
......@@ -565,7 +566,7 @@ pub fn HashMap(
565566 }
566567
567568 /// Inserts a new `Entry` into the hash map, returning the previous one, if any.
568 /// If insertion happuns, asserts there is enough capacity without allocating.
569 /// If insertion happens, asserts there is enough capacity without allocating.
569570 pub fn fetchPutAssumeCapacity(self: *Self, key: K, value: V) ?KV {
570571 return self.unmanaged.fetchPutAssumeCapacityContext(key, value, self.ctx);
571572 }
......@@ -684,7 +685,7 @@ pub fn HashMap(
684685}
685686
686687/// A HashMap based on open addressing and linear probing.
687/// A lookup or modification typically occurs only 2 cache misses.
688/// A lookup or modification typically incurs only 2 cache misses.
688689/// No order is guaranteed and any modification invalidates live iterators.
689690/// It achieves good performance with quite high load factors (by default,
690691/// grow is triggered at 80% full) and only one byte of overhead per element.
lib/std/http.zig+8
......@@ -14,7 +14,9 @@ pub const Version = enum {
1414};
1515
1616/// https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
17///
1718/// https://datatracker.ietf.org/doc/html/rfc7231#section-4 Initial definition
19///
1820/// https://datatracker.ietf.org/doc/html/rfc5789#section-2 PATCH
1921pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is supported by the C backend, and therefore cannot pass CI
2022 GET = parse("GET"),
......@@ -68,7 +70,9 @@ pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is s
6870 }
6971
7072 /// An HTTP method is safe if it doesn't alter the state of the server.
73 ///
7174 /// https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP
75 ///
7276 /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.1
7377 pub fn safe(self: Method) bool {
7478 return switch (self) {
......@@ -79,7 +83,9 @@ pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is s
7983 }
8084
8185 /// 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.
86 ///
8287 /// https://developer.mozilla.org/en-US/docs/Glossary/Idempotent
88 ///
8389 /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2
8490 pub fn idempotent(self: Method) bool {
8591 return switch (self) {
......@@ -90,7 +96,9 @@ pub const Method = enum(u64) { // TODO: should be u192 or u256, but neither is s
9096 }
9197
9298 /// 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.
99 ///
93100 /// https://developer.mozilla.org/en-US/docs/Glossary/cacheable
101 ///
94102 /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.3
95103 pub fn cacheable(self: Method) bool {
96104 return switch (self) {
lib/std/http/Headers.zig+1-1
......@@ -249,7 +249,7 @@ pub const Headers = struct {
249249 try out_stream.writeAll("\r\n");
250250 }
251251
252 /// Frees all `HeaderIndexList`s within `index`
252 /// Frees all `HeaderIndexList`s within `index`.
253253 /// Frees names and values of all fields if they are owned.
254254 fn deallocateIndexListsAndFields(headers: *Headers) void {
255255 var it = headers.index.iterator();
lib/std/io/limited_reader.zig+1-1
......@@ -26,7 +26,7 @@ pub fn LimitedReader(comptime ReaderType: type) type {
2626 };
2727}
2828
29/// Returns an initialised `LimitedReader`
29/// Returns an initialised `LimitedReader`.
3030/// `bytes_left` is a `u64` to be able to take 64 bit file offsets
3131pub fn limitedReader(inner_reader: anytype, bytes_left: u64) LimitedReader(@TypeOf(inner_reader)) {
3232 return .{ .inner_reader = inner_reader, .bytes_left = bytes_left };
lib/std/math/big/int.zig+2-1
......@@ -452,6 +452,7 @@ pub const Mutable = struct {
452452 }
453453
454454 /// r = a + b
455 ///
455456 /// r, a and b may be aliases.
456457 ///
457458 /// Asserts the result fits in `r`. An upper bound on the number of limbs needed by
......@@ -1869,7 +1870,7 @@ pub const Mutable = struct {
18691870 }
18701871 }
18711872
1872 /// Read the value of `x` from `buffer`
1873 /// Read the value of `x` from `buffer`.
18731874 /// Asserts that `buffer` is large enough to contain a value of bit-size `bit_count`.
18741875 ///
18751876 /// The contents of `buffer` are interpreted as if they were the contents of
lib/std/math/big/rational.zig+2-2
......@@ -333,8 +333,8 @@ pub const Rational = struct {
333333 r.q.swap(&other.q);
334334 }
335335
336 /// Returns math.Order.lt, math.Order.eq, math.Order.gt if a < b, a == b or a
337 /// > b respectively.
336 /// Returns math.Order.lt, math.Order.eq, math.Order.gt if a < b, a == b or
337 /// a > b respectively.
338338 pub fn order(a: Rational, b: Rational) !math.Order {
339339 return cmpInternal(a, b, false);
340340 }
lib/std/rand/ziggurat.zig+2-3
......@@ -1,7 +1,6 @@
1//! Implements ZIGNOR [1].
1//! Implements [ZIGNOR][1] (Jurgen A. Doornik, 2005, Nuffield College, Oxford).
22//!
3//! [1]: Jurgen A. Doornik (2005). [*An Improved Ziggurat Method to Generate Normal Random Samples*]
4//! (https://www.doornik.com/research/ziggurat.pdf). Nuffield College, Oxford.
3//! [1]: https://www.doornik.com/research/ziggurat.pdf
54//!
65//! rust/rand used as a reference;
76//!
lib/std/sort/block.zig+1-1
......@@ -95,7 +95,7 @@ const Pull = struct {
9595/// O(1) memory (no allocator required).
9696/// Sorts in ascending order with respect to the given `lessThan` function.
9797///
98/// NOTE: the algorithm only work when the comparison is less-than or greater-than
98/// NOTE: The algorithm only works when the comparison is less-than or greater-than.
9999/// (See https://github.com/ziglang/zig/issues/8289)
100100pub fn block(
101101 comptime T: type,
lib/std/valgrind.zig+1-1
......@@ -250,7 +250,7 @@ pub fn disableErrorReporting() void {
250250 doClientRequestStmt(.ChangeErrDisablement, 1, 0, 0, 0, 0);
251251}
252252
253/// Re-enable error reporting, (see disableErrorReporting())
253/// Re-enable error reporting. (see disableErrorReporting())
254254pub fn enableErrorReporting() void {
255255 doClientRequestStmt(.ChangeErrDisablement, math.maxInt(usize), 0, 0, 0, 0);
256256}
lib/std/wasm.zig+2-2
......@@ -216,7 +216,7 @@ test "Wasm - opcodes" {
216216 try testing.expectEqual(@as(u16, 0xC4), i64_extend32_s);
217217}
218218
219/// Opcodes that require a prefix `0xFC`
219/// Opcodes that require a prefix `0xFC`.
220220/// Each opcode represents a varuint32, meaning
221221/// they are encoded as leb128 in binary.
222222pub const MiscOpcode = enum(u32) {
......@@ -793,7 +793,7 @@ pub fn section(val: Section) u8 {
793793 return @intFromEnum(val);
794794}
795795
796/// The kind of the type when importing or exporting to/from the host environment
796/// The kind of the type when importing or exporting to/from the host environment.
797797/// https://webassembly.github.io/spec/core/syntax/modules.html
798798pub const ExternalKind = enum(u8) {
799799 function,