Định dạng JSDoc
Cộng đồng JS dùng JSDoc – comment block bắt đầu bằng /**.
Ví dụ chuẩn
/**
* Cộng hai số.
* @param {number} num1 - Số thứ nhất
* @param {number} num2 - Số thứ hai
* @returns {number} Tổng của num1 và num2
* @throws {TypeError} Nếu tham số không phải số
*/
function sum(num1, num2) {
if (typeof num1 !== 'number' || typeof num2 !== 'number') {
throw new TypeError('Tham số phải là số');
}
return num1 + num2;
}
Các thẻ phổ biến
| Thẻ | Ý nghĩa |
|---|---|
@param | Mô tả tham số (kiểu, tên, mô tả) |
@returns / @return | Giá trị trả về (kiểu, mô tả) |
@throws | Exception có thể ném ra |
@example | Ví dụ sử dụng |
@deprecated | Đánh dấu không khuyến khích dùng |
@see | Tham khảo liên quan |
Lợi ích
- IDE hiển thị tooltip, autocomplete.
- Tự động sinh tài liệu (docs).
- Type checking (VS Code, TypeScript hiểu JSDoc).