Documenting Javascript with JSDocs (Crash Course)

The document is a crash course on using JSDocs to document JavaScript code. It covers installation via npm, basic usage of JSDocs comments, and more

Crash Course on JSDoc and Using It with Svelte 5

JSDoc is a markup language used to annotate JavaScript source code files. It allows developers to add documentation directly in their code, which can then be used by IDEs for autocompletion, type checking, and generating documentation.

Installing JSDoc

npm install -g jsdoc

Basic JSDoc Syntax

JSDoc comments start with /** and end with */. They are placed immediately before the code they document.

/**
 * Adds two numbers
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 */
function add(a, b) {
  return a + b;
}

Common JSDoc Tags

• @param: Describes a function parameter

• @returns: Describes the return value of a function

• @type: Specifies the type of a variable or property

• @typedef: Defines a custom type

Using JSDoc with Svelte 5

In Svelte 5, you can use JSDoc to document and type-check your components, including props and state. Here's how:

Documenting Props

<script>
/**
 * @typedef {Object} Props
 * @property {string} name - The user's name
 * @property {number} age - The user's age
 */

/** @type {Props} */
let { name, age } = $props();
</script>

Documenting State

<script>
/** @type {number} */
let count = $state(0);

/**
 * Increments the count
 * @returns {void}
 */
function increment() {
  count++;
}
</script>

Documenting Derived Values

<script>
/** @type {string} */
let firstName = $state('John');

/** @type {string} */
let lastName = $state('Doe');

/**
 * @type {string}
 */
let fullName = $derived(`${firstName} ${lastName}`);
</script>

Documenting Effects

<script>
/** @type {number} */
let count = $state(0);

$effect(() => {
  /**
   * Logs the current count
   * @returns {void}
   */
  function logCount() {
    console.log(`Count is now: ${count}`);
  }
  
  logCount();
});
</script>

Showing Samples with JSDoc

To show code samples using JSDoc in Svelte 5, you can use the @example tag within your JSDoc comments. Here's how to effectively use it:

For Component Documentation

/**
 * A component that displays a todo item
 * @component
 * @example
 * ```svelte
 * <TodoItem text="Buy groceries" completed={false} />
 * ```
 */

For Function Documentation

/**
 * Adds a new todo item to the list
 * @param {string} text - The text of the todo item
 * @returns {void}
 * @example
 * ```js
 * addTodo("Finish project");
 * ```
 */
function addTodo(text) {
  // Function implementation
}

For Prop Documentation

<script>
/**
 * @typedef {Object} Props
 * @property {string} text - The text of the todo item
 * @property {boolean} [completed=false] - Whether the todo is completed
 */

/** @type {Props} */
let { text, completed = false } = $props();
</script>

For State Documentation

<script>
/**
 * @type {string[]}
 * @example
 * ```js
 * todos = ["Buy milk", "Walk the dog"];
 * ```
 */
let todos = $state([]);
</script>

For Derived Values

<script>
/**
 * @type {number}
 * @example
 * ```js
 * // If todos has 3 items, completedCount will be 2
 * todos = [
 *   { text: "Task 1", completed: true },
 *   { text: "Task 2", completed: true },
 *   { text: "Task 3", completed: false }
 * ];
 * ```
 */
let completedCount = $derived(todos.filter(todo => todo.completed).length);
</script>

By using these JSDoc comments in your Svelte 5 components, you'll get improved autocompletion, type checking, and inline documentation in your IDE. This makes your code more maintainable and easier to understand for other developers (or yourself in the future).

Remember to use markdown code blocks (svelte or js) within the @example tags to properly format your code samples. This will ensure they are displayed correctly in generated documentation and IDE tooltips.

By consistently using JSDoc comments with examples throughout your Svelte 5 project, you'll create a more robust and developer-friendly codebase.