Cách ghi lại mã JavaScript bằng JSDoc

Maya Patel included in Programming Javascript

2023-09-19 1956 words 10 minutes

Contents

Tài liệu mã phù hợp là một khía cạnh quan trọng nhưng thường bị bỏ qua trong quá trình phát triển phần mềm. Là một nhà phát triển, bạn sẽ quen với việc viết mã rõ ràng, hiệu quả, nhưng bạn có thể ít kinh nghiệm hơn trong việc viết tài liệu hay.

Tài liệu hiệu quả đóng vai trò là nguồn tài nguyên vô giá cho tất cả các cá nhân tham gia vào nỗ lực hợp tác liên quan đến cơ sở mã của bạn, bao gồm cả các lần lặp lại hiện tại và tương lai của chính bạn. Bằng cách cung cấp sự làm rõ về các lựa chọn thiết kế và đưa ra hướng dẫn về cách sử dụng các chức năng hoặc API cụ thể, nó sẽ thúc đẩy sự hiểu biết và hiệu quả cao hơn của người dùng.

Đối với những người thành thạo lập trình JavaScript, việc sử dụng JSDoc là một phương tiện tuyệt vời để bắt đầu quy trình tạo tài liệu cho cơ sở mã của họ.

##JSDoc là gì?

Việc áp dụng chiến lược “tài liệu dưới dạng mã” ngày càng trở nên phổ biến, với nhiều ngôn ngữ lập trình cung cấp các thư viện chuyên dụng để hợp lý hóa quy trình này. Những công cụ này cho phép các nhà phát triển tạo ra tài liệu toàn diện nhưng ngắn gọn một cách dễ dàng. Để minh họa, ngôn ngữ lập trình Go cung cấp GoDoc để tự động tạo tài liệu dựa trên chú thích mã, trong khi JavaScript dựa vào JSDoc cho các mục đích tương tự trong hệ sinh thái của nó.

Bằng cách sử dụng các nhận xét đặc biệt được nhúng trong mã nguồn JavaScript, JSDoc trích xuất và xử lý các chú thích đó một cách hiệu quả để tạo ra tài liệu phù hợp. Tài liệu này sau đó được định dạng thành định dạng HTML thân thiện với người dùng để có thể truy cập thuận tiện.

Bằng cách tích hợp tài liệu trực tiếp vào mã nguồn, phương pháp này tạo điều kiện thuận lợi cho quá trình cập nhật liền mạch cả mã và tài liệu tương ứng của nó bất cứ khi nào có sửa đổi đối với mã nguồn.

Thiết lập JSDoc

Các nhà thiết kế của JSDoc đã đơn giản hóa quy trình khởi tạo và tích hợp JSDoc trong một dự án JavaScript, giúp nó có thể truy cập và thân thiện với người dùng ngay từ đầu.

Để cài đặt JSDoc cục bộ, hãy chạy:

 npm install --save-dev jsdoc

Việc cài đặt thư viện như một phần phụ thuộc phát triển trong dự án của bạn đòi hỏi phải kết hợp nó vào cơ sở hạ tầng hiện có của dự án, cho phép bạn sử dụng các tính năng và chức năng của nó khi cần.

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

Để sử dụng JSDoc, người ta phải kết hợp cú pháp nhận xét cụ thể trực tiếp trong mã nguồn của họ. Tất cả các nhận xét về tài liệu phải được đặt trong các thẻ/và *//, cho phép mô tả chi tiết một loạt các phần tử như biến xác định, hàm, tham số hàm và nhiều thông tin liên quan khác.

Ví dụ:

 /**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */

function getUser(name) {
  const User = name;
  return User;
}

JSDoc là một công cụ tài liệu dành cho JavaScript sử dụng nhiều từ khóa chuyên biệt khác nhau, bao gồm “@param” và “@returns”, để cung cấp sự rõ ràng về mã của một người. Các từ khóa cụ thể này đóng vai trò là chú thích cho các tham số hàm và giá trị trả về tương ứng, cho phép các nhà phát triển hiểu rõ hơn về cách sử dụng mã của họ và kết quả có thể mong đợi từ nó.

Để tạo một tài liệu toàn diện phác thảo chức năng của tập lệnh này, hãy thực thi lệnh “npx jsdoc” theo sau là đường dẫn được chỉ định dẫn đến tệp JavaScript của bạn.

Ví dụ:

 npx jsdoc src/main.js

Nếu bạn đã cài đặt JSDoc dưới dạng gói chung, bạn có thể từ bỏ việc sử dụng lệnh “npx” bằng cách thực hiện:

 jsdoc path/to/file.js

Việc thực hiện lệnh này sẽ tạo ra một thư mục có tiêu đề “out” trong thư mục chính của dự án của bạn. Trong thư mục đã nói, bạn sẽ khám phá các tài liệu HTML thể hiện nội dung tài liệu của bạn.

Để truy cập tài liệu, bạn có hai tùy chọn. Việc đầu tiên liên quan đến việc định cấu hình máy chủ web cục bộ để làm nền tảng lưu trữ cho các tệp tài liệu. Ngoài ra, bạn có thể chọn mở nội dung của tệp out/index.html trong trình duyệt web ưa thích của mình để xem tài liệu trực tiếp. Xin lưu ý rằng giao diện mặc định của trang tài liệu như sau:

Định cấu hình đầu ra JSDoc

Bạn có tùy chọn sử dụng tệp cấu hình tùy chỉnh để sửa đổi chức năng tiêu chuẩn của JSDoc.

