feat: add JSDoc exercises and solutions for function documentation

- Introduce new exercises focused on writing JSDoc comments for functions, enhancing documentation skills.
- Add corresponding solution files demonstrating proper JSDoc usage for various functions.
- Update package-lock.json to include new exercise and solution modules.
- Enhance README files to provide context and guidance on JSDoc usage and best practices.

Author: kentcdodds

exercises/05.functions/05.problem.jsdoc/README.mdx

@@ -0,0 +1,50 @@
+# JSDoc Documentation
+
+👨‍💼 Code without documentation is like a recipe without instructions—technically
+all the ingredients are there, but good luck figuring out how to use them!
+
+JSDoc is a documentation format that lives in special comments above your
+functions. The best part? TypeScript and your IDE understand JSDoc, so your
+documentation shows up in tooltips and autocomplete.
+
+```ts
+/**
+ * Calculates the area of a rectangle.
+ * @param width - The width of the rectangle
+ * @param height - The height of the rectangle
+ * @returns The area in square units
+ * @example
+ * const area = calculateArea(5, 10)
+ * console.log(area) // 50
+ */
+function calculateArea(width: number, height: number): number {
+	return width * height
+}
+```
+
+When you hover over `calculateArea` anywhere in your codebase, you'll see this
+documentation!
+
+## Common JSDoc Tags
+
+| Tag        | Purpose                            |
+| ---------- | ---------------------------------- |
+| `@param`   | Documents a function parameter     |
+| `@returns` | Documents what the function returns|
+| `@example` | Shows how to use the function      |
+| `@throws`  | Documents errors the function throws|
+| `@see`     | Links to related documentation     |
+
+🐨 Open <InlineFile file="index.ts" /> and add JSDoc comments to each function.
+
+💰 The description goes right after the opening `/**`:
+
+```ts
+/**
+ * This is the description that explains what the function does.
+ * It can span multiple lines.
+ * @param name - Description of the parameter
+ */
+```
+
+📜 [JSDoc Reference](https://jsdoc.app/)

exercises/05.functions/05.problem.jsdoc/index.ts

@@ -0,0 +1,48 @@
+// JSDoc Documentation
+// Writing documentation comments that enhance IDE support and code clarity
+
+// 🐨 Add a JSDoc comment above this function that includes:
+// - A description of what the function does
+// - @param tag documenting the `a` parameter
+// - @param tag documenting the `b` parameter
+// - @returns tag documenting what the function returns
+// 💰 JSDoc comments start with /** and end with */
+function add(a: number, b: number): number {
+	return a + b
+}
+
+// 🐨 Add a JSDoc comment for this function that includes:
+// - A description
+// - @param tag for the `name` parameter
+// - @returns tag
+// - @example tag showing how to use the function
+// 💰 @example tags let you show usage:
+// @example
+// const result = greet('Alice')
+// console.log(result) // "Hello, Alice!"
+function greet(name: string): string {
+	return `Hello, ${name}!`
+}
+
+// 🐨 Add a JSDoc comment for this function that includes:
+// - A description explaining what the function calculates
+// - @param tag for `principal` (the initial amount)
+// - @param tag for `rate` (annual interest rate as decimal)
+// - @param tag for `years` (number of years)
+// - @returns tag explaining the result
+// - @example tag showing typical usage
+function calculateCompoundInterest(
+	principal: number,
+	rate: number,
+	years: number,
+): number {
+	return principal * Math.pow(1 + rate, years)
+}
+
+// 🐨 Create a function called `clamp` that:
+// - Takes a value, min, and max
+// - Returns the value constrained between min and max
+// - Has a complete JSDoc comment with description, @param, @returns, and @example
+// 💰 Math.max(min, Math.min(max, value)) will clamp a value
+
+export { add, greet, calculateCompoundInterest }

exercises/05.functions/05.problem.jsdoc/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "exercises_05.functions_05.problem.jsdoc",
+  "type": "module",
+  "scripts": {
+    "start": "node index.ts",
+    "test": "node --test index.test.ts"
+  }
+}

exercises/05.functions/05.solution.jsdoc/README.mdx

@@ -0,0 +1,38 @@
+# JSDoc Documentation
+
+👨‍💼 Excellent work! Your functions now have professional documentation.
+
+🦉 Key takeaways about JSDoc:
+
+1. **IDE Integration** - When you hover over a documented function, you'll see
+   the description, parameters, return type, and examples right in your editor
+2. **Self-Documenting Code** - Good JSDoc makes code easier to understand
+   without reading the implementation
+3. **`@example` is powerful** - Examples show how to actually use the function,
+   which is often clearer than a description
+
+```ts
+/**
+ * Constrains a value to be within a specified range.
+ * @param value - The value to clamp
+ * @param min - The minimum allowed value
+ * @param max - The maximum allowed value
+ * @returns The clamped value between min and max
+ * @example
+ * clamp(15, 0, 10)  // returns 10
+ * clamp(-5, 0, 10)  // returns 0
+ */
+function clamp(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, value))
+}
+```
+
+While TypeScript gives you type information automatically, JSDoc adds the
+*human* context: what does this function actually do? When should I use it?
+What do the numbers mean?
+
+📝 For your own projects, consider adding JSDoc to:
+
+- Public API functions
+- Complex utility functions
+- Functions with non-obvious parameter meanings

