วิธีการจัดทำเอกสารโค้ด JavaScript โดยใช้ JSDoc

เอกสารโค้ดที่เหมาะสมเป็นสิ่งสำคัญในการพัฒนาซอฟต์แวร์ที่มักถูกมองข้าม ในฐานะนักพัฒนา คุณจะคุ้นเคยกับการเขียนโค้ดที่สะอาดและมีประสิทธิภาพ แต่คุณอาจมีประสบการณ์น้อยกว่าในการเขียนเอกสารที่ดี

เอกสารที่มีประสิทธิภาพทำหน้าที่เป็นทรัพยากรอันล้ำค่าสำหรับทุกคนที่เกี่ยวข้องกับความพยายามในการทำงานร่วมกันที่เกี่ยวข้องกับโค้ดเบสของคุณ รวมถึงการทำซ้ำในปัจจุบันและอนาคตของคุณเอง ด้วยการชี้แจงตัวเลือกการออกแบบและเสนอคำแนะนำในการใช้ฟังก์ชันหรือ API เฉพาะ จะช่วยส่งเสริมความเข้าใจและประสิทธิภาพในหมู่ผู้ใช้มากขึ้น

สำหรับผู้ที่มีความเชี่ยวชาญในการเขียนโปรแกรม JavaScript การใช้ JSDoc ถือเป็นวิธีการที่ดีเยี่ยมในการเริ่มต้นกระบวนการเอกสารสำหรับโค้ดเบสของพวกเขา

JSDoc คืออะไร?

การใช้กลยุทธ์"docs-as-code"ได้รับความนิยมเพิ่มมากขึ้น โดยมีภาษาการเขียนโปรแกรมจำนวนมากที่ให้ไลบรารีเฉพาะสำหรับการปรับปรุงกระบวนการนี้ เครื่องมือเหล่านี้ช่วยให้นักพัฒนาสามารถสร้างเอกสารที่ครอบคลุมแต่กระชับได้อย่างง่ายดาย ตามภาพประกอบ ภาษาการเขียนโปรแกรม Go เสนอ GoDoc สำหรับการสร้างเอกสารอัตโนมัติตามคำอธิบายประกอบโค้ด ในขณะที่ JavaScript อาศัย JSDoc เพื่อจุดประสงค์ที่คล้ายกันภายในระบบนิเวศของมัน

ด้วยการใช้ความคิดเห็นพิเศษที่ฝังอยู่ในซอร์สโค้ด JavaScript JSDoc จึงแยกและประมวลผลคำอธิบายประกอบดังกล่าวได้อย่างมีประสิทธิภาพเพื่อสร้างเอกสารที่ปรับแต่งโดยเฉพาะ เอกสารนี้จะถูกจัดรูปแบบให้เป็นรูปแบบ HTML ที่ใช้งานง่ายในภายหลังเพื่อให้เข้าถึงได้สะดวก

ด้วยการรวมเอกสารประกอบเข้ากับซอร์สโค้ดโดยตรง วิธีการนี้ช่วยให้กระบวนการอัปเดตทั้งโค้ดและเอกสารประกอบที่เกี่ยวข้องเป็นไปอย่างราบรื่นทุกครั้งที่มีการแก้ไขโค้ดเดิม

การตั้งค่า JSDoc

ผู้ออกแบบ JSDoc ได้ทำให้กระบวนการเริ่มต้นและบูรณาการ JSDoc ภายในโปรเจ็กต์ JavaScript ง่ายขึ้น ทำให้สามารถเข้าถึงได้และเป็นมิตรกับผู้ใช้ตั้งแต่เริ่มแรก

หากต้องการติดตั้ง JSDoc ในเครื่อง ให้รัน:

 npm install --save-dev jsdoc

การติดตั้งไลบรารีเป็นการพึ่งพาการพัฒนาภายในโปรเจ็กต์ของคุณจะต้องรวมไลบรารีเข้ากับโครงสร้างพื้นฐานที่มีอยู่ของโปรเจ็กต์ของคุณ ซึ่งทำให้คุณสามารถใช้คุณสมบัติและฟังก์ชันการทำงานได้ตามต้องการ

วิธีเขียนความคิดเห็น JSDoc

หากต้องการใช้ JSDoc เราจะต้องรวมไวยากรณ์ความคิดเห็นเฉพาะไว้ภายในซอร์สโค้ดโดยตรง หมายเหตุในเอกสารทั้งหมดจะล้อมรอบด้วยแท็ก/และ *//ซึ่งช่วยให้อาร์เรย์องค์ประกอบต่างๆ มากมาย เช่น ตัวแปรที่กำหนด ฟังก์ชัน พารามิเตอร์ฟังก์ชัน และข้อมูลที่เกี่ยวข้องอื่นๆ ที่จะอธิบายโดยละเอียด

ตัวอย่างเช่น:

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

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

