From 64c23b47de3a2aa61bb5ebc49b9553fcf2367103 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Thu, 23 May 2024 16:28:33 +0900
Subject: [PATCH 1/8] docs(semver): improve docs

---
 _tools/check_docs.ts         |  1 +
 semver/can_parse.ts          | 15 +++++++++++++++
 semver/compare.ts            | 17 +++++++++++++++++
 semver/difference.ts         | 23 ++++++++++++++++++++++-
 semver/equals.ts             | 16 ++++++++++++++++
 semver/format.ts             | 13 +++++++++++++
 semver/format_range.ts       | 10 +++++++++-
 semver/greater_or_equal.ts   | 16 ++++++++++++++++
 semver/greater_than.ts       | 16 ++++++++++++++++
 semver/greater_than_range.ts | 20 +++++++++++++++++++-
 semver/increment.ts          | 20 ++++++++++++++++++--
 semver/is_range.ts           | 10 ++++++++++
 semver/is_semver.ts          | 16 ++++++++++++++++
 semver/less_or_equal.ts      | 16 ++++++++++++++++
 semver/less_than.ts          | 16 ++++++++++++++++
 semver/less_than_range.ts    | 20 +++++++++++++++++++-
 semver/max_satisfying.ts     | 12 ++++++++++++
 semver/min_satisfying.ts     | 12 ++++++++++++
 semver/mod.ts                |  1 +
 semver/not_equals.ts         | 15 +++++++++++++++
 semver/parse.ts              | 16 ++++++++++++++++
 semver/parse_range.ts        | 18 ++++++++++++++++++
 semver/range_intersects.ts   | 17 ++++++++++++++++-
 semver/range_max.ts          | 14 ++++++++++----
 semver/range_min.ts          | 14 ++++++++++----
 semver/satisfies.ts          | 15 +++++++++++++++
 semver/test_range.ts         | 15 +++++++++++++++
 semver/try_parse.ts          | 13 +++++++++++++
 semver/try_parse_range.ts    | 17 ++++++++++++++++-
 semver/types.ts              | 17 ++++++++++++++---
 30 files changed, 422 insertions(+), 19 deletions(-)

diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts
index 18370635bb05..48c5ebbec3fc 100644
--- a/_tools/check_docs.ts
+++ b/_tools/check_docs.ts
@@ -33,6 +33,7 @@ const ENTRY_POINTS = [
   "../internal/mod.ts",
   "../jsonc/mod.ts",
   "../media_types/mod.ts",
+  "../semver/mod.ts",
   "../ulid/mod.ts",
   "../webgpu/mod.ts",
   "../http/mod.ts",
diff --git a/semver/can_parse.ts b/semver/can_parse.ts
index 2a88243aaa5e..c9ccf7bc9e44 100644
--- a/semver/can_parse.ts
+++ b/semver/can_parse.ts
@@ -2,6 +2,21 @@
 // This module is browser compatible.
 import { parse } from "./parse.ts";
 
+/**
+ * Returns true if the string can be parsed as semver.
+ *
+ * @example Usage
+ * ```ts
+ * import { canParse } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * assert(canParse("1.2.3"));
+ * assertFalse(canParse("invalid"));
+ * ```
+ *
+ * @param version The version string to check
+ * @returns `true` if the string can be parsed as semver, `false` otherwise
+ */
 export function canParse(version: string): boolean {
   try {
     parse(version);
diff --git a/semver/compare.ts b/semver/compare.ts
index 480023451728..a859ef5c7ad7 100644
--- a/semver/compare.ts
+++ b/semver/compare.ts
@@ -14,6 +14,23 @@ import {
  * greater.
  *
  * Sorts in ascending order if passed to `Array.sort()`,
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, compare } from "@std/semver";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ *
+ * assertEquals(compare(s0, s1), -1);
+ * assertEquals(compare(s1, s0), 1);
+ * assertEquals(compare(s0, s0), 0);
+ * ```
+ *
+ * @param s0 The first SemVer to compare
+ * @param s1 The second SemVer to compare
+ * @returns `1` if `s0` is greater, `0` if equal, or `-1` if `s1` is greater
  */
 export function compare(
   s0: SemVer,
diff --git a/semver/difference.ts b/semver/difference.ts
index 6a13e6a797b8..859cd8b73e40 100644
--- a/semver/difference.ts
+++ b/semver/difference.ts
@@ -4,7 +4,28 @@ import type { ReleaseType, SemVer } from "./types.ts";
 import { compareIdentifier } from "./_shared.ts";
 
 /**
- * Returns difference between two versions by the release type, or `undefined` if the versions are the same.
+ * Returns difference between two versions by the release type,
+ * or `undefined` if the versions are the same.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, difference } from "@std/semver";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ * const s2 = parse("1.3.0");
+ * const s3 = parse("2.0.0");
+ *
+ * assertEquals(difference(s0, s1), "patch");
+ * assertEquals(difference(s0, s2), "minor");
+ * assertEquals(difference(s0, s3), "major");
+ * assertEquals(difference(s0, s0), undefined);
+ * ```
+ *
+ * @param s0 The first SemVer to compare
+ * @param s1 The second SemVer to compare
+ * @returns The release type difference or `undefined` if the versions are the same
  */
 export function difference(s0: SemVer, s1: SemVer): ReleaseType | undefined {
   const hasPrerelease = s0.prerelease?.length || s1.prerelease?.length;
diff --git a/semver/equals.ts b/semver/equals.ts
index 361a8fa49978..05c2af01ef03 100644
--- a/semver/equals.ts
+++ b/semver/equals.ts
@@ -7,6 +7,22 @@ import type { SemVer } from "./types.ts";
  * Returns `true` if both semantic versions are logically equivalent, even if they're not the exact same version object.
  *
  * This is equal to `compare(s0, s1) === 0`.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, equals } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.3");
+ *
+ * assert(equals(s0, s1));
+ * assertFalse(equals(s0, parse("1.2.4")));
+ * ```
+ *
+ * @param s0 The first version to compare
+ * @param s1 The second version to compare
+ * @returns `true` if `s0` is equal to `s1`, `false` otherwise
  */
 export function equals(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) === 0;
diff --git a/semver/format.ts b/semver/format.ts
index 483c14ee9f39..a1276854be7e 100644
--- a/semver/format.ts
+++ b/semver/format.ts
@@ -20,6 +20,19 @@ function formatNumber(value: number) {
  *
  * If any number is positive or negative infinity then '∞' or '⧞' will be printed instead.
  *
+ * @example Usage
+ * ```ts
+ * import { format } from "@std/semver";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const semver = {
+ *   major: 1,
+ *   minor: 2,
+ *   patch: 3,
+ * };
+ * assertEquals(format(semver), "1.2.3");
+ * ```
+ *
  * @param semver The semantic version to format
  * @returns The string representation of a semantic version.
  */
diff --git a/semver/format_range.ts b/semver/format_range.ts
index e711d69bd158..3301bd6c1b0f 100644
--- a/semver/format_range.ts
+++ b/semver/format_range.ts
@@ -10,7 +10,15 @@ function formatComparator(comparator: Comparator): string {
 
 /**
  * Formats the range into a string
- * @example >=0.0.0 || <1.0.0
+ * @example Usage
+ * ```ts
+ * import { formatRange, parseRange } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const range = parseRange(">=1.2.3 <1.2.4");
+ * assertEquals(formatRange(range), ">=1.2.3 <1.2.4");
+ * ```
+ *
  * @param range The range to format
  * @returns A string representation of the range
  */
diff --git a/semver/greater_or_equal.ts b/semver/greater_or_equal.ts
index 88e429cf1f11..d5fffdc4c4ef 100644
--- a/semver/greater_or_equal.ts
+++ b/semver/greater_or_equal.ts
@@ -7,6 +7,22 @@ import { compare } from "./compare.ts";
  * Greater than or equal to comparison
  *
  * This is equal to `compare(s0, s1) >= 0`.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, greaterOrEqual } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ * assert(greaterOrEqual(s1, s0));
+ * assertFalse(greaterOrEqual(s0, s1));
+ * assert(greaterOrEqual(s0, s0));
+ * ```
+ *
+ * @param s0 The first version to compare
+ * @param s1 The second version to compare
+ * @returns `true` if `s0` is greater than or equal to `s1`, `false` otherwise
  */
 export function greaterOrEqual(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) >= 0;
diff --git a/semver/greater_than.ts b/semver/greater_than.ts
index 252238bcb6da..31d784bb4b9e 100644
--- a/semver/greater_than.ts
+++ b/semver/greater_than.ts
@@ -8,6 +8,22 @@ import { compare } from "./compare.ts";
  * Greater than comparison
  *
  * This is equal to `compare(s0, s1) > 0`.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, greaterThan } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ * assert(greaterThan(s1, s0));
+ * assertFalse(greaterThan(s0, s1));
+ * assertFalse(greaterThan(s0, s0));
+ * ```
+ *
+ * @param s0 The first version to compare
+ * @param s1 The second version to compare
+ * @returns `true` if `s0` is greater than `s1`, `false` otherwise
  */
 export function greaterThan(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) > 0;
diff --git a/semver/greater_than_range.ts b/semver/greater_than_range.ts
index dbed2ae39c7a..7df8b7a2c2f2 100644
--- a/semver/greater_than_range.ts
+++ b/semver/greater_than_range.ts
@@ -6,7 +6,25 @@ import { testComparatorSet } from "./_test_comparator_set.ts";
 import { isWildcardComparator } from "./_shared.ts";
 import { compare } from "./compare.ts";
 
-/** Check if the semver is greater than the range. */
+/**
+ * Check if the semver is greater than the range.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, parseRange, greaterThanRange } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const v0 = parse("1.2.3");
+ * const v1 = parse("1.2.4");
+ * const range = parseRange(">=1.2.3 <1.2.4");
+ * assertFalse(greaterThanRange(v0, range));
+ * assert(greaterThanRange(v1, range));
+ * ```
+ *
+ * @param semver The version to check.
+ * @param range The range to check against.
+ * @returns `true` if the semver is greater than the range, `false` otherwise.
+ */
 export function greaterThanRange(semver: SemVer, range: Range): boolean {
   return range.every((comparatorSet) =>
     greaterThanComparatorSet(semver, comparatorSet)
diff --git a/semver/increment.ts b/semver/increment.ts
index 14e14fa2ccf6..8dbeb60bbbb5 100644
--- a/semver/increment.ts
+++ b/semver/increment.ts
@@ -55,11 +55,27 @@ function bumpPrerelease(
  * If the input version has build metadata it will be preserved on the resulting version
  * unless a new build parameter is specified. Specifying `""` will unset existing build
  * metadata.
+ *
+ * @example Usage
+ * ```ts
+ * import { increment, parse } from "@std/semver";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const version = parse("1.2.3");
+ * assertEquals(increment(version, "major"), parse("2.0.0"));
+ * assertEquals(increment(version, "minor"), parse("1.3.0"));
+ * assertEquals(increment(version, "patch"), parse("1.2.4"));
+ * assertEquals(increment(version, "prerelease"), parse("1.2.4-0"));
+ *
+ * const prerelease = parse("1.2.3-beta.0");
+ * assertEquals(increment(prerelease, "prerelease"), parse("1.2.3-beta.1"));
+ * ```
+ *
  * @param version The version to increment
  * @param release The type of increment to perform
  * @param prerelease The pre-release metadata of the new version
- * @param build The build metadata of the new version
- * @returns
+ * @param buildmetadata The build metadata of the new version
+ * @returns The new version
  */
 export function increment(
   version: SemVer,
diff --git a/semver/is_range.ts b/semver/is_range.ts
index 1102d8fbd86b..bd5d1e699477 100644
--- a/semver/is_range.ts
+++ b/semver/is_range.ts
@@ -26,6 +26,16 @@ function isComparator(value: unknown): value is Comparator {
  * least the correct fields.
  *
  * Adds a type assertion if true.
+ *
+ * @example Usage
+ * ```ts
+ * import { isRange } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const range = [[{ major: 1, minor: 2, patch: 3 }]];
+ * assert(isRange(range));
+ * assertFalse(isRange({}));
+ * ```
  * @param value The value to check if its a valid Range
  * @returns True if its a valid Range otherwise false.
  */
diff --git a/semver/is_semver.ts b/semver/is_semver.ts
index a6dbda7e0acf..21694108c0f4 100644
--- a/semver/is_semver.ts
+++ b/semver/is_semver.ts
@@ -16,6 +16,22 @@ import { isValidNumber, isValidString } from "./_shared.ts";
  * considered SemVer objects and this will return true.
  *
  * A type assertion is added to the value.
+ *
+ * @example Usage
+ * ```ts
+ * import { isSemVer } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const value = {
+ *   major: 1,
+ *   minor: 2,
+ *   patch: 3,
+ * };
+ *
+ * assert(isSemVer(value));
+ * assertFalse(isSemVer({ major: 1, minor: 2 }));
+ * ```
+ *
  * @param value The value to check to see if its a valid SemVer object
  * @returns True if value is a valid SemVer otherwise false
  */
diff --git a/semver/less_or_equal.ts b/semver/less_or_equal.ts
index fccee015d20a..6714ba68b20d 100644
--- a/semver/less_or_equal.ts
+++ b/semver/less_or_equal.ts
@@ -7,6 +7,22 @@ import { compare } from "./compare.ts";
  * Less than or equal to comparison
  *
  * This is equal to `compare(s0, s1) <= 0`.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, lessOrEqual } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ * assert(lessOrEqual(s0, s1));
+ * assertFalse(lessOrEqual(s1, s0));
+ * assert(lessOrEqual(s0, s0));
+ * ```
+ *
+ * @param s0 the first version to compare
+ * @param s1 the second version to compare
+ * @returns `true` if `s0` is less than or equal to `s1`, `false` otherwise
  */
 export function lessOrEqual(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) <= 0;
diff --git a/semver/less_than.ts b/semver/less_than.ts
index 017e6db3df47..4d0946399e50 100644
--- a/semver/less_than.ts
+++ b/semver/less_than.ts
@@ -7,6 +7,22 @@ import { compare } from "./compare.ts";
  * Less than comparison
  *
  * This is equal to `compare(s0, s1) < 0`.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, lessThan } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ * assert(lessThan(s0, s1));
+ * assertFalse(lessThan(s1, s0));
+ * assertFalse(lessThan(s0, s0));
+ * ```
+ *
+ * @param s0 the first version to compare
+ * @param s1 the second version to compare
+ * @returns `true` if `s0` is less than `s1`, `false` otherwise
  */
 export function lessThan(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) < 0;
diff --git a/semver/less_than_range.ts b/semver/less_than_range.ts
index d822a5ce358d..529a108836e9 100644
--- a/semver/less_than_range.ts
+++ b/semver/less_than_range.ts
@@ -6,7 +6,25 @@ import { testComparatorSet } from "./_test_comparator_set.ts";
 import { isWildcardComparator } from "./_shared.ts";
 import { compare } from "./compare.ts";
 
-/** Check if the semver is less than the range. */
+/**
+ * Check if the semver is less than the range.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, parseRange, lessThanRange } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const v0 = parse("1.2.3");
+ * const v1 = parse("1.0.0");
+ * const range = parseRange(">=1.2.3 <1.2.4");
+ * assertFalse(lessThanRange(v0, range));
+ * assert(lessThanRange(v1, range));
+ * ```
+ *
+ * @param semver The version to check.
+ * @param range The range to check against.
+ * @returns `true` if the semver is less than the range, `false` otherwise.
+ */
 export function lessThanRange(semver: SemVer, range: Range): boolean {
   return range.every((comparatorSet) =>
     lessThanComparatorSet(semver, comparatorSet)
diff --git a/semver/max_satisfying.ts b/semver/max_satisfying.ts
index a6f991b36ca6..fba582c212da 100644
--- a/semver/max_satisfying.ts
+++ b/semver/max_satisfying.ts
@@ -7,6 +7,18 @@ import { greaterThan } from "./greater_than.ts";
 /**
  * Returns the highest version in the list that satisfies the range, or `undefined`
  * if none of them do.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, parseRange, maxSatisfying } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const versions = ["1.2.3", "1.2.4", "1.3.0", "2.0.0", "2.1.0"].map(parse);
+ * const range = parseRange(">=1.0.0 <2.0.0");
+ *
+ * assertEquals(maxSatisfying(versions, range), parse("1.3.0"));
+ * ```
+ *
  * @param versions The versions to check.
  * @param range The range of possible versions to compare to.
  * @returns The highest version in versions that satisfies the range.
diff --git a/semver/min_satisfying.ts b/semver/min_satisfying.ts
index e19b4caedffc..1da56f31c9db 100644
--- a/semver/min_satisfying.ts
+++ b/semver/min_satisfying.ts
@@ -7,6 +7,18 @@ import { lessThan } from "./less_than.ts";
 /**
  * Returns the lowest version in the list that satisfies the range, or `undefined` if
  * none of them do.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, parseRange, minSatisfying } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const versions = ["0.2.0", "1.2.3", "1.3.0", "2.0.0", "2.1.0"].map(parse);
+ * const range = parseRange(">=1.0.0 <2.0.0");
+ *
+ * assertEquals(minSatisfying(versions, range), parse("1.2.3"));
+ * ```
+ *
  * @param versions The versions to check.
  * @param range The range of possible versions to compare to.
  * @returns The lowest version in versions that satisfies the range.
diff --git a/semver/mod.ts b/semver/mod.ts
index 4ad318346d13..25793a2e0450 100644
--- a/semver/mod.ts
+++ b/semver/mod.ts
@@ -295,4 +295,5 @@ export * from "./less_than.ts";
 export * from "./less_than_range.ts";
 export * from "./less_or_equal.ts";
 
+/** The semver spec version */
 export const SEMVER_SPEC_VERSION = "2.0.0";
diff --git a/semver/not_equals.ts b/semver/not_equals.ts
index 79a81a537f44..1f22eb3a8429 100644
--- a/semver/not_equals.ts
+++ b/semver/not_equals.ts
@@ -7,6 +7,21 @@ import { compare } from "./compare.ts";
  * Not equal comparison
  *
  * This is equal to `compare(s0, s1) !== 0`.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, notEquals } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const s0 = parse("1.2.3");
+ * const s1 = parse("1.2.4");
+ * assert(notEquals(s0, s1));
+ * assertFalse(notEquals(s0, s0));
+ * ```
+ *
+ * @param s0 The first version to compare
+ * @param s1 The second version to compare
+ * @returns `true` if `s0` is not equal to `s1`, `false` otherwise
  */
 export function notEquals(s0: SemVer, s1: SemVer): boolean {
   return compare(s0, s1) !== 0;
diff --git a/semver/parse.ts b/semver/parse.ts
index b6c4cd46ac85..b6100cca8eef 100644
--- a/semver/parse.ts
+++ b/semver/parse.ts
@@ -7,6 +7,22 @@ import { FULL_REGEXP, MAX_LENGTH } from "./_shared.ts";
 /**
  * Attempt to parse a string as a semantic version, returning either a `SemVer`
  * object or throws a TypeError.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const version = parse("1.2.3");
+ * assertEquals(version, {
+ *   major: 1,
+ *   minor: 2,
+ *   patch: 3,
+ *   prerelease: [],
+ *   build: [],
+ * });
+ * ```
+ *
  * @param version The version string to parse
  * @returns A valid SemVer
  */
diff --git a/semver/parse_range.ts b/semver/parse_range.ts
index 84f8ddcbfa3a..69f9d483318a 100644
--- a/semver/parse_range.ts
+++ b/semver/parse_range.ts
@@ -381,6 +381,24 @@ function parseOperatorRanges(string: string): Comparator[] {
 
 /**
  * Parses a range string into a Range object or throws a TypeError.
+ *
+ * @example Usage
+ * ```ts
+ * import { parseRange } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const range = parseRange(">=1.0.0 <2.0.0 || >=3.0.0");
+ * assertEquals(range, [
+ *   [
+ *     { operator: ">=", major: 1, minor: 0, patch: 0, prerelease: [], build: [] },
+ *     { operator: "<", major: 2, minor: 0, patch: 0, prerelease: [], build: [] },
+ *   ],
+ *   [
+ *     { operator: ">=", major: 3, minor: 0, patch: 0, prerelease: [], build: [] },
+ *   ]
+ * ]);
+ * ```
+ *
  * @param range The range set string
  * @returns A valid semantic range
  */
diff --git a/semver/range_intersects.ts b/semver/range_intersects.ts
index 4b571d10a73f..7418ed4efdb7 100644
--- a/semver/range_intersects.ts
+++ b/semver/range_intersects.ts
@@ -67,9 +67,24 @@ function comparatorsSatisfiable(comparators: Comparator[]): boolean {
 
 /**
  * The ranges intersect every range of AND comparators intersects with a least one range of OR ranges.
+ *
+ * @example Usage
+ * ```ts
+ * import { parseRange, rangeIntersects } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const r0 = parseRange(">=1.0.0 <2.0.0");
+ * const r1 = parseRange(">=1.0.0 <1.2.3");
+ * const r2 = parseRange(">=1.2.3 <2.0.0");
+ *
+ * assert(rangeIntersects(r0, r1));
+ * assert(rangeIntersects(r0, r2));
+ * assertFalse(rangeIntersects(r1, r2));
+ * ```
+ *
  * @param r0 range 0
  * @param r1 range 1
- * @returns returns true if any
+ * @returns returns true if the given ranges intersect, false otherwise
  */
 export function rangeIntersects(
   r0: Range,
diff --git a/semver/range_max.ts b/semver/range_max.ts
index 09951646964f..aed009e8c048 100644
--- a/semver/range_max.ts
+++ b/semver/range_max.ts
@@ -44,15 +44,21 @@ function comparatorMax(comparator: Comparator): SemVer {
 }
 
 /**
+ * The maximum valid SemVer for a given range or INVALID
+ *
+ * @example Usage
+ * ```ts
+ * // This API is deprecated
+ * ```
+ *
+ * @param range The range to calculate the max for
+ * @returns A valid SemVer or INVALID
+ *
  * @deprecated This will be removed in 1.0.0. Use {@linkcode greaterThanRange} or
  * {@linkcode lessThanRange} for comparing ranges and semvers. The maximum
  * version of a range is often not well defined, and therefore this API
  * shouldn't be used. See
  * {@link https://github.com/denoland/deno_std/issues/4365} for details.
- *
- * The maximum valid SemVer for a given range or INVALID
- * @param range The range to calculate the max for
- * @returns A valid SemVer or INVALID
  */
 export function rangeMax(range: Range): SemVer {
   let max;
diff --git a/semver/range_min.ts b/semver/range_min.ts
index fc64ce1f24f3..fc3aabeac528 100644
--- a/semver/range_min.ts
+++ b/semver/range_min.ts
@@ -35,15 +35,21 @@ function comparatorMin(comparator: Comparator): SemVer {
 }
 
 /**
+ * The minimum valid SemVer for a given range or INVALID
+ *
+ * @example Usage
+ * ```ts
+ * // This API is deprecated
+ * ```
+ *
+ * @param range The range to calculate the min for
+ * @returns A valid SemVer or INVALID
+ *
  * @deprecated This will be removed in 1.0.0. Use {@linkcode greaterThanRange} or
  * {@linkcode lessThanRange} for comparing ranges and semvers. The minimum
  * version of a range is often not well defined, and therefore this API
  * shouldn't be used. See
  * {@link https://github.com/denoland/deno_std/issues/4365} for details.
- *
- * The minimum valid SemVer for a given range or INVALID
- * @param range The range to calculate the min for
- * @returns A valid SemVer or INVALID
  */
 export function rangeMin(range: Range): SemVer {
   let min;
diff --git a/semver/satisfies.ts b/semver/satisfies.ts
index 69a7c586e19c..0e86920c76a2 100644
--- a/semver/satisfies.ts
+++ b/semver/satisfies.ts
@@ -5,6 +5,21 @@ import { testComparatorSet } from "./_test_comparator_set.ts";
 
 /**
  * Test to see if the version satisfies the range.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, parseRange, satisfies } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const version = parse("1.2.3");
+ * const range0 = parseRange(">=1.0.0 <2.0.0");
+ * const range1 = parseRange(">=1.0.0 <1.3.0");
+ * const range2 = parseRange(">=1.0.0 <1.2.3");
+ *
+ * assert(satisfies(version, range0));
+ * assert(satisfies(version, range1));
+ * assertFalse(satisfies(version, range2));
+ * ```
  * @param version The version to test
  * @param range The range to check
  * @returns true if the version is in the range
diff --git a/semver/test_range.ts b/semver/test_range.ts
index 74db80d68064..69e5a024485d 100644
--- a/semver/test_range.ts
+++ b/semver/test_range.ts
@@ -4,6 +4,21 @@ import { satisfies } from "./satisfies.ts";
 
 /**
  * Test to see if the version satisfies the range.
+ *
+ * @example Usage
+ * ```ts
+ * import { parse, parseRange, testRange } from "@std/semver";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * const version = parse("1.2.3");
+ * const range0 = parseRange(">=1.0.0 <2.0.0");
+ * const range1 = parseRange(">=1.0.0 <1.3.0");
+ * const range2 = parseRange(">=1.0.0 <1.2.3");
+ *
+ * assert(testRange(version, range0));
+ * assert(testRange(version, range1));
+ * assertFalse(testRange(version, range2));
+ * ```
  * @param version The version to test
  * @param range The range to check
  * @returns true if the version is in the range
diff --git a/semver/try_parse.ts b/semver/try_parse.ts
index 1513b7ec761e..423a12a0c8f6 100644
--- a/semver/try_parse.ts
+++ b/semver/try_parse.ts
@@ -5,6 +5,19 @@ import { parse } from "./parse.ts";
 
 /**
  * Returns the parsed version, or undefined if it's not valid.
+ *
+ * @example Usage
+ * ```ts
+ * import { tryParse } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(tryParse("1.2.3"), { major: 1, minor: 2, patch: 3, prerelease: [], build: [] });
+ * assertEquals(tryParse("1.2.3-alpha"), { major: 1, minor: 2, patch: 3, prerelease: ["alpha"], build: [] });
+ * assertEquals(tryParse("1.2.3+build"), { major: 1, minor: 2, patch: 3, prerelease: [], build: ["build"] });
+ * assertEquals(tryParse("1.2.3-alpha.1+build.1"), { major: 1, minor: 2, patch: 3, prerelease: ["alpha", 1], build: ["build", "1"] });
+ * assertEquals(tryParse(" invalid "), undefined);
+ * ```
+ *
  * @param version The version string to parse
  * @returns A valid SemVer or `undefined`
  */
diff --git a/semver/try_parse_range.ts b/semver/try_parse_range.ts
index 1e8fa305f716..e1b2c3ba7273 100644
--- a/semver/try_parse_range.ts
+++ b/semver/try_parse_range.ts
@@ -5,7 +5,22 @@ import type { Range } from "./types.ts";
 import { parseRange } from "./parse_range.ts";
 
 /**
- * A tries to parse a valid Range string or returns undefined
+ * Parses the given range string and returns a Range object. If the range string
+ * is invalid, `undefined` is returned.
+ *
+ * @example Usage
+ * ```ts
+ * import { tryParseRange } from "@std/semver";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(tryParseRange(">=1.2.3 <1.2.4"), [
+ *  [
+ *    { operator: ">=", major: 1, minor: 2, patch: 3, prerelease: [], build: [] },
+ *    { operator: "<", major: 1, minor: 2, patch: 4, prerelease: [], build: [] },
+ *  ],
+ * ]);
+ * ```
+ *
  * @param range The range string
  * @returns A Range object if valid otherwise `undefined`
  */
diff --git a/semver/types.ts b/semver/types.ts
index 898b147db821..2d17c6dd7399 100644
--- a/semver/types.ts
+++ b/semver/types.ts
@@ -1,8 +1,6 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-import type { OPERATORS } from "./_constants.ts";
-
 /**
  * The possible release types are used as an operator for the
  * increment function and as a result of the difference function.
@@ -20,13 +18,21 @@ export type ReleaseType =
 /**
  * SemVer comparison operators.
  */
-export type Operator = typeof OPERATORS[number];
+export type Operator =
+  | undefined
+  | "="
+  | "!="
+  | ">"
+  | ">="
+  | "<"
+  | "<=";
 
 /**
  * The shape of a valid semantic version comparator
  * @example >=0.0.0
  */
 export interface Comparator extends SemVer {
+  /** The operator */
   operator?: Operator;
 }
 
@@ -34,10 +40,15 @@ export interface Comparator extends SemVer {
  * A SemVer object parsed into its constituent parts.
  */
 export interface SemVer {
+  /** The major version */
   major: number;
+  /** The minor version */
   minor: number;
+  /** The patch version */
   patch: number;
+  /** The prerelease version */
   prerelease?: (string | number)[];
+  /** The build metadata */
   build?: string[];
 }
 

From 03b4fee631c87cc96c8279da71d97f4376365cb1 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Fri, 24 May 2024 21:23:26 +0900
Subject: [PATCH 2/8] use specific import path where possible

---
 semver/can_parse.ts      | 2 +-
 semver/format.ts         | 2 +-
 semver/is_range.ts       | 2 +-
 semver/is_semver.ts      | 2 +-
 semver/max_satisfying.ts | 2 +-
 semver/min_satisfying.ts | 2 +-
 semver/parse.ts          | 4 ++--
 semver/parse_range.ts    | 4 ++--
 semver/try_parse.ts      | 4 ++--
 9 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/semver/can_parse.ts b/semver/can_parse.ts
index c9ccf7bc9e44..246ed278b35c 100644
--- a/semver/can_parse.ts
+++ b/semver/can_parse.ts
@@ -7,7 +7,7 @@ import { parse } from "./parse.ts";
  *
  * @example Usage
  * ```ts
- * import { canParse } from "@std/semver";
+ * import { canParse } from "@std/semver/can-parse";
  * import { assert, assertFalse } from "@std/assert";
  *
  * assert(canParse("1.2.3"));
diff --git a/semver/format.ts b/semver/format.ts
index a1276854be7e..750c9c0bc26b 100644
--- a/semver/format.ts
+++ b/semver/format.ts
@@ -22,7 +22,7 @@ function formatNumber(value: number) {
  *
  * @example Usage
  * ```ts
- * import { format } from "@std/semver";
+ * import { format } from "@std/semver/format";
  * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const semver = {
diff --git a/semver/is_range.ts b/semver/is_range.ts
index bd5d1e699477..953226f5af5a 100644
--- a/semver/is_range.ts
+++ b/semver/is_range.ts
@@ -29,7 +29,7 @@ function isComparator(value: unknown): value is Comparator {
  *
  * @example Usage
  * ```ts
- * import { isRange } from "@std/semver";
+ * import { isRange } from "@std/semver/is-range";
  * import { assert, assertFalse } from "@std/assert";
  *
  * const range = [[{ major: 1, minor: 2, patch: 3 }]];
diff --git a/semver/is_semver.ts b/semver/is_semver.ts
index 21694108c0f4..a26a0853aa10 100644
--- a/semver/is_semver.ts
+++ b/semver/is_semver.ts
@@ -19,7 +19,7 @@ import { isValidNumber, isValidString } from "./_shared.ts";
  *
  * @example Usage
  * ```ts
- * import { isSemVer } from "@std/semver";
+ * import { isSemVer } from "@std/semver/is-semver";
  * import { assert, assertFalse } from "@std/assert";
  *
  * const value = {
diff --git a/semver/max_satisfying.ts b/semver/max_satisfying.ts
index fba582c212da..b5c07782d561 100644
--- a/semver/max_satisfying.ts
+++ b/semver/max_satisfying.ts
@@ -11,7 +11,7 @@ import { greaterThan } from "./greater_than.ts";
  * @example Usage
  * ```ts
  * import { parse, parseRange, maxSatisfying } from "@std/semver";
- * import { assertEquals } from "@std/assert";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const versions = ["1.2.3", "1.2.4", "1.3.0", "2.0.0", "2.1.0"].map(parse);
  * const range = parseRange(">=1.0.0 <2.0.0");
diff --git a/semver/min_satisfying.ts b/semver/min_satisfying.ts
index 1da56f31c9db..cf9525c07159 100644
--- a/semver/min_satisfying.ts
+++ b/semver/min_satisfying.ts
@@ -11,7 +11,7 @@ import { lessThan } from "./less_than.ts";
  * @example Usage
  * ```ts
  * import { parse, parseRange, minSatisfying } from "@std/semver";
- * import { assertEquals } from "@std/assert";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const versions = ["0.2.0", "1.2.3", "1.3.0", "2.0.0", "2.1.0"].map(parse);
  * const range = parseRange(">=1.0.0 <2.0.0");
diff --git a/semver/parse.ts b/semver/parse.ts
index b6100cca8eef..9b27d1bd90de 100644
--- a/semver/parse.ts
+++ b/semver/parse.ts
@@ -10,8 +10,8 @@ import { FULL_REGEXP, MAX_LENGTH } from "./_shared.ts";
  *
  * @example Usage
  * ```ts
- * import { parse } from "@std/semver";
- * import { assertEquals } from "@std/assert";
+ * import { parse } from "@std/semver/parse";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const version = parse("1.2.3");
  * assertEquals(version, {
diff --git a/semver/parse_range.ts b/semver/parse_range.ts
index 69f9d483318a..257732695c59 100644
--- a/semver/parse_range.ts
+++ b/semver/parse_range.ts
@@ -384,8 +384,8 @@ function parseOperatorRanges(string: string): Comparator[] {
  *
  * @example Usage
  * ```ts
- * import { parseRange } from "@std/semver";
- * import { assertEquals } from "@std/assert";
+ * import { parseRange } from "@std/semver/parse-range";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const range = parseRange(">=1.0.0 <2.0.0 || >=3.0.0");
  * assertEquals(range, [
diff --git a/semver/try_parse.ts b/semver/try_parse.ts
index 423a12a0c8f6..08673031a787 100644
--- a/semver/try_parse.ts
+++ b/semver/try_parse.ts
@@ -8,8 +8,8 @@ import { parse } from "./parse.ts";
  *
  * @example Usage
  * ```ts
- * import { tryParse } from "@std/semver";
- * import { assertEquals } from "@std/assert";
+ * import { tryParse } from "@std/semver/try-parse";
+ * import { assertEquals } from "@std/assert/assert-equals";
  *
  * assertEquals(tryParse("1.2.3"), { major: 1, minor: 2, patch: 3, prerelease: [], build: [] });
  * assertEquals(tryParse("1.2.3-alpha"), { major: 1, minor: 2, patch: 3, prerelease: ["alpha"], build: [] });

From 704a95e3ae75306bb462deb066a73e2a4308b668 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Mon, 27 May 2024 18:41:57 +0900
Subject: [PATCH 3/8] Apply suggestions from code review

Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>
---
 semver/can_parse.ts          | 4 ++--
 semver/equals.ts             | 4 ++--
 semver/format.ts             | 2 +-
 semver/greater_than_range.ts | 2 +-
 semver/mod.ts                | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/semver/can_parse.ts b/semver/can_parse.ts
index 246ed278b35c..5f440670e618 100644
--- a/semver/can_parse.ts
+++ b/semver/can_parse.ts
@@ -3,7 +3,7 @@
 import { parse } from "./parse.ts";
 
 /**
- * Returns true if the string can be parsed as semver.
+ * Returns true if the string can be parsed as SemVer.
  *
  * @example Usage
  * ```ts
@@ -15,7 +15,7 @@ import { parse } from "./parse.ts";
  * ```
  *
  * @param version The version string to check
- * @returns `true` if the string can be parsed as semver, `false` otherwise
+ * @returns `true` if the string can be parsed as SemVer, `false` otherwise
  */
 export function canParse(version: string): boolean {
   try {
diff --git a/semver/equals.ts b/semver/equals.ts
index 05c2af01ef03..c88817053b9a 100644
--- a/semver/equals.ts
+++ b/semver/equals.ts
@@ -20,8 +20,8 @@ import type { SemVer } from "./types.ts";
  * assertFalse(equals(s0, parse("1.2.4")));
  * ```
  *
- * @param s0 The first version to compare
- * @param s1 The second version to compare
+ * @param s0 The first SemVer to compare
+ * @param s1 The second SemVer to compare
  * @returns `true` if `s0` is equal to `s1`, `false` otherwise
  */
 export function equals(s0: SemVer, s1: SemVer): boolean {
diff --git a/semver/format.ts b/semver/format.ts
index 750c9c0bc26b..935de82d9d30 100644
--- a/semver/format.ts
+++ b/semver/format.ts
@@ -33,7 +33,7 @@ function formatNumber(value: number) {
  * assertEquals(format(semver), "1.2.3");
  * ```
  *
- * @param semver The semantic version to format
+ * @param semver The SemVer to format
  * @returns The string representation of a semantic version.
  */
 export function format(semver: SemVer): string {
diff --git a/semver/greater_than_range.ts b/semver/greater_than_range.ts
index 7df8b7a2c2f2..84958f66e943 100644
--- a/semver/greater_than_range.ts
+++ b/semver/greater_than_range.ts
@@ -7,7 +7,7 @@ import { isWildcardComparator } from "./_shared.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Check if the semver is greater than the range.
+ * Check if the SemVer is greater than the range.
  *
  * @example Usage
  * ```ts
diff --git a/semver/mod.ts b/semver/mod.ts
index 25793a2e0450..d37bfb56c40f 100644
--- a/semver/mod.ts
+++ b/semver/mod.ts
@@ -295,5 +295,5 @@ export * from "./less_than.ts";
 export * from "./less_than_range.ts";
 export * from "./less_or_equal.ts";
 
-/** The semver spec version */
+/** The SemVer spec version */
 export const SEMVER_SPEC_VERSION = "2.0.0";

From 85be160bd30c7639202767a59ef03ac882cd8480 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Fri, 24 May 2024 21:30:38 +0900
Subject: [PATCH 4/8] test(yaml): test handling of omap (#4851)

---
 yaml/_type/omap.ts |  5 -----
 yaml/parse_test.ts | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/yaml/_type/omap.ts b/yaml/_type/omap.ts
index ded6e1e26031..73ab906cb868 100644
--- a/yaml/_type/omap.ts
+++ b/yaml/_type/omap.ts
@@ -35,12 +35,7 @@ function resolveYamlOmap(data: Any): boolean {
   return true;
 }
 
-function constructYamlOmap(data: Any): Any {
-  return data !== null ? data : [];
-}
-
 export const omap = new Type("tag:yaml.org,2002:omap", {
-  construct: constructYamlOmap,
   kind: "sequence",
   resolve: resolveYamlOmap,
 });
diff --git a/yaml/parse_test.ts b/yaml/parse_test.ts
index efc658120afb..d04a9d90f7ca 100644
--- a/yaml/parse_test.ts
+++ b/yaml/parse_test.ts
@@ -271,3 +271,45 @@ Deno.test({
     ]);
   },
 });
+
+Deno.test({
+  name: "parse() handles omap type",
+  fn() {
+    const yaml = `--- !!omap
+- Mark McGwire: 65
+- Sammy Sosa: 63
+- Ken Griffey: 58
+`;
+    assertEquals(parse(yaml), [
+      { "Mark McGwire": 65 },
+      { "Sammy Sosa": 63 },
+      { "Ken Griffey": 58 },
+    ]);
+
+    // Invalid omap
+    // map entry is not an object
+    assertThrows(
+      () => parse("--- !!omap\n- 1"),
+      YAMLError,
+      "cannot resolve a node with !<tag:yaml.org,2002:omap> explicit tag",
+    );
+    // map entry is empty object
+    assertThrows(
+      () => parse("--- !!omap\n- {}"),
+      YAMLError,
+      "cannot resolve a node with !<tag:yaml.org,2002:omap> explicit tag",
+    );
+    // map entry is an object with multiple keys
+    assertThrows(
+      () => parse("--- !!omap\n- foo: 1\n  bar: 2"),
+      YAMLError,
+      "cannot resolve a node with !<tag:yaml.org,2002:omap> explicit tag",
+    );
+    // 2 map entries have the same key
+    assertThrows(
+      () => parse("--- !!omap\n- foo: 1\n- foo: 2"),
+      YAMLError,
+      "cannot resolve a node with !<tag:yaml.org,2002:omap> explicit tag",
+    );
+  },
+});

From d84970f4e9027e299cb923f6d6618e6ee01eae0f Mon Sep 17 00:00:00 2001
From: familyboat <84062528+familyboat@users.noreply.github.com>
Date: Mon, 27 May 2024 12:17:51 +0800
Subject: [PATCH 5/8] docs(encoding): fix typo in `ascii85.ts` (#4854)

---
 encoding/ascii85.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/encoding/ascii85.ts b/encoding/ascii85.ts
index 2ce8c4f20a8d..01611d980603 100644
--- a/encoding/ascii85.ts
+++ b/encoding/ascii85.ts
@@ -49,7 +49,7 @@ const Z85 =
   "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#" as const;
 
 /**
- * Converts data into an ascii58-encoded string.
+ * Converts data into an ascii85-encoded string.
  *
  * @param data The data to encode.
  * @param options Options for encoding.

From a13344338ab0b5636f5d12433e263db8652ecfe9 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Mon, 27 May 2024 14:30:26 +0900
Subject: [PATCH 6/8] docs(data-structures): enables doc lint of
 data-structures (#4847)

---
 _tools/check_docs.ts                  | 1 +
 data_structures/binary_heap.ts        | 2 +-
 data_structures/binary_search_tree.ts | 2 +-
 data_structures/red_black_tree.ts     | 4 +---
 4 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts
index 51f5d8a361b9..a3295f52cdf9 100644
--- a/_tools/check_docs.ts
+++ b/_tools/check_docs.ts
@@ -30,6 +30,7 @@ const ENTRY_POINTS = [
   "../bytes/mod.ts",
   "../cli/mod.ts",
   "../collections/mod.ts",
+  "../data_structures/mod.ts",
   "../datetime/mod.ts",
   "../encoding/mod.ts",
   "../expect/mod.ts",
diff --git a/data_structures/binary_heap.ts b/data_structures/binary_heap.ts
index 7291cdef157a..c522ce3176b8 100644
--- a/data_structures/binary_heap.ts
+++ b/data_structures/binary_heap.ts
@@ -26,7 +26,7 @@ function getParentIndex(index: number) {
  * | pop()       | O(log n)     | O(log n)   |
  * | push(value) | O(1)         | O(log n)   |
  *
- * @example
+ * @example Usage
  * ```ts
  * import {
  *   ascend,
diff --git a/data_structures/binary_search_tree.ts b/data_structures/binary_search_tree.ts
index c72297a46bd1..687e9dc00e4e 100644
--- a/data_structures/binary_search_tree.ts
+++ b/data_structures/binary_search_tree.ts
@@ -24,7 +24,7 @@ type Direction = "left" | "right";
  * | min()         | O(log n)     | O(n)       |
  * | max()         | O(log n)     | O(n)       |
  *
- * @example
+ * @example Usage
  * ```ts
  * import {
  *   BinarySearchTree,
diff --git a/data_structures/red_black_tree.ts b/data_structures/red_black_tree.ts
index 165a57c569fd..d39ec4d49ead 100644
--- a/data_structures/red_black_tree.ts
+++ b/data_structures/red_black_tree.ts
@@ -34,7 +34,7 @@ const {
  * | min()         | O(log n)     | O(log n)   |
  * | max()         | O(log n)     | O(log n)   |
  *
- * @example
+ * @example Usage
  * ```ts
  * import {
  *   ascend,
@@ -101,8 +101,6 @@ const {
  * @typeparam T The type of the values being stored in the tree.
  */
 export class RedBlackTree<T> extends BinarySearchTree<T> {
-  declare protected root: RedBlackNode<T> | null;
-
   /**
    * Construct an empty red-black tree.
    *

From 9a69163ae3fc4789782b80cb9d512662859e2718 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Mon, 27 May 2024 18:49:03 +0900
Subject: [PATCH 7/8] add examples for rangeMin and rangeMax

---
 semver/range_max.ts | 7 ++++++-
 semver/range_min.ts | 7 ++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/semver/range_max.ts b/semver/range_max.ts
index aed009e8c048..d7a5e9c85ca1 100644
--- a/semver/range_max.ts
+++ b/semver/range_max.ts
@@ -48,7 +48,12 @@ function comparatorMax(comparator: Comparator): SemVer {
  *
  * @example Usage
  * ```ts
- * // This API is deprecated
+ * import { parseRange } from "@std/semver/parse-range";
+ * import { rangeMax } from "@std/semver/range-max";
+ * import { equals } from "@std/semver/equals";
+ * import { assert } from "@std/assert/assert";
+ *
+ * assert(equals(rangeMax(parseRange(">1.0.0 <=2.0.0")), { major: 2, minor: 0, patch: 0 }));
  * ```
  *
  * @param range The range to calculate the max for
diff --git a/semver/range_min.ts b/semver/range_min.ts
index fc3aabeac528..7cad146587cf 100644
--- a/semver/range_min.ts
+++ b/semver/range_min.ts
@@ -39,7 +39,12 @@ function comparatorMin(comparator: Comparator): SemVer {
  *
  * @example Usage
  * ```ts
- * // This API is deprecated
+ * import { parseRange } from "@std/semver/parse-range";
+ * import { rangeMin } from "@std/semver/range-min";
+ * import { equals } from "@std/semver/equals";
+ * import { assert } from "@std/assert/assert";
+ *
+ * assert(equals(rangeMin(parseRange(">=1.0.0 <2.0.0")), { major: 1, minor: 0, patch: 0 }));
  * ```
  *
  * @param range The range to calculate the min for

From 1501f1798ab7c94b0ab5c6658983ea23809b5ab8 Mon Sep 17 00:00:00 2001
From: Yoshiya Hinosawa <stibium121@gmail.com>
Date: Mon, 27 May 2024 18:53:58 +0900
Subject: [PATCH 8/8] use SemVer consistently

---
 semver/less_than_range.ts       | 8 ++++----
 semver/less_than_range_test.ts  | 2 +-
 semver/mod.ts                   | 4 ++--
 semver/range_intersects_test.ts | 2 +-
 semver/range_max.ts             | 2 +-
 semver/range_min.ts             | 2 +-
 6 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/semver/less_than_range.ts b/semver/less_than_range.ts
index 529a108836e9..4f3393340eab 100644
--- a/semver/less_than_range.ts
+++ b/semver/less_than_range.ts
@@ -7,7 +7,7 @@ import { isWildcardComparator } from "./_shared.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Check if the semver is less than the range.
+ * Check if the SemVer is less than the range.
  *
  * @example Usage
  * ```ts
@@ -23,7 +23,7 @@ import { compare } from "./compare.ts";
  *
  * @param semver The version to check.
  * @param range The range to check against.
- * @returns `true` if the semver is less than the range, `false` otherwise.
+ * @returns `true` if the SemVer is less than the range, `false` otherwise.
  */
 export function lessThanRange(semver: SemVer, range: Range): boolean {
   return range.every((comparatorSet) =>
@@ -34,9 +34,9 @@ export function lessThanRange(semver: SemVer, range: Range): boolean {
 function lessThanComparatorSet(semver: SemVer, comparatorSet: Comparator[]) {
   // If the comparator set contains wildcard, then the semver is not greater than the range.
   if (comparatorSet.some(isWildcardComparator)) return false;
-  // If the semver satisfies the comparator set, then it's not less than the range.
+  // If the SemVer satisfies the comparator set, then it's not less than the range.
   if (testComparatorSet(semver, comparatorSet)) return false;
-  // If the semver is greater than any of the comparator set, then it's not less than the range.
+  // If the SemVer is greater than any of the comparator set, then it's not less than the range.
   if (
     comparatorSet.some((comparator) =>
       greaterThanComparator(semver, comparator)
diff --git a/semver/less_than_range_test.ts b/semver/less_than_range_test.ts
index 1e89d1ab56b7..792c49684889 100644
--- a/semver/less_than_range_test.ts
+++ b/semver/less_than_range_test.ts
@@ -10,7 +10,7 @@ import {
   parseRange,
 } from "./mod.ts";
 
-Deno.test("lessThanRange() checks if the semver is less than the range", async (t) => {
+Deno.test("lessThanRange() checks if the SemVer is less than the range", async (t) => {
   // From https://github.com/npm/node-semver/blob/692451bd6f75b38a71a99f39da405c94a5954a22/test/fixtures/version-lt-range.js
   const versionLtRange = [
     ["~1.2.2", "1.2.1"],
diff --git a/semver/mod.ts b/semver/mod.ts
index d37bfb56c40f..6bafe17e94d9 100644
--- a/semver/mod.ts
+++ b/semver/mod.ts
@@ -105,8 +105,8 @@
  *
  * Build metadata is `.` delimited alpha-numeric string.
  * When parsing a version it is retained on the `build: string[]` field
- * of the semver instance. When incrementing there is an additional parameter that
- * can set the build metadata on the semver instance.
+ * of the SemVer instance. When incrementing there is an additional parameter that
+ * can set the build metadata on the SemVer instance.
  *
  * ### Advanced Range Syntax
  *
diff --git a/semver/range_intersects_test.ts b/semver/range_intersects_test.ts
index bba913c86808..88095e54b430 100644
--- a/semver/range_intersects_test.ts
+++ b/semver/range_intersects_test.ts
@@ -96,7 +96,7 @@ Deno.test({
       ["<=1.2.0", "<1.3.0", true],
       ["<1.2.0", "<=1.3.0", true],
 
-      // Different directions, same semver and inclusive operator
+      // Different directions, same SemVer and inclusive operator
       [">=1.3.0", "<=1.3.0", true],
       [">=v1.3.0", "<=1.3.0", true],
       [">=1.3.0", ">=1.3.0", true],
diff --git a/semver/range_max.ts b/semver/range_max.ts
index d7a5e9c85ca1..7b6434985195 100644
--- a/semver/range_max.ts
+++ b/semver/range_max.ts
@@ -60,7 +60,7 @@ function comparatorMax(comparator: Comparator): SemVer {
  * @returns A valid SemVer or INVALID
  *
  * @deprecated This will be removed in 1.0.0. Use {@linkcode greaterThanRange} or
- * {@linkcode lessThanRange} for comparing ranges and semvers. The maximum
+ * {@linkcode lessThanRange} for comparing ranges and SemVers. The maximum
  * version of a range is often not well defined, and therefore this API
  * shouldn't be used. See
  * {@link https://github.com/denoland/deno_std/issues/4365} for details.
diff --git a/semver/range_min.ts b/semver/range_min.ts
index 7cad146587cf..5d10739ad878 100644
--- a/semver/range_min.ts
+++ b/semver/range_min.ts
@@ -51,7 +51,7 @@ function comparatorMin(comparator: Comparator): SemVer {
  * @returns A valid SemVer or INVALID
  *
  * @deprecated This will be removed in 1.0.0. Use {@linkcode greaterThanRange} or
- * {@linkcode lessThanRange} for comparing ranges and semvers. The minimum
+ * {@linkcode lessThanRange} for comparing ranges and SemVers. The minimum
  * version of a range is often not well defined, and therefore this API
  * shouldn't be used. See
  * {@link https://github.com/denoland/deno_std/issues/4365} for details.