docs(collections,internal,media-types): use @typeParam tag instead of @template (#4772)

_tools/check_docs.ts

@@ -129,23 +129,23 @@ function assertHasExampleTag(tags: JsDocTag[], document: DocNodeBase) {
   }
 }
 
-function assertHasTemplateTags(
+function assertHasTypeParamTags(
   tags: JsDocTag[],
-  template: string,
+  typeParamName: string,
   document: DocNodeBase,
 ) {
   const tag = tags.find((tag) =>
-    tag.kind === "template" && tag.name === template
+    tag.kind === "template" && tag.name === typeParamName
   );
   assert(
     tag !== undefined,
-    `Symbol must have a @template tag for ${template}`,
+    `Symbol must have a @typeParam tag for ${typeParamName}`,
     document,
   );
   assert(
     // @ts-ignore doc is defined
     tag.doc !== undefined,
-    `@template tag for ${template} must have a description`,
+    `@typeParam tag for ${typeParamName} must have a description`,
     document,
   );
 }
@@ -168,7 +168,7 @@ function assertFunctionDocs(document: DocNodeFunction) {
     }
   }
   for (const typeParam of document.functionDef.typeParams) {
-    assertHasTemplateTags(tags, typeParam.name, document);
+    assertHasTypeParamTags(tags, typeParam.name, document);
   }
   assertHasTag(tags, "return", document);
   assertHasExampleTag(tags, document);

collections/aggregate_groups.ts

@@ -7,8 +7,8 @@ import { mapEntries } from "./map_entries.ts";
  * Applies the given aggregator to each group in the given grouping, returning the
  * results together with the respective group keys
  *
- * @template T Type of the values in the input record.
+ * @typeParam T Type of the values in the input record.
- * @template A Type of the accumulator value, which will match the returned
+ * @typeParam A Type of the accumulator value, which will match the returned
  * record's values.
  *
  * @param record The grouping to aggregate.

collections/associate_by.ts

@@ -8,7 +8,7 @@
  * If the selector produces the same key for multiple elements, the latest one
  * will be used (overriding the ones before it).
  *
- * @template T Type of the elements in the input array.
+ * @typeParam T Type of the elements in the input array.
  *
  * @param array The array to transform.
  * @param selector The function to extract the key from each element.

collections/associate_with.ts

@@ -8,7 +8,7 @@
  * If any of two pairs would have the same value, the latest one will be used
  * (overriding the ones before it).
  *
- * @template T The type of the values returned by the selector function.
+ * @typeParam T The type of the values returned by the selector function.
  *
  * @param array The array of elements to associate with values.
  * @param selector The selector function that returns a value for each element.

collections/chunk.ts