JSDoc เป็นเครื่องมือเอกสารสำหรับ JavaScript ที่ใช้คำสำคัญพิเศษต่างๆ รวมถึง “@param” และ “@returns” เพื่อให้ความชัดเจนเกี่ยวกับโค้ดของตน คำหลักเฉพาะเหล่านี้ทำหน้าที่เป็นคำอธิบายประกอบสำหรับพารามิเตอร์ฟังก์ชันและค่าที่ส่งคืนตามลำดับ ช่วยให้นักพัฒนาเข้าใจได้ดีขึ้นว่าควรใช้โค้ดของตนอย่างไร และคาดหวังผลลัพธ์ใดได้บ้าง

หากต้องการสร้างเอกสารที่ครอบคลุมโดยสรุปฟังก์ชันการทำงานของสคริปต์นี้ ให้ดำเนินการคำสั่ง “npx jsdoc” ตามด้วยเส้นทางที่ระบุซึ่งนำไปสู่ไฟล์ JavaScript ของคุณ

ตัวอย่างเช่น:

 npx jsdoc src/main.js

หากคุณได้ติดตั้ง JSDoc เป็นแพ็คเกจสากล คุณอาจละทิ้งการใช้คำสั่ง “npx” โดยเพียงดำเนินการ:

 jsdoc path/to/file.js 

การดำเนินการตามคำสั่งนี้จะส่งผลให้มีการสร้างไดเร็กทอรีชื่อ"out"ภายในไดเร็กทอรีหลักของโครงการของคุณ ภายในไดเร็กทอรีดังกล่าว คุณจะค้นพบเอกสาร HTML ที่รวบรวมเนื้อหาของเอกสารของคุณ

ในการเข้าถึงเอกสาร คุณมีสองทางเลือก ประการแรกเกี่ยวข้องกับการกำหนดค่าเว็บเซิร์ฟเวอร์ในพื้นที่เพื่อทำหน้าที่เป็นแพลตฟอร์มการโฮสต์สำหรับไฟล์เอกสาร หรือคุณสามารถเลือกที่จะเปิดเนื้อหาของไฟล์ out/index.html ภายในเว็บเบราว์เซอร์ที่คุณต้องการเพื่อดูเอกสารโดยตรง โปรดทราบว่าลักษณะเริ่มต้นของหน้าเอกสารจะเป็นดังนี้:

การกำหนดค่าเอาต์พุต JSDoc

คุณมีทางเลือกในการใช้ไฟล์คอนฟิกูเรชันที่กำหนดเองเพื่อแก้ไขฟังก์ชันการทำงานมาตรฐานของ JSDoc

เพื่อให้บรรลุเป้าหมายนี้ จำเป็นต้องสร้างไฟล์การกำหนดค่าที่เรียกว่า “conf.js” ภายในไฟล์นี้ ควรส่งออกโมดูล JavaScript ที่จะตอบสนองวัตถุประสงค์ที่ตั้งใจไว้

ตัวอย่างเช่น:

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

ภายในไฟล์การกำหนดค่ามีตัวเลือก การกำหนดค่า JSDoc ต่างๆ ตัวเลือกเทมเพลตช่วยให้คุณใช้เทมเพลตเพื่อปรับแต่งรูปลักษณ์ของเอกสารประกอบได้ ชุมชนของ JSDoc€™ มี เทมเพลต มากมายที่คุณสามารถใช้ได้ แพ็คเกจนี้ยังให้คุณสร้างเทมเพลตส่วนตัวของคุณเองได้

หากต้องการย้ายเอกสารที่สร้างขึ้นโดยอัตโนมัติ จะต้องกำหนดไดเร็กทอรีเฉพาะเป็นปลายทางโดยการปรับการตั้งค่าการกำหนดค่าที่มีป้ายกำกับว่า"ปลายทาง"ดังที่แสดงไว้ก่อนหน้านี้ การระบุโฟลเดอร์ “เอกสาร” ที่กำหนดซึ่งอยู่ภายในพื้นที่เก็บข้อมูลหลักของโปรเจ็กต์จะบรรลุวัตถุประสงค์นี้ได้อย่างมีประสิทธิภาพ

ดำเนินการคำสั่งต่อไปนี้เพื่อดำเนินการ JSDoc โดยใช้ไฟล์การกำหนดค่า:

 jsdoc -c /path/to/conf.js

เพื่อให้ดำเนินการคำสั่งนี้ได้ง่ายขึ้น ให้รวมคำสั่งนี้เป็นรายการ “สคริปต์” ภายในไฟล์ “package.json” ของคุณ ซึ่งจะช่วยให้ดำเนินการคำสั่งได้อย่างสะดวกจากทุกที่ในไดเร็กทอรีโปรเจ็กต์ของคุณโดยการรัน “npm run [ชื่อสคริปต์]”

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

