JSDoc Type Annotations in Plain JavaScript
What You'll Learn
You'll discover how JSDoc comments let you add type checking to regular JavaScript without installing TypeScript at all.
The Core Idea
Before TypeScript became popular, developers needed a way to document their JavaScript code. JSDoc is a commenting system that describes what types functions expect and return. Modern editors like VS Code can read these comments and provide type checking—no compilation required!
Here's how it works:
/**
* @param {string} name - The user's name
* @param {number} age - The user's age
* @returns {string} A greeting message
*/
function greet(name, age) {
return `Hello ${name}, you are ${age} years old`;
}
// Your editor will warn you about this:
greet(123, "wrong"); // Wrong types!
The @param and @returns tags tell your editor what types to expect. You get autocomplete and error warnings without any build step.
Where JSDoc Falls Short
While JSDoc provides basic type safety, it has limitations:
- Verbose syntax: The comment format is clunky compared to TypeScript's inline types
- Limited type features: Complex types (the advanced patterns we'll learn later) are awkward or impossible to express
- No enforcement: It's still JavaScript—the code runs even with type errors
- Inconsistent adoption: Team members might skip writing JSDoc comments
Think of JSDoc as training wheels for type safety—helpful for light projects or gradual adoption, but you'll eventually want the full power and guarantees of actual TypeScript.
Key Takeaway: JSDoc offers type checking in plain JavaScript through comments, giving you some TypeScript benefits without compilation, but lacks the power and enforcement of true static typing.