docs(semver): minor documentation cleanups (#5178)

* docs(semver): minor documentation cleanups

* fix

semver/compare.ts

@@ -8,12 +8,12 @@ import {
 } from "./_shared.ts";
 
 /**
- * Compare two semantic version objects.
+ * Compare two SemVers.
  *
  * Returns `0` if `s0 === s1`, or `1` if `s0` is greater, or `-1` if `s1` is
  * greater.
  *
- * Sorts in ascending order if passed to `Array.sort()`,
+ * Sorts in ascending order if passed to {@linkcode Array.sort}.
  *
  * @example Usage
  * ```ts

semver/difference.ts

@@ -4,8 +4,8 @@ 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 SemVers by the release type,
+ * or `undefined` if the SemVers are the same.
  *
  * @example Usage
  * ```ts

semver/equals.ts

@@ -4,20 +4,20 @@ import { compare } from "./compare.ts";
 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.
+ * Returns `true` if both SemVers are equivalent.
  *
  * This is equal to `compare(s0, s1) === 0`.
  *
  * @example Usage
  * ```ts
  * import { parse, equals } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } 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")));
+ * assert(!equals(s0, parse("1.2.4")));
  * ```
  *
  * @param s0 The first SemVer to compare

semver/format.ts

@@ -16,7 +16,7 @@ function formatNumber(value: number) {
 /**
  * Format a SemVer object into a string.
  *
- * If any number is NaN then NaN will be printed.
+ * If any number is {@linkcode NaN}, then `NaN` will be printed.
  *
  * If any number is positive or negative infinity then '∞' or '⧞' will be printed instead.
  *

semver/format_range.ts

@@ -9,7 +9,8 @@ function formatComparator(comparator: Comparator): string {
 }
 
 /**
- * Formats the range into a string
+ * Formats the SemVerrange into a string.
+ *
  * @example Usage
  * ```ts
  * import { formatRange, parseRange } from "@std/semver";
@@ -20,7 +21,7 @@ function formatComparator(comparator: Comparator): string {
  * ```
  *
  * @param range The range to format
- * @returns A string representation of the range
+ * @returns A string representation of the SemVer range
  */
 export function formatRange(range: Range): string {
   return range.map((c) => c.map((c) => formatComparator(c)).join(" "))

semver/greater_or_equal.ts

@@ -4,19 +4,20 @@ import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Greater than or equal to comparison
+ * Greater than or equal to comparison for two SemVers.
  *
  * This is equal to `compare(s0, s1) >= 0`.
  *
  * @example Usage
  * ```ts
  * import { parse, greaterOrEqual } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/assert";
  *
  * const s0 = parse("1.2.3");
  * const s1 = parse("1.2.4");
+ *
  * assert(greaterOrEqual(s1, s0));
- * assertFalse(greaterOrEqual(s0, s1));
+ * assert(!greaterOrEqual(s0, s1));
  * assert(greaterOrEqual(s0, s0));
  * ```
  *

semver/greater_than.ts

@@ -5,20 +5,21 @@ import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Greater than comparison
+ * Greater than comparison for two SemVers.
  *
  * This is equal to `compare(s0, s1) > 0`.
  *
  * @example Usage
  * ```ts
  * import { parse, greaterThan } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/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));
+ * assert(!greaterThan(s0, s1));
+ * assert(!greaterThan(s0, s0));
  * ```
  *
  * @param s0 The first version to compare

semver/greater_than_range.ts

@@ -12,12 +12,13 @@ import { compare } from "./compare.ts";
  * @example Usage
  * ```ts
  * import { parse, parseRange, greaterThanRange } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/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(v0, range));
  * assert(greaterThanRange(v1, range));
  * ```
  *

semver/increment.ts

@@ -36,7 +36,7 @@ function bumpPrerelease(
 }
 
 /**
- * Returns the new version resulting from an increment by release type.
+ * Returns the new SemVer resulting from an increment by release type.
  *
  * `premajor`, `preminor` and `prepatch` will bump the version up to the next version,
  * based on the type, and will also add prerelease metadata.

semver/is_range.ts

@@ -30,11 +30,11 @@ function isComparator(value: unknown): value is Comparator {
  * @example Usage
  * ```ts
  * import { isRange } from "@std/semver/is-range";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/assert";
  *
  * const range = [[{ major: 1, minor: 2, patch: 3 }]];
  * assert(isRange(range));
- * assertFalse(isRange({}));
+ * assert(!isRange({}));
  * ```
  * @param value The value to check if its a valid Range
  * @returns True if its a valid Range otherwise false.

semver/is_semver.ts

@@ -20,7 +20,7 @@ import { isValidNumber, isValidString } from "./_shared.ts";
  * @example Usage
  * ```ts
  * import { isSemVer } from "@std/semver/is-semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/assert";
  *
  * const value = {
  *   major: 1,
@@ -29,7 +29,7 @@ import { isValidNumber, isValidString } from "./_shared.ts";
  * };
  *
  * assert(isSemVer(value));
- * assertFalse(isSemVer({ major: 1, minor: 2 }));
+ * assert(!isSemVer({ major: 1, minor: 2 }));
  * ```
  *
  * @param value The value to check to see if its a valid SemVer object

semver/less_or_equal.ts

@@ -4,19 +4,20 @@ import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Less than or equal to comparison
+ * Less than or equal to comparison for two SemVers.
  *
  * This is equal to `compare(s0, s1) <= 0`.
  *
  * @example Usage
  * ```ts
  * import { parse, lessOrEqual } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/assert";
  *
  * const s0 = parse("1.2.3");
  * const s1 = parse("1.2.4");
+ *
  * assert(lessOrEqual(s0, s1));
- * assertFalse(lessOrEqual(s1, s0));
+ * assert(!lessOrEqual(s1, s0));
  * assert(lessOrEqual(s0, s0));
  * ```
  *

semver/less_than.ts

@@ -4,20 +4,21 @@ import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Less than comparison
+ * Less than comparison for two SemVers.
  *
  * This is equal to `compare(s0, s1) < 0`.
  *
  * @example Usage
  * ```ts
  * import { parse, lessThan } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/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));
+ * assert(!lessThan(s1, s0));
+ * assert(!lessThan(s0, s0));
  * ```
  *
  * @param s0 the first version to compare

semver/less_than_range.ts

@@ -12,12 +12,13 @@ import { compare } from "./compare.ts";
  * @example Usage
  * ```ts
  * import { parse, parseRange, lessThanRange } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/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(v0, range));
  * assert(lessThanRange(v1, range));
  * ```
  *

semver/max_satisfying.ts

@@ -5,7 +5,7 @@ import { satisfies } from "./satisfies.ts";
 import { greaterThan } from "./greater_than.ts";
 
 /**
- * Returns the highest version in the list that satisfies the range, or `undefined`
+ * Returns the highest SemVer in the list that satisfies the range, or `undefined`
  * if none of them do.
  *
  * @example Usage

semver/min_satisfying.ts

@@ -5,7 +5,7 @@ import { satisfies } from "./satisfies.ts";
 import { lessThan } from "./less_than.ts";
 
 /**
- * Returns the lowest version in the list that satisfies the range, or `undefined` if
+ * Returns the lowest SemVer in the list that satisfies the range, or `undefined` if
  * none of them do.
  *
  * @example Usage

semver/mod.ts

@@ -68,11 +68,11 @@
  *
  * ## Ranges
  *
- * A `version range` is a set of `comparators` which specify versions that satisfy
- * the range.
+ * A version {@linkcode Range} is a set of {@linkcode Comparator}s which specify
+ * versions that satisfy the range.
  *
- * A `comparator` is composed of an `operator` and a `version`. The set of
- * primitive `operators` is:
+ * A {@linkcode Comparator} is composed of an {@linkcode Operator} and a
+ * {@link SemVer}. The set of primitive `operators` is:
  *
  * - `<` Less than
  * - `<=` Less than or equal to
@@ -123,12 +123,14 @@
  *
  * #### Prerelease Identifiers
  *
- * The method `.increment` takes an additional `identifier` string argument that
- * will append the value of the string as a prerelease identifier:
+ * The method {@linkcode increment} takes an additional `identifier` string
+ * argument that will append the value of the string as a prerelease identifier:
  *
- * ```javascript
- * semver.increment(parse("1.2.3"), "prerelease", "beta");
- * // "1.2.4-beta.0"
+ * ```ts
+ * import { increment, parse } from "@std/semver";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * assertEquals(increment(parse("1.2.3"), "prerelease", "alpha"), parse("1.2.4-alpha.0"));
  * ```
  *
  * ### Build Metadata
@@ -269,10 +271,6 @@
  *
  * If you want to know if a version satisfies or does not satisfy a range, use the
  * {@linkcode satisfies} function.
- *
- *
- *
-
  *
  * @module
  */

semver/not_equals.ts

@@ -4,19 +4,20 @@ import type { SemVer } from "./types.ts";
 import { compare } from "./compare.ts";
 
 /**
- * Not equal comparison
+ * Not equal comparison for two SemVers.
  *
  * This is equal to `compare(s0, s1) !== 0`.
  *
  * @example Usage
  * ```ts
  * import { parse, notEquals } from "@std/semver";
- * import { assert, assertFalse } from "@std/assert";
+ * import { assert } from "@std/assert/assert";
  *
  * const s0 = parse("1.2.3");
  * const s1 = parse("1.2.4");
+ *
  * assert(notEquals(s0, s1));
- * assertFalse(notEquals(s0, s0));
+ * assert(!notEquals(s0, s0));
  * ```
  *
  * @param s0 The first version to compare

semver/parse.ts

@@ -5,8 +5,7 @@ import { parseBuild, parseNumber, parsePrerelease } from "./_shared.ts";
 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.
+ * Attempt to parse a string as a semantic version, returning a SemVer object.
  *
  * @example Usage
  * ```ts
@@ -23,6 +22,7 @@ import { FULL_REGEXP, MAX_LENGTH } from "./_shared.ts";
  * });
  * ```
  *
+ * @throws {TypeError} If the input string is invalid.
  * @param version The version string to parse
  * @returns A valid SemVer
  */

semver/parse_range.ts

@@ -380,7 +380,7 @@ function parseOperatorRanges(string: string): Comparator[] {
 }
 
 /**
- * Parses a range string into a Range object or throws a TypeError.
+ * Parses a range string into a {@linkcode Range} object.
  *
  * @example Usage
  * ```ts
@@ -399,8 +399,9 @@ function parseOperatorRanges(string: string): Comparator[] {
  * ]);
  * ```
  *
+ * @throws {TypeError} If the input range is invalid.
  * @param range The range set string
- * @returns A valid semantic range
+ * @returns A valid SemVer range
  */
 export function parseRange(range: string): Range {
   return range