Để đạt được mục tiêu này, cần thiết lập một tệp cấu hình có tên là “conf.js”. Trong tệp này, người ta phải xuất một mô-đun JavaScript sẽ phục vụ mục đích đã định của nó.

Ví dụ:

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

Bên trong tệp cấu hình có nhiều tùy chọn Cấu hình JSDoc. Tùy chọn mẫu cho phép bạn sử dụng mẫu để tùy chỉnh giao diện của tài liệu. Cộng đồng của JSDoc cung cấp nhiều mẫu mà bạn có thể sử dụng. Gói này cũng cho phép bạn tạo các mẫu được cá nhân hóa của riêng bạn.

Để di chuyển tài liệu được tạo tự động, người ta phải chỉ định một thư mục cụ thể làm đích bằng cách điều chỉnh cài đặt cấu hình có nhãn “đích”. Như đã trình bày trước đây, việc chỉ định thư mục “tài liệu” được chỉ định nằm trong vùng lưu trữ chính của dự án sẽ đạt được mục tiêu này một cách hiệu quả.

Thực hiện lệnh sau để vận hành JSDoc bằng tệp cấu hình:

 jsdoc -c /path/to/conf.js

Để đơn giản hóa việc thực thi lệnh này, hãy đưa nó vào dưới dạng mục nhập “scripts” trong tệp “package.json” của bạn. Điều này sẽ cho phép thực thi lệnh một cách thuận tiện từ bất kỳ đâu trong thư mục dự án của bạn bằng cách chạy “npm run [tên tập lệnh]”.

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

Bây giờ người ta có thể thực thi lệnh tập lệnh npm trong môi trường đầu cuối, cho phép thực thi các lệnh tập lệnh được xác định trước được liên kết với Trình quản lý gói nút.

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

Dưới đây là thư viện số học cơ bản có các phương pháp cộng và trừ.

Ví dụ này minh họa cách triển khai JavaScript ngắn gọn và có cấu trúc tốt, được đặc trưng bởi tài liệu rõ ràng tạo điều kiện thuận lợi cho việc hiểu và bảo trì.

 /**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
    /**
     * Adds two numbers.
     * @param {number} a - The first number.
     * @param {number} b - The second number.
     * @return {number} The sum of the two numbers.
     * @throws {TypeError} If any of the arguments is not a number.
     *
      * @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('Both arguments must be numbers.');
        }

        return a \+ b;
    },

    /**
     * Subtracts the second number from the first number.
     * @param {number} a - The number to subtract from.
     * @param {number} b - The number to subtract.
     * @return {number} The result of the subtraction.
     * @throws {TypeError} If any of the arguments is not a number.
     *
      * @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('Both arguments must be numbers.');
        }

        return a - b;
    }

    // ... other methods ...
};

Các nhận xét của JSDoc cung cấp mô tả sâu sắc và toàn diện về thư viện cũng như các chức năng của nó, bao gồm:

Thư viện đóng vai trò là kho lưu trữ nhiều tác phẩm văn học khác nhau, cung cấp cho khách hàng một bộ sưu tập sách phong phú phục vụ cho mục đích trí tuệ của họ. Mục tiêu chính của nó là tạo điều kiện thuận lợi cho việc tiếp cận thông tin và kiến thức, cho phép các cá nhân mở rộng tầm nhìn của mình thông qua việc đọc và học tập. Thư viện cũng đóng một vai trò quan trọng trong việc bảo tồn di sản văn hóa bằng cách lưu trữ các tài liệu lịch sử và kho tàng văn học.

Các biến đầu vào của từng phương thức riêng lẻ, bao gồm kiểu dữ liệu và giải thích ngắn gọn của chúng.

Các đặc điểm, tầm quan trọng hoặc bản chất của đầu ra do mỗi chức năng tạo ra có thể khác nhau về giá trị và phân loại của nó.

Để hiểu rõ hơn các vấn đề tiềm ẩn liên quan đến một phương pháp nhất định, điều quan trọng là phải xem xét cả hai loại lỗi mà phương pháp đó có thể gây ra cũng như bất kỳ điều kiện hoặc trường hợp cụ thể nào mà các lỗi đó có nhiều khả năng xảy ra hơn. Bằng cách nhận thức được những yếu tố này, nhà phát triển có thể thực hiện các bước để giảm thiểu rủi ro và đảm bảo rằng mã của họ hoạt động trơn tru trong nhiều tình huống khác nhau.

Nhận xét trong mã được cung cấp chứa hai thẻ quan trọng, đó là thẻ “@module” và thẻ “@example”. Cái trước chỉ ra rằng tệp là một mô-đun, trong khi cái sau cung cấp một ví dụ mã minh họa cho từng phương thức tương ứng. Các thẻ này đóng vai trò là tài liệu tham khảo hữu ích cho các nhà phát triển đang tìm kiếm hướng dẫn về cách sử dụng các phương pháp này một cách hiệu quả trong các dự án của riêng họ.

Ghi lại mã nhà phát triển đúng cách

Thật vậy, JSDoc đóng vai trò là phương tiện hiệu quả để tạo tài liệu toàn diện về mã JavaScript thông qua việc kết hợp liền mạch trong quá trình phát triển. Điều này tạo điều kiện cho việc tạo nhanh chóng cả tài liệu ngắn gọn và phức tạp, đồng thời cho phép cập nhật và sửa đổi liên tục trong môi trường dự án.

Mặc dù tính năng tự động hóa do JSDoc cung cấp có thể khá hữu ích trong việc tạo tài liệu nhưng điều cần thiết là người ta phải tuân thủ một số nguyên tắc và phương pháp hay nhất nhất định để đảm bảo tạo ra tài liệu chất lượng cao.