Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

JSDoc comments in the TypeScript ecosystem are structured, multi-line block comments beginning with /** and ending with */ that the TypeScript compiler parses to extract type information, metadata, and documentation. The TypeScript compiler (TSC) and Language Server map these annotations directly to internal Abstract Syntax Tree (AST) nodes, utilizing them to infer types, provide IntelliSense, and enforce static type checking. Because TypeScript explicitly ignores JSDoc type annotations in .ts files in favor of standard static typing syntax, these JSDoc type annotations are primarily parsed and enforced by the compiler when processing standard JavaScript (.js) files. By default, this enforcement is disabled; developers must explicitly activate type checking in JavaScript files by enabling the checkJs compiler option in tsconfig.json or by inserting a // @ts-check directive at the top of the file.

​
Syntax Anatomy

A valid JSDoc comment must start with exactly two asterisks (/**). Single asterisk blocks (/*) are treated as standard block comments and are ignored by the TypeScript type checker. 
/**
 * Description of the symbol.
 * 
 * @tagName {TypeAnnotation} identifier - Description of the tag.
 */

​
Core Type Annotations

TypeScript supports a specific subset of JSDoc tags, mapping them directly to TypeScript’s type system.

​
Variables and Properties (@type)

The @type tag assigns a specific TypeScript type to a variable, property, or expression. It supports standard TypeScript type syntax, including unions, intersections, and utility types. 
/** @type {string | number} */
let primitiveOrString;

/** @type {Partial<HTMLInputElement>} */
const elementConfig = {};

​
Inline Type Assertions

In JavaScript files, TypeScript allows JSDoc to be used for inline type casting (assertions) by wrapping the target expression in parentheses immediately following the @type annotation. If used in a .ts file, the TypeScript compiler treats it as a standard comment and ignores it. 
const canvas = /** @type {HTMLCanvasElement} */ (document.getElementById("canvas"));

​
Function Signatures (@param, @returns)

Function parameters and return types are defined using @param and @returns. Optional parameters are denoted by wrapping the parameter name in square brackets []. TypeScript enforces that required parameters cannot follow optional parameters. 
/**
 * @param {string} target
 * @param {Record<string, any>} config
 * @param {number} [timeout] - Optional parameter
 * @returns {Promise<boolean>}
 */
async function initialize(target, config, timeout) {
  // ...
}

​
Type Aliases and Object Shapes (@typedef, @property)

The @typedef tag creates a custom type alias, equivalent to the type keyword in TypeScript. The @property tag defines the shape of object types. 
/**
 * @typedef {Object} User
 * @property {number} id
 * @property {string} username
 * @property {string[]} [roles]
 */

/** @type {User} */
const currentUser = { id: 1, username: "admin" };

​
Generics (@template)

The @template tag declares type parameters, enabling generic programming within JSDoc. Constraints are defined by placing the constraint type inside curly braces before the type parameter name (e.g., @template {Type} T). Because JavaScript lacks a syntax for explicitly passing type arguments to function calls, the generic type must be inferrable from the function parameters to function correctly. 
/**
 * @template {HTMLElement} T
 * @param {T} element
 * @returns {T}
 */
function hideElement(element) {
  element.style.display = 'none';
  return element;
}

​
TypeScript-Specific JSDoc Extensions

TypeScript has extended standard JSDoc with tags specifically designed to mirror advanced TypeScript features within JavaScript files.

​
@satisfies

Enforces that an expression matches a specific type without widening or altering the inferred type of the expression itself. 
/** @typedef {Record<string, string | number>} Config */

const myConfig = /** @satisfies {Config} */ ({
    endpoint: "https://api.example.com",
    retries: 3
});

​
@import (TypeScript 5.5+)

Allows importing types directly within JSDoc comments without emitting runtime JavaScript import statements. 
/** @import { Request, Response } from "express" */

/**
 * @param {Request} req
 * @param {Response} res
 */
function handleRequest(req, res) {
  // ...
}

​
@overload

Defines multiple function signatures for a single implementation, mirroring TypeScript’s function overloading capabilities. 
/**
 * @overload
 * @param {string} value
 * @returns {string}
 */
/**
 * @overload
 * @param {number} value
 * @returns {number}
 */
/**
 * @param {string | number} value
 * @returns {string | number}
 */
function process(value) {
    return value;
}

​
Compiler Mechanics

When the TypeScript compiler encounters a /** comment in a JavaScript file, it invokes its internal JSDoc parser. The parser tokenizes the comment, extracts the @ tags, and parses the {Type} expressions using the same type-resolution engine used for .ts files. The compiler strictly enforces the boundary between JSDoc type syntax and standard TypeScript syntax. If JSDoc-specific type syntax (such as the nullable string? or the any-type *) is used within standard TypeScript type annotations in a .ts file (e.g., let x: string?;), the compiler emits TS8020: JSDoc types can only be used inside documentation comments. Conversely, invalid TypeScript syntax inside a JSDoc comment will produce standard parsing errors (such as TS1005).
Master TypeScript with Deep Grasping Methodology!Learn More