docs(bytes): polish documentation (#4594)

bytes/concat.ts

@@ -2,14 +2,17 @@
 // This module is browser compatible.
 
 /**
- * Concatenate an array of {@linkcode Uint8Array}s.
+ * Concatenate an array of byte slices into a single slice.
  *
- * @example
+ * @param buf Array of byte slices to concatenate.
+ *
+ * @example Basic usage
  * ```ts
  * import { concat } from "https://deno.land/std@$STD_VERSION/bytes/concat.ts";
  *
  * const a = new Uint8Array([0, 1, 2]);
  * const b = new Uint8Array([3, 4, 5]);
+ *
  * concat([a, b]); // Uint8Array(6) [ 0, 1, 2, 3, 4, 5 ]
  * ```
  */

bytes/copy.ts

@@ -1,38 +1,48 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Copy bytes from the `src` array to the `dst` array. Returns the number of
+/**
+ * Copy bytes from the `src` array to the `dst` array and returns the number of
  * bytes copied.
  *
  * If the `src` array is larger than what the `dst` array can hold, only the
  * amount of bytes that fit in the `dst` array are copied.
  *
- * An offset can be specified as the third argument that begins the copy at
- * that given index in the `dst` array. The offset defaults to the beginning of
- * the array.
+ * @param src Source array to copy from.
+ * @param dst Destination array to copy to.
+ * @param offset Offset in the destination array to start copying to. Defaults
+ * to 0.
  *
+ * @example Basic usage
  * ```ts
  * import { copy } from "https://deno.land/std@$STD_VERSION/bytes/copy.ts";
+ *
  * const src = new Uint8Array([9, 8, 7]);
  * const dst = new Uint8Array([0, 1, 2, 3, 4, 5]);
- * console.log(copy(src, dst)); // 3
- * console.log(dst); // [9, 8, 7, 3, 4, 5]
+ *
+ * copy(src, dst); // 3
+ * dst; // Uint8Array(6) [9, 8, 7, 3, 4, 5]
  * ```
  *
+ * @example Copy with offset
  * ```ts
  * import { copy } from "https://deno.land/std@$STD_VERSION/bytes/copy.ts";
+ *
  * const src = new Uint8Array([1, 1, 1, 1]);
  * const dst = new Uint8Array([0, 0, 0, 0]);
- * console.log(copy(src, dst, 1)); // 3
- * console.log(dst); // [0, 1, 1, 1]
+ *
+ * copy(src, dst, 1); // 3
+ * dst; // Uint8Array(4) [0, 1, 1, 1]
  * ```
+ * Defining an offset will start copying at the specified index in the
+ * destination array.
  */
-export function copy(src: Uint8Array, dst: Uint8Array, off = 0): number {
-  off = Math.max(0, Math.min(off, dst.byteLength));
-  const dstBytesAvailable = dst.byteLength - off;
+export function copy(src: Uint8Array, dst: Uint8Array, offset = 0): number {
+  offset = Math.max(0, Math.min(offset, dst.byteLength));
+  const dstBytesAvailable = dst.byteLength - offset;
   if (src.byteLength > dstBytesAvailable) {
     src = src.subarray(0, dstBytesAvailable);
   }
-  dst.set(src, off);
+  dst.set(src, offset);
   return src.byteLength;
 }

bytes/ends_with.ts

@@ -1,16 +1,25 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Returns true if the suffix array appears at the end of the source array,
- * false otherwise.
+/**
+ * Returns `true` if the suffix array appears at the end of the source array,
+ * `false` otherwise.
  *
- * The complexity of this function is O(suffix.length).
+ * The complexity of this function is `O(suffix.length)`.
  *
+ * @param source Source array to check.
+ * @param suffix Suffix array to check for.
+ * @returns `true` if the suffix array appears at the end of the source array,
+ * `false` otherwise.
+ *
+ * @example Basic usage
  * ```ts
  * import { endsWith } from "https://deno.land/std@$STD_VERSION/bytes/ends_with.ts";
+ *
  * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
  * const suffix = new Uint8Array([1, 2, 3]);
- * console.log(endsWith(source, suffix)); // true
+ *
+ * endsWith(source, suffix); // true
  * ```
  */
 export function endsWith(source: Uint8Array, suffix: Uint8Array): boolean {

bytes/equals.ts

@@ -1,10 +1,14 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Check whether binary arrays are equal to each other using 8-bit comparisons.
+/**
+ * Check whether byte slices are equal to each other using 8-bit comparisons.
+ *
+ * @param a First array to check equality
+ * @param b Second array to check equality
+ * @returns `true` if the arrays are equal, `false` otherwise
+ *
  * @private
- * @param a first array to check equality
- * @param b second array to check equality
  */
 function equalsNaive(a: Uint8Array, b: Uint8Array): boolean {
   for (let i = 0; i < b.length; i++) {
@@ -13,10 +17,13 @@ function equalsNaive(a: Uint8Array, b: Uint8Array): boolean {
   return true;
 }
 
-/** Check whether binary arrays are equal to each other using 32-bit comparisons.
+/** Check whether byte slices are equal to each other using 32-bit comparisons.
+ *
+ * @param a First array to check equality.
+ * @param b Second array to check equality.
+ * @returns `true` if the arrays are equal, `false` otherwise.
+ *
  * @private
- * @param a first array to check equality
- * @param b second array to check equality
  */
 function equals32Bit(a: Uint8Array, b: Uint8Array): boolean {
   const len = a.length;
@@ -32,9 +39,24 @@ function equals32Bit(a: Uint8Array, b: Uint8Array): boolean {
   return true;
 }
 
-/** Check whether binary arrays are equal to each other.
- * @param a first array to check equality
- * @param b second array to check equality
+/**
+ * Check whether byte slices are equal to each other.
+ *
+ * @param a First array to check equality.
+ * @param b Second array to check equality.
+ * @returns `true` if the arrays are equal, `false` otherwise.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { equals } from "https://deno.land/std@$STD_VERSION/bytes/equals.ts";
+ *
+ * const a = new Uint8Array([1, 2, 3]);
+ * const b = new Uint8Array([1, 2, 3]);
+ * const c = new Uint8Array([4, 5, 6]);
+ *
+ * equals(a, b); // true
+ * equals(b, c); // false
+ * ```
  */
 export function equals(a: Uint8Array, b: Uint8Array): boolean {
   if (a.length !== b.length) {

bytes/includes_needle.ts

@@ -3,20 +3,38 @@
 
 import { indexOfNeedle } from "./index_of_needle.ts";
 
-/** Returns true if the source array contains the needle array, false otherwise.
+/**
+ * Determines whether the source array contains the needle array.
  *
- * A start index can be specified as the third argument that begins the search
- * at that given index. The start index defaults to the beginning of the array.
+ * The complexity of this function is `O(source.length * needle.length)`.
  *
- * The complexity of this function is O(source.length * needle.length).
+ * @param source Source array to check.
+ * @param needle Needle array to check for.
+ * @param start Start index in the source array to begin the search. Defaults to
+ * 0.
+ * @returns `true` if the source array contains the needle array, `false`
+ * otherwise.
  *
+ * @example Basic usage
  * ```ts
  * import { includesNeedle } from "https://deno.land/std@$STD_VERSION/bytes/includes_needle.ts";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * includesNeedle(source, needle); // true
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { includesNeedle } from "https://deno.land/std@$STD_VERSION/bytes/includes_needle.ts";
+ *
  * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
  * const needle = new Uint8Array([1, 2]);
- * console.log(includesNeedle(source, needle)); // true
- * console.log(includesNeedle(source, needle, 6)); // false
+ *
+ * includesNeedle(source, needle, 6); // false
  * ```
+ * The search will start at the specified index in the source array.
  */
 export function includesNeedle(
   source: Uint8Array,

bytes/index_of_needle.ts

@@ -1,21 +1,44 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Returns the index of the first occurrence of the needle array in the source
+/**
+ * Returns the index of the first occurrence of the needle array in the source
  * array, or -1 if it is not present.
  *
  * A start index can be specified as the third argument that begins the search
  * at that given index. The start index defaults to the start of the array.
  *
- * The complexity of this function is O(source.length * needle.length).
+ * The complexity of this function is `O(source.length * needle.length)`.
  *
+ * @param source Source array to check.
+ * @param needle Needle array to check for.
+ * @param start Start index in the source array to begin the search. Defaults to
+ * 0.
+ *
+ * @example Basic usage
  * ```ts
  * import { indexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/index_of_needle.ts";
+ *
  * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
  * const needle = new Uint8Array([1, 2]);
- * console.log(indexOfNeedle(source, needle)); // 1
- * console.log(indexOfNeedle(source, needle, 2)); // 3
+ * const notNeedle = new Uint8Array([5, 0]);
+ *
+ * indexOfNeedle(source, needle); // 1
+ * indexOfNeedle(source, notNeedle); // -1
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { indexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/index_of_needle.ts";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ *
+ * indexOfNeedle(source, needle, 2); // 3
+ * indexOfNeedle(source, needle, 6); // -1
  * ```
+ * Defining a start index will begin the search at the specified index in the
+ * source array.
  */
 export function indexOfNeedle(
   source: Uint8Array,

bytes/last_index_of_needle.ts

@@ -1,21 +1,41 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Returns the index of the last occurrence of the needle array in the source
+/**
+ * Returns the index of the last occurrence of the needle array in the source
  * array, or -1 if it is not present.
  *
- * A start index can be specified as the third argument that begins the search
- * at that given index. The start index defaults to the end of the array.
+ * The complexity of this function is `O(source.length * needle.length)`.
  *
- * The complexity of this function is O(source.length * needle.length).
+ * @param source Source array to check.
+ * @param needle Needle array to check for.
+ * @param start Start index in the source array to begin the search. Defaults to
+ * the end of the array.
  *
+ * @example Basic usage
  * ```ts
  * import { lastIndexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/last_index_of_needle.ts";
+ *
+ * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
+ * const needle = new Uint8Array([1, 2]);
+ * const notNeedle = new Uint8Array([5, 0]);
+ *
+ * lastIndexOfNeedle(source, needle); // 5
+ * lastIndexOfNeedle(source, notNeedle); // -1
+ * ```
+ *
+ * @example Start index
+ * ```ts
+ * import { lastIndexOfNeedle } from "https://deno.land/std@$STD_VERSION/bytes/last_index_of_needle.ts";
+ *
  * const source = new Uint8Array([0, 1, 2, 1, 2, 1, 2, 3]);
  * const needle = new Uint8Array([1, 2]);
- * console.log(lastIndexOfNeedle(source, needle)); // 5
- * console.log(lastIndexOfNeedle(source, needle, 4)); // 3
+ *
+ * lastIndexOfNeedle(source, needle, 2); // 1
+ * lastIndexOfNeedle(source, needle, 6); // 3
  * ```
+ * Defining a start index will begin the search at the specified index in the
+ * source array.
  */
 export function lastIndexOfNeedle(
   source: Uint8Array,