exercises/05.functions/05.solution.jsdoc/index.test.ts

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { add, greet, calculateCompoundInterest, clamp } from './index.ts'
+
+await test('add has JSDoc comment', () => {
+	const source = add.toString()
+	// Function should work correctly
+	assert.strictEqual(add(2, 3), 5, '🚨 add(2, 3) should return 5')
+	assert.strictEqual(add(-1, 1), 0, '🚨 add(-1, 1) should return 0')
+})
+
+await test('greet has JSDoc comment and works correctly', () => {
+	assert.strictEqual(
+		greet('Alice'),
+		'Hello, Alice!',
+		'🚨 greet("Alice") should return "Hello, Alice!"',
+	)
+	assert.strictEqual(
+		greet('World'),
+		'Hello, World!',
+		'🚨 greet("World") should return "Hello, World!"',
+	)
+})
+
+await test('calculateCompoundInterest works correctly', () => {
+	// $1000 at 5% for 10 years = $1000 * (1.05)^10 ≈ $1628.89
+	const result = calculateCompoundInterest(1000, 0.05, 10)
+	assert.ok(
+		Math.abs(result - 1628.89) < 0.1,
+		`🚨 calculateCompoundInterest(1000, 0.05, 10) should be approximately 1628.89, got ${result}`,
+	)
+
+	// $100 at 10% for 1 year = $110
+	const simpleResult = calculateCompoundInterest(100, 0.1, 1)
+	assert.ok(
+		Math.abs(simpleResult - 110) < 0.01,
+		`🚨 calculateCompoundInterest(100, 0.1, 1) should be approximately 110, got ${simpleResult}`,
+	)
+})
+
+await test('clamp constrains values correctly', () => {
+	// Value above max should return max
+	assert.strictEqual(
+		clamp(15, 0, 10),
+		10,
+		'🚨 clamp(15, 0, 10) should return 10 (value above max)',
+	)
+
+	// Value below min should return min
+	assert.strictEqual(
+		clamp(-5, 0, 10),
+		0,
+		'🚨 clamp(-5, 0, 10) should return 0 (value below min)',
+	)
+
+	// Value within range should return unchanged
+	assert.strictEqual(
+		clamp(5, 0, 10),
+		5,
+		'🚨 clamp(5, 0, 10) should return 5 (value within range)',
+	)
+
+	// Edge cases
+	assert.strictEqual(
+		clamp(0, 0, 10),
+		0,
+		'🚨 clamp(0, 0, 10) should return 0 (value at min)',
+	)
+	assert.strictEqual(
+		clamp(10, 0, 10),
+		10,
+		'🚨 clamp(10, 0, 10) should return 10 (value at max)',
+	)
+})

exercises/05.functions/05.solution.jsdoc/index.ts

@@ -0,0 +1,65 @@
+// JSDoc Documentation
+// Writing documentation comments that enhance IDE support and code clarity
+
+/**
+ * Adds two numbers together.
+ * @param a - The first number to add
+ * @param b - The second number to add
+ * @returns The sum of a and b
+ */
+function add(a: number, b: number): number {
+	return a + b
+}
+
+/**
+ * Creates a greeting message for a person.
+ * @param name - The name of the person to greet
+ * @returns A greeting string
+ * @example
+ * const result = greet('Alice')
+ * console.log(result) // "Hello, Alice!"
+ */
+function greet(name: string): string {
+	return `Hello, ${name}!`
+}
+
+/**
+ * Calculates compound interest on a principal amount.
+ * @param principal - The initial amount of money
+ * @param rate - The annual interest rate as a decimal (e.g., 0.05 for 5%)
+ * @param years - The number of years to compound
+ * @returns The final amount after compound interest
+ * @example
+ * const result = calculateCompoundInterest(1000, 0.05, 10)
+ * console.log(result) // 1628.89 (approximately)
+ */
+function calculateCompoundInterest(
+	principal: number,
+	rate: number,
+	years: number,
+): number {
+	return principal * Math.pow(1 + rate, years)
+}
+
+/**
+ * Constrains a value to be within a specified range.
+ * @param value - The value to clamp
+ * @param min - The minimum allowed value
+ * @param max - The maximum allowed value
+ * @returns The clamped value between min and max
+ * @example
+ * clamp(15, 0, 10)  // returns 10
+ * clamp(-5, 0, 10)  // returns 0
+ * clamp(5, 0, 10)   // returns 5
+ */
+function clamp(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, value))
+}
+
+// Test the functions
+console.log(add(2, 3)) // 5
+console.log(greet('World')) // "Hello, World!"
+console.log(calculateCompoundInterest(1000, 0.05, 10)) // ~1628.89
+console.log(clamp(15, 0, 10)) // 10
+
+export { add, greet, calculateCompoundInterest, clamp }

exercises/05.functions/05.solution.jsdoc/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "exercises_05.functions_05.solution.jsdoc",
+  "type": "module",
+  "scripts": {
+    "start": "node index.ts",
+    "test": "node --test index.test.ts"
+  }
+}