doc: improve jsdoc

Author: markusberg

.github/workflows/master.yaml

@@ -2,7 +2,7 @@ name: Node.js 24.x build
 
 on:
   push:
-    branches: [master, feat/v3.0.1]
+    branches: [master, release/**]
 
 jobs:
   build:

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.0.2] - 2025-10-18
+
+- Improve JSDoc documentation
+- Remove last vitest reference from README.md
+
+## [3.0.1] - 2025-09-28
+
+- Remove references to vitest from README.md
+
 ## [3.0.0] - 2025-09-21
 
 - feat: minimum required version of Node.Js is 20.x

README.md

@@ -71,7 +71,7 @@ console.log(verify(plaintextPassword, sha256))
 
 ## Test
 
-The tests are written with the built-in [node:assert](https://nodejs.org/api/assert.html) module, using the [vitest](https://vitest.dev/) test runner.
+The tests are written with the built-in [node:assert](https://nodejs.org/api/assert.html) module, and are run in the Node.Js test runner. The test runner didn't get good enough coverage reporting until v24, so that's the reason for the minimum required version of v24 for building and testing.
 
 ```sh
 $ npm test

package.json

@@ -1,6 +1,6 @@
 {
   "name": "unixcrypt",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Node.js implementation of Unixcrypt, specifically SHA-256 and SHA-512",
   "type": "module",
   "exports": {

src/index.ts

@@ -325,22 +325,42 @@ function bufferToBase64(buf: Buffer): string {
 }
 
 /**
- * Create sha256 or sha512 crypt of plaintext password
- * @param plaintext The plaintext password
- * @param salt optional salt, for example "$6$salt" or "$6$rounds=10000$salt"
+ * Create a SHA-256 or SHA-512 hash of a plaintext password using the unixcrypt format.
+ *
+ * @param plaintext - The password to encrypt
+ * @param salt - Optional salt string in Unix crypt format. Examples:
+ *   - "$6$salt" - Use SHA-512 with default rounds
+ *   - "$6$rounds=10000$salt" - Use SHA-512 with 10000 rounds
+ *   - "$5$salt" - Use SHA-256 with default rounds
+ *   If omitted, generates SHA-512 hash with random salt
+ * @returns The complete hash string in Unix crypt format
+ * @example
+ * // Generate SHA-512 hash with random salt
+ * encrypt("mypassword")
+ * // -> "$6$WHT0QXyF$LQv3c1yqBWVHxkd0LHAkC..."
+ *
+ * // Generate SHA-512 hash with specific salt and rounds
+ * encrypt("mypassword", "$6$rounds=10000$saltvalue")
+ * // -> "$6$rounds=10000$saltvalue$LQv3c1yq..."
  */
-function encrypt(plaintext: string, salt?: string): string {
+export function encrypt(plaintext: string, salt?: string): string {
   const conf = parseSalt(salt)
   const hash = generateHash(plaintext, conf)
   return normalizeSalt(conf) + "$" + hash
 }
 
 /**
- * Verify plaintext password against expected hash
- * @param plaintext The plaintext password
- * @param hash The expected hash
+ * Verify a plaintext password against an existing unixcrypt hash.
+ *
+ * @param plaintext - The password to verify
+ * @param hash - The complete hash string to verify against (including salt and rounds)
+ * @returns True if the plaintext matches the hash, false otherwise
+ * @example
+ * // Verify password against hash
+ * verify("mypassword", "$6$WHT0QXyF$LQv3c1yqBWVHxkd0LHAkC...")
+ * // -> true or false
  */
-function verify(plaintext: string, hash: string): boolean {
+export function verify(plaintext: string, hash: string): boolean {
   const salt = hash.slice(0, hash.lastIndexOf("$"))
   const computedHash = encrypt(plaintext, salt)
 
@@ -349,5 +369,3 @@ function verify(plaintext: string, hash: string): boolean {
     Buffer.from(hash, "utf8"),
   )
 }
-
-export { encrypt, verify }