การทำ Code Document ในภาษา JavaScript

วันนี้อยากจะมาเขียนถึงเรื่องการทำเอกสารประกอบโค้ดหรือว่า code document ในภาษา JavaScript กันครับ จริงๆ แล้วเราสามารถทำได้หลายวิธี แต่หนึ่งในวิธีที่นิยมที่สุดคือการใช้ JSDoc ซึ่งเป็นมาตรฐานในการเขียน comments ที่สามารถใช้สร้าง document แบบอัตโนมัติได้

ตัวอย่างการทำ Code Document โดยการใช้ JSDoc

/**
 * Adds two numbers together.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of the two numbers.
 */
function add(a, b) {
    return a + b;
}

/**
 * Represents a person.
 * @constructor
 * @param {string} name - The name of the person.
 * @param {number} age - The age of the person.
 */
function Person(name, age) {
    this.name = name;
    this.age = age;
}

/**
 * Greet a person.
 * @returns {string} A greeting message.
 */
Person.prototype.greet = function() {
    return `Hello, my name is ${this.name} and I am ${this.age} years old.`;
};

// Example usage
const john = new Person('John', 30);
console.log(john.greet());

อธิบายตัวอย่างด้านบน

1. Function add มีการใส่คอมเมนต์ JSDoc ซึ่งระบุประเภทของ parameters (@param {number} a, @param {number} b) และประเภทของค่าที่ส่งกลับ (@returns {number}).
2. Constructor Function Person จะมีคอมเมนต์ JSDoc ซึ่งระบุพารามิเตอร์ (@param {string} name, @param {number} age).
3. Method greet ของ Person Class จะมีคอมเมนต์ JSDoc ซึ่งระบุประเภทของค่าที่ส่งกลับ (@returns {string}).

สรุป

การใช้ JSDoc จะช่วยให้ผู้อื่นสามารถอ่านโค้ดของเราเข้าใจถึงการทำงานของ function และ class ต่าง ๆ ได้ง่ายขึ้น และยังสามารถใช้เครื่องมืออัตโนมัติสร้าง document จาก comments เหล่านี้ได้อีกด้วย