docs(semver): improve docs (#4846)

Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>

_tools/check_docs.ts

@@ -38,6 +38,7 @@ const ENTRY_POINTS = [
   "../internal/mod.ts",
   "../jsonc/mod.ts",
   "../media_types/mod.ts",
+  "../semver/mod.ts",
   "../text/mod.ts",
   "../ulid/mod.ts",
   "../webgpu/mod.ts",

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/can-parse";
+ * 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);

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,

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;

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 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 {
   return compare(s0, s1) === 0;

semver/format.ts

@@ -20,7 +20,20 @@ function formatNumber(value: number) {
  *
  * If any number is positive or negative infinity then '∞' or '⧞' will be printed instead.
  *
- * @param semver The semantic version to format
+ * @example Usage
+ * ```ts
+ * import { format } from "@std/semver/format";
+ * import { assertEquals } from "@std/assert/assert-equals";
+ *
+ * const semver = {
+ *   major: 1,
+ *   minor: 2,
+ *   patch: 3,
+ * };
+ * assertEquals(format(semver), "1.2.3");
+ * ```
+ *
+ * @param semver The SemVer to format
  * @returns The string representation of a semantic version.
  */
 export function format(semver: SemVer): string {

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
  */

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;

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;

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)

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,

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/is-range";
+ * 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.
  */

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/is-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
  */

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;

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;

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)
@@ -16,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)

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"],