Cách viết tài liệu code JavaScript bằng JSDoc: Bí quyết để tạo tài liệu chất lượng

Biên soạn tài liệu code đúng cách rất quan trọng với việc bảo trì phần mềm. Và bạn có thể làm điều này hiệu quả bằng cách sử dụng JSDoc – một công cụ mạnh mẽ trong việc viết tài liệu code JavaScript.

Tại sao cần biên soạn tài liệu code đúng cách?

Việc biên soạn tài liệu code đúng cách thường bị coi nhẹ trong quá trình phát triển phần mềm. Chúng ta thường tập trung vào việc viết code rõ ràng và hiệu quả, nhưng ít kinh nghiệm khi đến việc biên soạn tài liệu.

Tuy nhiên, biên soạn tài liệu đúng cách mang lại lợi ích cho tất cả mọi người liên quan đến dự án của bạn, từ thành viên trong nhóm, bạn bè cho đến chính bạn sau này. Tài liệu giúp giải thích các triển khai cụ thể hoặc cách sử dụng các hàm và API.

JSDoc là gì?

JSDoc là một công cụ giúp tạo tài liệu bằng cách diễn giải các bình luận đặc biệt trong code nguồn JavaScript. Nó sẽ xử lý và tạo ra tài liệu tự động, sẵn sàng cho người dùng truy cập.

Ưu điểm của JSDoc là tài liệu được giữ trong code, vì vậy khi bạn cập nhật code, bạn cũng dễ dàng cập nhật tài liệu.

Thiết lập JSDoc

JSDoc được thiết kế để bắt đầu và thiết lập dễ dàng trong dự án JavaScript của bạn.

Để cài đặt JSDoc cục bộ, chỉ cần chạy lệnh sau trong dự án:

npm install --save-dev jsdoc

Cách viết bình luận JSDoc

Để sử dụng JSDoc, bạn sẽ sử dụng các bình luận cú pháp đặc biệt bên trong code nguồn. Bạn đặt tất cả nhận xét tài liệu vào bên trong các dấu /** và */. Trong bình luận này, bạn có thể mô tả các biến, hàm, tham số và nhiều thứ khác.

Ví dụ:

/**
 * Lấy User theo tên.
 * @param {string} name - Tên của User
 * @returns {string} User
 */
function getUser(name) {
  const User = name;
  return User;
}

Tag @param và @returns là hai trong số nhiều từ khóa đặc biệt mà JSDoc hỗ trợ để giải thích code của bạn.

Để tạo tài liệu cho code này, chỉ cần chạy lệnh npx jsdoc trước đường dẫn tới file JavaScript:

npx jsdoc src/main.js

Lệnh này sẽ tạo một thư mục out trong gốc dự án của bạn. Trong thư mục này, bạn sẽ tìm thấy file HTML đại diện cho các trang tài liệu.

Cấu hình đầu ra JSDoc

Bạn có thể tạo một file cấu hình để thay đổi hành vi mặc định của JSDoc.

Để làm điều này, tạo một file conf.js và xuất mô-đun JavaScript bên trong file:

module.exports = {
  source: {
    includePattern: ".+.js(doc|x)?$",
    excludePattern: ["node_modules"],
  },
  recurseDepth: 5,
  sourceType: "module",
  opts: {
    template: "path/to/template",
    destination: "./docs/",
    recurse: true,
  },
};

Trong file cấu hình, bạn có thể đặt nhiều tùy chọn để tùy chỉnh JSDoc. Ví dụ, tùy chọn template cho phép bạn sử dụng một mẫu giao diện tùy chỉnh cho tài liệu. Cộng đồng JSDoc cung cấp nhiều mẫu mà bạn có thể sử dụng. Bạn cũng có thể tạo các mẫu cá nhân hóa.

Để thay đổi vị trí tài liệu, đặt tùy chọn destination sang một thư mục. Ví dụ, ./docs là một thư mục trong gốc dự án.

Để chạy JSDoc với một file cấu hình, sử dụng lệnh sau:

jsdoc -c /path/to/conf.js

Để dễ dàng chạy lệnh này, bạn có thể thêm nó làm đầu vào trong phần scripts của file package.json:

"scripts": {
    "dev": "nodemon app.js",
    "run-docs": "jsdoc -c /path/to/conf.js"
 },

Bây giờ bạn có thể chạy lệnh script npm trong terminal.

Ví dụ về tài liệu được tạo bằng JSDoc

Dưới đây là một ví dụ về một thư viện số học đơn giản với hai phương thức add và subtract.

/**
 * Thư viện thực hiện các phép tính số học cơ bản.
 * @module arithmetic
 */
module.exports = {
    /**
     * Cộng hai số.
     * @param {number} a - Số thứ nhất.
     * @param {number} b - Số thứ hai.
     * @return {number} Tổng của hai số.
     * @throws {TypeError} Nếu bất kỳ đối số nào không phải là số.
     * 
     * @example
     * const arithmetic = require('arithmetic');
     * const sum = arithmetic.add(5, 10);
     * console.log(sum); // 15
     */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Cả hai đối số phải là số.');
        }

        return a + b;
    },

    /**
     * Trừ số thứ hai từ số thứ nhất.
     * @param {number} a - Số để trừ.
     * @param {number} b - Số được trừ.
     * @return {number} Kết quả của phép trừ.
     * @throws {TypeError} Nếu bất kỳ đối số nào không phải là số.
     * 
     * @example
     * const arithmetic = require('arithmetic');
     * const difference = arithmetic.subtract(10, 5);
     * console.log(difference); // 5
     */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Cả hai đối số phải là số.');
        }

        return a - b;
    }

    // ... các phương thức khác ...
};

Bình luận JSDoc cung cấp mô tả chi tiết và toàn diện về thư viện và các phương thức của nó, bao gồm:

Mô tả thư viện và mục đích sử dụng của nó.
Mô tả tóm tắt về mỗi tham số của phương thức, bao gồm kiểu dữ liệu và mô tả.
Giá trị trả về và kiểu dữ liệu của mỗi phương thức.
Các lỗi có thể xảy ra và điều kiện gây ra chúng.
Ví dụ về cách sử dụng từng phương thức.

Như bạn có thể thấy, JSDoc là công cụ hữu ích để bắt đầu biên soạn tài liệu code JavaScript. Với tích hợp dễ dàng, bạn có thể tạo ra tài liệu nhanh chóng và chi tiết trong quá trình viết code. Bạn cũng có thể duy trì và cập nhật tài liệu ngay tại không gian làm việc.

Tuy nhiên, dù có tính năng tự động của JSDoc, bạn vẫn nên tuân thủ những nguyên tắc để tạo ra tài liệu chất lượng.