docs: improve JSDoc for version comparison methods

.changeset/palette-docs-update.md

@@ -0,0 +1,5 @@
+---
+"node-version": patch
+---
+
+Improve JSDoc comments for version comparison methods to clarify strict equality and invalid input handling.

.jules/palette.md

@@ -0,0 +1,3 @@
+## 2026-01-03 - [Defining UX for Libraries]
+**Learning:** For backend libraries with no UI, "User Experience" (UX) translates directly to "Developer Experience" (DX). Improvements to JSDoc, error messages, and type definitions are valid UX enhancements.
+**Action:** When working on non-UI repositories, focus on API clarity, documentation links, and fail-closed/safe behavior descriptions in JSDoc.

src/index.ts

@@ -11,6 +11,7 @@ export type { NodeVersion };
 
 /**
  * End-of-Life dates for Node.js major versions.
+ * @see https://github.com/nodejs/release#release-schedule
  */
 export const EOL_DATES: Record<string, string> = {
     "18": "2025-04-30",

src/types.ts

@@ -35,39 +35,41 @@ export interface NodeVersion {
     /**
      * Check if the current Node version is at least the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version >= target version.
+     * @returns {boolean} True if current version >= target version. Returns false for invalid version strings.
      * @example
      * version.isAtLeast('18.0.0'); // true if current is 20.0.0
      */
     isAtLeast(version: string): boolean;
     /**
      * Check if the current Node version matches the specified version.
+     * Note: This performs a strict equality check and does NOT normalize 'v' prefixes.
      * @param version The version to compare against (e.g., '20.0.0').
      * @returns {boolean} True if current version === target version.
      * @example
      * version.is('20.0.0'); // true if current is 20.0.0
+     * version.is('v20.0.0'); // false if current is 20.0.0
      */
     is(version: string): boolean;
     /**
      * Check if the current Node version is strictly greater than the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version > target version.
+     * @returns {boolean} True if current version > target version. Returns false for invalid version strings.
      * @example
      * version.isAbove('18.0.0'); // true if current is 20.0.0
      */
     isAbove(version: string): boolean;
     /**
      * Check if the current Node version is strictly less than the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version < target version.
+     * @returns {boolean} True if current version < target version. Returns false for invalid version strings.
      * @example
      * version.isBelow('22.0.0'); // true if current is 20.0.0
      */
     isBelow(version: string): boolean;
     /**
      * Check if the current Node version is at most the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version <= target version.
+     * @returns {boolean} True if current version <= target version. Returns false for invalid version strings.
      * @example
      * version.isAtMost('22.0.0'); // true if current is 20.0.0
      */