ตอนนี้สามารถรันคำสั่งสคริปต์ npm ภายในสภาพแวดล้อมเทอร์มินัล เปิดใช้งานการดำเนินการคำสั่งสคริปต์ที่กำหนดไว้ล่วงหน้าที่เกี่ยวข้องกับ Node Package Manager

ตัวอย่างเอกสารที่สร้างด้วย JSDoc

ด้านล่างนี้เป็นไลบรารีเลขคณิตเบื้องต้นที่มีวิธีการบวกและการลบ

ตัวอย่างนี้แสดงให้เห็นถึงการใช้งาน JavaScript ที่กระชับและมีโครงสร้างที่ดี โดยมีลักษณะเฉพาะด้วยเอกสารที่ชัดเจนซึ่งเอื้อต่อความเข้าใจและการบำรุงรักษา

 /**
 * 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 ...
};

ความคิดเห็นของ JSDoc นำเสนอการพรรณนาไลบรารีและฟังก์ชันการทำงานของไลบรารีในเชิงลึกและครอบคลุมทั้งหมด ซึ่งรวมถึง:

ห้องสมุดทำหน้าที่เป็นพื้นที่เก็บข้อมูลสำหรับงานวรรณกรรมต่างๆ โดยให้บริการลูกค้าด้วยคอลเลกชั่นหนังสือมากมายที่เหมาะกับการแสวงหาความรู้ทางปัญญา วัตถุประสงค์หลักคือการอำนวยความสะดวกในการเข้าถึงข้อมูลและความรู้ ช่วยให้บุคคลสามารถขยายขอบเขตอันไกลโพ้นผ่านการอ่านและการเรียนรู้ ห้องสมุดยังมีบทบาทสำคัญในการอนุรักษ์มรดกทางวัฒนธรรมด้วยการเก็บรักษาเอกสารสำคัญทางประวัติศาสตร์และสมบัติทางวรรณกรรม

ตัวแปรอินพุตของแต่ละวิธี ครอบคลุมประเภทข้อมูลและคำอธิบายที่กระชับ

ลักษณะ ความสำคัญ หรือลักษณะของผลลัพธ์ที่สร้างโดยแต่ละฟังก์ชันอาจแตกต่างกันไปในแง่ของมูลค่าและการจำแนกประเภท

เพื่อให้เข้าใจถึงปัญหาที่อาจเกิดขึ้นที่เกี่ยวข้องกับวิธีการที่กำหนดได้ดีขึ้น สิ่งสำคัญคือต้องพิจารณาทั้งประเภทของข้อผิดพลาดที่อาจเกิดจากวิธีการดังกล่าว ตลอดจนเงื่อนไขหรือสถานการณ์เฉพาะใดๆ ที่ข้อผิดพลาดเหล่านั้นมีแนวโน้มที่จะเกิดขึ้นมากกว่า เมื่อตระหนักถึงปัจจัยเหล่านี้ นักพัฒนาสามารถดำเนินการเพื่อลดความเสี่ยงและรับรองว่าโค้ดของพวกเขาทำงานได้อย่างราบรื่นในสถานการณ์ต่างๆ

ความคิดเห็นในโค้ดที่ให้มาประกอบด้วยแท็กที่สำคัญสองแท็ก ได้แก่ แท็ก “@module” และแท็ก “@example” แบบแรกระบุว่าไฟล์นั้นเป็นโมดูล ในขณะที่แบบหลังให้ตัวอย่างโค้ดที่แสดงให้เห็นสำหรับแต่ละวิธีตามลำดับ แท็กเหล่านี้ทำหน้าที่เป็นข้อมูลอ้างอิงที่มีประโยชน์สำหรับนักพัฒนาที่กำลังมองหาคำแนะนำเกี่ยวกับวิธีการใช้วิธีการเหล่านี้อย่างมีประสิทธิภาพภายในโครงการของตนเอง

การจัดทำเอกสารโค้ดของนักพัฒนาอย่างถูกวิธี

แท้จริงแล้ว JSDoc ทำหน้าที่เป็นวิธีที่มีประสิทธิภาพในการสร้างเอกสารประกอบของโค้ด JavaScript ที่ครอบคลุมผ่านการผสานรวมที่ราบรื่นภายในกระบวนการพัฒนา สิ่งนี้อำนวยความสะดวกในการสร้างเอกสารที่กระชับและซับซ้อนอย่างรวดเร็วในขณะเดียวกันก็เปิดใช้งานการอัปเดตและการแก้ไขอย่างต่อเนื่องภายในสภาพแวดล้อมของโครงการ

แม้ว่าระบบอัตโนมัติที่ JSDoc มอบให้อาจมีประโยชน์มากในการสร้างเอกสารประกอบ แต่ก็ยังจำเป็นอย่างยิ่งที่จะต้องปฏิบัติตามหลักเกณฑ์และแนวทางปฏิบัติที่ดีที่สุดบางประการเพื่อให้แน่ใจว่าจะสร้างเอกสารประกอบคุณภาพสูงได้