@@ -4,7 +4,7 @@
 /**
  * Splits the given array into chunks of the given size and returns them.
  *
- * @template T Type of the elements in the input array.
+ * @typeParam T Type of the elements in the input array.
  *
  * @param array The array to split into chunks.
  * @param size The size of the chunks. This must be a positive integer.

collections/deep_merge.ts

@@ -10,7 +10,7 @@ import { filterInPlace } from "./_utils.ts";
  * For arrays, maps and sets, a merging strategy can be specified to either
  * `replace` values, or `merge` them instead.
  *
- * @template T Type of the first record
+ * @typeParam T Type of the first record
  *
  * @param record First record to merge.
  * @param other Second record to merge.
@@ -107,9 +107,9 @@ export function deepMerge<
  * For arrays, maps and sets, a merging strategy can be specified to either
  * `replace` values, or `merge` them instead.
  *
- * @template T Type of the first record
+ * @typeParam T Type of the first record
- * @template U Type of the second record
+ * @typeParam U Type of the second record
- * @template Options Merging options
+ * @typeParam Options Merging options
  *
  * @param record First record to merge.
  * @param other Second record to merge.

collections/distinct.ts

@@ -5,7 +5,7 @@
  * Returns all distinct elements in the given array, preserving order by first
  * occurrence.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
  *
  * @param array The array to filter for distinct elements.
  *

collections/distinct_by.ts

@@ -5,8 +5,8 @@
  * Returns all elements in the given array that produce a distinct value using
  * the given selector, preserving order by first occurrence.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
- * @template D The type of the values produced by the selector function.
+ * @typeParam D The type of the values produced by the selector function.
  *
  * @param array The array to filter for distinct elements.
  * @param selector The function to extract the value to compare for

collections/drop_last_while.ts

@@ -5,7 +5,7 @@
  * Returns a new array that drops all elements in the given collection until the
  * last element that does not match the given predicate.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
  *
  * @param array The array to drop elements from.
  * @param predicate The function to test each element for a condition.

collections/drop_while.ts

@@ -5,7 +5,7 @@
  * Returns a new array that drops all elements in the given collection until the
  * first element that does not match the given predicate.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
  *
  * @param array The array to drop elements from.
  * @param predicate The function to test each element for a condition.

collections/filter_entries.ts

@@ -5,7 +5,7 @@
  * Returns a new record with all entries of the given record except the ones
  * that do not match the given predicate.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
  *
  * @param record The record to filter entries from.
  * @param predicate The function to test each entry for a condition.

collections/filter_keys.ts

@@ -5,7 +5,7 @@
  * Returns a new record with all entries of the given record except the ones that
  * have a key that does not match the given predicate.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
  *
  * @param record The record to filter keys from.
  * @param predicate The function to test each key for a condition.

collections/filter_values.ts

@@ -5,7 +5,7 @@
  * Returns a new record with all entries of the given record except the ones
  * that have a value that does not match the given predicate.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
  *
  * @param record The record to filter values from.
  * @param predicate The function to test each value for a condition.

collections/find_single.ts

@@ -5,7 +5,7 @@
  * Returns an element if and only if that element is the only one matching the
  * given condition. Returns `undefined` otherwise.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
  *
  * @param array The array to find a single element in.
  * @param predicate The function to test each element for a condition.

collections/first_not_nullish_of.ts

@@ -6,8 +6,8 @@
  * produced that is neither `null` nor `undefined` and returns that value.
  * Returns `undefined` if no such value is produced.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
- * @template O The type of the value produced by the selector function.
+ * @typeParam O The type of the value produced by the selector function.
  *
  * @param array The array to select a value from.
  * @param selector The function to extract a value from an element.

collections/includes_value.ts

@@ -8,7 +8,7 @@
  * Note: this doesn't work with non-primitive values. For example,
  * `includesValue({x: {}}, {})` returns false.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
  *
  * @param record The record to check for the given value.
  * @param value The value to check for in the record.

collections/intersect.ts

@@ -7,7 +7,7 @@ import { filterInPlace } from "./_utils.ts";
  * Returns all distinct elements that appear at least once in each of the given
  * arrays.
  *
- * @template T The type of the elements in the input arrays.
+ * @typeParam T The type of the elements in the input arrays.
  *
  * @param arrays The arrays to intersect.
  *

collections/invert.ts

@@ -13,7 +13,7 @@ export type InvertResult<T extends Record<PropertyKey, PropertyKey>> = {
  * assignments of previous values. If the record contains values which aren't
  * {@linkcode PropertyKey}s their string representation is used as the key.
  *
- * @template T The type of the input record.
+ * @typeParam T The type of the input record.
  *
  * @param record The record to invert.
  *

collections/invert_by.ts

@@ -16,8 +16,8 @@ export type InvertByResult<
  * The corresponding inverted value of each inverted key is an array of keys
  * responsible for generating the inverted value.
  *
- * @template R The type of the input record.
+ * @typeParam R The type of the input record.
- * @template T The type of the iterator function.
+ * @typeParam T The type of the iterator function.
  *
  * @param record The record to invert.
  * @param transformer The function to transform keys.

collections/join_to_string.ts

@@ -45,7 +45,7 @@ export type JoinToStringOptions = {
  * in which case only the first `limit` elements will be appended, followed by
  * the `truncated` string.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
  *
  * @param array The array to join elements from.
  * @param selector The function to transform elements to strings.

collections/map_entries.ts

@@ -5,8 +5,8 @@
  * Applies the given transformer to all entries in the given record and returns
  * a new record containing the results.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
- * @template O The type of the values in the output record.
+ * @typeParam O The type of the values in the output record.
  *
  * @param record The record to map entries from.
  * @param transformer The function to transform each entry.

collections/map_keys.ts

@@ -8,7 +8,7 @@
  * If the transformed entries contain the same key multiple times, only the last
  * one will appear in the returned record.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
  *
  * @param record The record to map keys from.
  * @param transformer The function to transform each key.

collections/map_not_nullish.ts

@@ -6,8 +6,8 @@
  * using the given transformer, except the ones that were transformed to `null`
  * or `undefined`.
  *
- * @template T The type of the elements in the input array.
+ * @typeParam T The type of the elements in the input array.
- * @template O The type of the elements in the output array.
+ * @typeParam O The type of the elements in the output array.
  *
  * @param array The array to map elements from.
  * @param transformer The function to transform each element.

collections/map_values.ts

@@ -6,9 +6,9 @@
  * new record containing the resulting keys associated to the last value that
  * produced them.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
- * @template O The type of the values in the output record.
+ * @typeParam O The type of the values in the output record.
- * @template K The type of the keys in the input and output records.
+ * @typeParam K The type of the keys in the input and output records.
  *
  * @param record The record to map values from.
  * @param transformer The function to transform each value.
@@ -44,9 +44,9 @@ export function mapValues<T, O, K extends string>(
  * new record containing the resulting keys associated to the last value that
  * produced them.
  *
- * @template T The type of the values in the input record.
+ * @typeParam T The type of the values in the input record.
- * @template O The type of the values in the output record.
+ * @typeParam O The type of the values in the output record.
- * @template K The type of the keys in the input and output records.
+ * @typeParam K The type of the keys in the input and output records.
  *
  * @param record The record to map values from.
  * @param transformer The function to transform each value.

collections/max_by.ts

@@ -5,7 +5,7 @@
  * Returns the first element that is the largest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param selector The function to get the value to compare from each element.
@@ -37,7 +37,7 @@ export function maxBy<T>(
  * Returns the first element that is the largest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param selector The function to get the value to compare from each element.
@@ -69,7 +69,7 @@ export function maxBy<T>(
  * Returns the first element that is the largest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param selector The function to get the value to compare from each element.
@@ -101,7 +101,7 @@ export function maxBy<T>(
  * Returns the first element that is the largest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param selector The function to get the value to compare from each element.

collections/max_of.ts

@@ -6,7 +6,7 @@
  * returns the max value of all elements. If an empty array is provided the
  * function will return undefined.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param selector The function to get the value to compare from each element.
@@ -39,7 +39,7 @@ export function maxOf<T>(
  * returns the max value of all elements. If an empty array is provided the
  * function will return undefined.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param selector The function to get the value to compare from each element.

collections/max_with.ts

@@ -9,7 +9,7 @@
  * which means that `comparator(a, b)` should return a negative number if
  * `a < b`, a positive number if `a > b` and `0` if `a === b`.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the maximum element in.
  * @param comparator The function to compare elements.

collections/min_by.ts

@@ -5,7 +5,7 @@
  * Returns the first element that is the smallest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param selector The function to get the value to compare from each element.
@@ -37,7 +37,7 @@ export function minBy<T>(
  * Returns the first element that is the smallest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param selector The function to get the value to compare from each element.
@@ -69,7 +69,7 @@ export function minBy<T>(
  * Returns the first element that is the smallest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param selector The function to get the value to compare from each element.
@@ -101,7 +101,7 @@ export function minBy<T>(
  * Returns the first element that is the smallest value of the given function or
  * undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param selector The function to get the value to compare from each element.

collections/min_of.ts

@@ -6,7 +6,7 @@
  * returns the min value of all elements. If an empty array is provided the
  * function will return undefined.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param selector The function to get the value to compare from each element.
@@ -39,7 +39,7 @@ export function minOf<T>(
  * returns the min value of all elements. If an empty array is provided the
  * function will return undefined.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param selector The function to get the value to compare from each element.

collections/min_with.ts

@@ -5,7 +5,7 @@
  * Returns the first element having the smallest value according to the provided
  * comparator or undefined if there are no elements.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to find the minimum element in.
  * @param comparator The function to compare elements.

collections/omit.ts

@@ -4,8 +4,8 @@
 /**
  * Creates a new object by excluding the specified keys from the provided object.
  *
- * @template T The type of the object.
+ * @typeParam T The type of the object.
- * @template K The type of the keys to omit.
+ * @typeParam K The type of the keys to omit.
  *
  * @param obj The object to omit keys from.
  * @param keys The keys to omit from the object.

collections/partition.ts

@@ -6,7 +6,7 @@
  * the given array that match the given predicate and the second one containing
  * all that do not.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param array The array to partition.
  * @param predicate The predicate function to determine which array an element
@@ -40,8 +40,8 @@ export function partition<T>(
  * allows you to specify a type-guard predicate function that narrows the type
  * of the elements in the array.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
- * @template U The type of the elements that match the predicate.
+ * @typeParam U The type of the elements that match the predicate.
  *
  * @param array The array to partition.
  * @param predicate The type-guard predicate function to determine which array

collections/partition_entries.ts

@@ -6,7 +6,7 @@
  * the given record that match the given predicate and the second one containing
  * all that do not.
  *
- * @template T The type of the values in the record.
+ * @typeParam T The type of the values in the record.
  *
  * @param record The record to partition.
  * @param predicate The predicate function to determine which entries go where.

collections/permutations.ts

@@ -6,7 +6,7 @@
  * Ignores equality of elements, meaning this will always return the same
  * number of permutations for a given length of input.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
  *
  * @param inputArray The array to build permutations from.
  *

collections/pick.ts

@@ -5,8 +5,8 @@
  * Creates a new object by including the specified keys from the provided
  * object.
  *
- * @template T The type of the object.
+ * @typeParam T The type of the object.
- * @template K The type of the keys.
+ * @typeParam K The type of the keys.
  *
  * @param obj The object to pick keys from.
  * @param keys The keys to include in the new object.

collections/reduce_groups.ts

@@ -7,8 +7,8 @@ import { mapValues } from "./map_values.ts";
  * Applies the given reducer to each group in the given grouping, returning the
  * results together with the respective group keys.
  *
- * @template T input type of an item in a group in the given grouping.
+ * @typeParam T input type of an item in a group in the given grouping.
- * @template A type of the accumulator value, which will match the returned
+ * @typeParam A type of the accumulator value, which will match the returned
  * record's values.
  *
  * @param record The grouping to reduce.

collections/running_reduce.ts

@@ -6,8 +6,8 @@
  * result as the accumulator to the next respective call, starting with the
  * given initialValue. Returns all intermediate accumulator results.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
- * @template O The type of the accumulator.
+ * @typeParam O The type of the accumulator.
  *
  * @param array The array to reduce.
  * @param reducer The reducer function to apply to each element.

collections/sample.ts

@@ -6,8 +6,8 @@ import { randomInteger } from "./_utils.ts";
 /**
  * Returns a random element from the given array.
  *
- * @template T The type of the elements in the array.
+ * @typeParam T The type of the elements in the array.
- * @template O The type of the accumulator.
+ * @typeParam O The type of the accumulator.
  *
  * @param array The array to sample from.
  *

collections/sliding_windows.ts

@@ -29,7 +29,7 @@ export interface SlidingWindowsOptions {
  * If partial is set, windows will be generated for the last elements of the
  * collection, resulting in some undefined values if size is greater than 1.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to generate sliding windows from.
  * @param size The size of the sliding windows.

collections/sort_by.ts

@@ -20,7 +20,7 @@ export type SortByOptions = {
  * element. Ascending or descending order can be specified through the `order`
  * option. By default, the elements are sorted in ascending order.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to sort.
  * @param selector The selector function to get the value to sort by.
@@ -66,7 +66,7 @@ export function sortBy<T>(
  * element. Ascending or descending order can be specified through the `order`
  * option. By default, the elements are sorted in ascending order.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to sort.
  * @param selector The selector function to get the value to sort by.
@@ -97,7 +97,7 @@ export function sortBy<T>(
  * element. Ascending or descending order can be specified through the `order`
  * option. By default, the elements are sorted in ascending order.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to sort.
  * @param selector The selector function to get the value to sort by.
@@ -137,7 +137,7 @@ export function sortBy<T>(
  * element. Ascending or descending order can be specified through the `order`
  * option. By default, the elements are sorted in ascending order.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to sort.
  * @param selector The selector function to get the value to sort by.

collections/sum_of.ts

@@ -5,7 +5,7 @@
  * Applies the given selector to all elements in the given collection and
  * calculates the sum of the results.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to calculate the sum of.
  * @param selector The selector function to get the value to sum.

collections/take_last_while.ts

@@ -5,7 +5,7 @@
  * Returns all elements in the given array after the last element that does not
  * match the given predicate.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to take elements from.
  * @param predicate The predicate function to determine if an element should be

collections/take_while.ts

@@ -5,7 +5,7 @@
  * Returns all elements in the given collection until the first element that
  * does not match the given predicate.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to take elements from.
  * @param predicate The predicate function to determine if an element should be

collections/union.ts

@@ -4,7 +4,7 @@
 /**
  * Returns all distinct elements that appear in any of the given arrays.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param arrays The arrays to get the union of.
  *

collections/unzip.ts

@@ -6,8 +6,8 @@
  * returned array holding all first tuple elements and the second one holding
  * all the second elements.
  *
- * @template T The type of the first tuple elements.
+ * @typeParam T The type of the first tuple elements.
- * @template U The type of the second tuple elements.
+ * @typeParam U The type of the second tuple elements.
  *
  * @param pairs The array of 2-tuples to unzip.
  *

collections/without_all.ts

@@ -4,7 +4,7 @@
 /**
  * Returns an array excluding all given values.
  *
- * @template T The type of the array elements.
+ * @typeParam T The type of the array elements.
  *
  * @param array The array to exclude values from.
  * @param values The values to exclude from the array.

collections/zip.ts

@@ -7,7 +7,7 @@ import { minOf } from "./min_of.ts";
  * Builds N-tuples of elements from the given N arrays with matching indices,
  * stopping when the smallest array's end is reached.
  *
- * @template T the type of the tuples produced by this function.
+ * @typeParam T the type of the tuples produced by this function.
  *
  * @param arrays The arrays to zip.
  *

internal/diff.ts

@@ -15,7 +15,7 @@ const ADDED = 3;
 /**
  * Creates an array of common elements between two arrays.
  *
- * @template T The type of elements in the arrays.
+ * @typeParam T The type of elements in the arrays.
  *
  * @param A The first array.
  * @param B The second array.
@@ -122,7 +122,7 @@ function createFp(
 /**
  * Renders the differences between the actual and expected values.
  *
- * @template T The type of elements in the arrays.
+ * @typeParam T The type of elements in the arrays.
  *
  * @param A Actual value
  * @param B Expected value

internal/types.ts

@@ -6,7 +6,7 @@ export type DiffType = "removed" | "common" | "added";
 /**
  * Represents the result of a diff operation.
  *
- * @template T The type of the value in the diff result.
+ * @typeParam T The type of the value in the diff result.
  */
 export interface DiffResult<T> {
   /** The type of the diff. */

media_types/content_type.ts

@@ -41,7 +41,7 @@ export type KnownExtensionOrType =
  * > file name, use {@linkcode https://jsr.io/@std/path/doc/~/extname | extname}
  * > to determine the extension and pass it here.
  *
- * @template T Type of the extension or media type to resolve.
+ * @typeParam T Type of the extension or media type to resolve.
  *
  * @param extensionOrType The extension or media type to resolve.
  *