📘 JSDoc – Your Development Assistant. See for Yourself!

If you write JavaScript or TypeScript, you’ve probably seen /** ... */ above functions. These aren’t just comments — they’re JSDoc.

And it can make your life (and your colleagues’ lives) way easier.

🤔 What is JSDoc?

JSDoc is a tool for documenting JavaScript code. It allows you to:

• describe functions, classes, and variables,
• define data types,
• generate HTML documentation,
• and most importantly — get autocomplete and type hints right in your editor.

📚 Official docs: jsdoc.app

✅ Where JSDoc Really Helps

🔹 1. Functions and Methods

/**
 * Calculates product price with discount.
 * @param {number} originalPrice - Original price (must be > 0).
 * @param {number} discountPercent - Discount percent (0–100).
 * @returns {{ finalPrice: number, error: string | null }} - Final price and error message (if any).
 * @example
 * calculateDiscount(1000, 20); // { finalPrice: 800, error: null }
 * calculateDiscount(-50, 10);  // { finalPrice: 0, error: "Price must be greater than 0" }
 */
function calculateDiscount(originalPrice, discountPercent) {
	if (originalPrice <= 0) {
		return { finalPrice: 0, error: 'Price must be greater than 0' };
	}
 
	if (discountPercent < 0 || discountPercent > 100) {
		return { finalPrice: originalPrice, error: 'Discount must be between 0% and 100%' };
	}
 
	const finalPrice = originalPrice * (1 - discountPercent / 100);
	return { finalPrice: Number(finalPrice.toFixed(2)), error: null };
}

➡️ You instantly get inline hints in the editor — no need to read through the implementation.

🔹 2. API and SDK Documentation

JSDoc is perfect for documenting public methods, classes, and interfaces — especially in SDKs, libraries, or internal APIs.

🔹 3. Type Support in JS Projects

If you’re not using TypeScript, JSDoc is a lightweight way to add types without a full migration or rebuild process.

🚫 When You Might Skip JSDoc

• In small pet projects.
• When code is super simple and self-explanatory.
• For one-liners like const double = (x) => x * 2.

📌 The key is: don’t overdo it. Use JSDoc when it actually adds value.

⚙️ How to Start

Just start writing comments using /** */ and include the right tags:

• @param — parameters
• @returns — return value
• @typedef — custom type definitions
• @property — object properties
• @example — usage examples

More tags: jsdoc.app/tags.html

📝 Conclusion

JSDoc is your assistant for teamwork, autocomplete, and code clarity.

📌 It makes supporting your code much easier — especially in large projects.
Without it, complex functions become “mysteries” — for others, and for future you. 😉

✍️ Try documenting 1–2 core functions in your project using JSDoc — and see how much smoother things get.

📢 Don’t ignore it. Use it wisely — and your teammates will thank you for code that’s easier to read and faster to work with.