05./05. (πŸ’ͺ)

JSDoc Documentation

Jsdoc
Jsdoc
πŸ‘¨β€πŸ’Ό 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.
/**
 * 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!
Since TypeScript already provides type information (parameter types, return types), JSDoc is primarily useful for descriptions and examples in TypeScript projects. The @param and @returns tags add human-readable explanations that go beyond what types alone can convey.

Common JSDoc Tags

TagPurpose
@paramDocuments a function parameter
@returnsDocuments what the function returns
@exampleShows how to use the function
@throwsDocuments errors the function throws
@seeLinks to related documentation
🐨 Open
index.ts
and:
  1. Add JSDoc above add with a description, @param for a and b, and @returns
  2. Add JSDoc above greet with a description, @param for name, @returns, and an @example
  3. Add JSDoc above calculateCompoundInterest documenting principal, rate (decimal), years, @returns, and an @example
  4. Create and export clamp(value: number, min: number, max: number): number that returns:
    • min when value is below min
    • max when value is above max
    • value when it is already between min and max (inclusive)
  5. Give clamp complete JSDoc (description, @param, @returns, @example)

Required exports

add, greet, calculateCompoundInterest, clamp

Completion criteria

Automated tests verify behavior (not the JSDoc text itself):
  • add(2, 3) β†’ 5; add(-1, 1) β†’ 0
  • greet('Alice') β†’ "Hello, Alice!"
  • calculateCompoundInterest(1000, 0.05, 10) β‰ˆ 1628.89
  • calculateCompoundInterest(100, 0.1, 1) β‰ˆ 110
  • clamp(15, 0, 10) β†’ 10; clamp(-5, 0, 10) β†’ 0; clamp(5, 0, 10) β†’ 5; clamp(0, 0, 10) β†’ 0; clamp(10, 0, 10) β†’ 10
For the learning goal: hover each function in your editor and confirm the JSDoc appears in the tooltip.
Some functions in this exercise use built-in Math helpers for powers and for choosing the larger/smaller of two numbers when clamping a value into a range.
πŸ’° Put a brief description immediately after the opening /**.
Edit
problemsolutiondiffchat

Please set the playground first

Loading "JSDoc Documentation"
Loading "JSDoc Documentation"