📖JSDoc

🔴 主題

• @mixin - a mixin object.

📘 手冊

• JSDoc

• TypeScript ⟩ JSDoc Reference

⭐️ 重點

if you write three or more stars (*), the comment will be ignored;

/** <-- ⭐️ JSDoc expects two stars (no more, no less)
 * 
 */

📗 參考

• TypeScript without TypeScript - JSDoc superpowers ⭐️

• DEV ⟩ Document your Javascript code with JSDoc

• VSCode ⟩ JSDoc support

• Kevin Bridges ⟩ Integrating GitBook with JSDoc to Document Your Open Source Project

📗 書

• TypeScript in 50 Lessons (2020), Lesson 4: Adding Types with JSDoc

• Modern JavaScript Web Development Cookbook (2018) ⟩ Documenting your code with JSDoc

🛠 工具

• Google Apps Script ⟩ play JSDoc

• GitHub ⟩ vscode-docthis - auto-generated JSDoc.

• VSCode ⟩ Document This (vscode-docthis?)

• DevHints ⟩ JSDoc cheatsheet

@param

/**
 * Adds VAT to a price 
 *  
 * @param {number} price The price without VAT 
 * @param {number} vat The VAT [0-1] 
 *  
 * @returns {number} 
 */
 function addVAT(price, vat = 0.2) {  
   return price * (1 + vat)
 }

@typedef

// defining objects

/** 
 * @typedef {Object} Article
 *
 * @property {number} price 
 * @property {number} vat 
 * @property {string} string 
 * @property {boolean=} sold (⭐️ optional property)
 */
 
 // ⭐️ optional property/parameter syntax:
 //    • @param {boolean=} sold
 //    • @param {boolean} [sold]
 
/** 
 * Now we can use `Article` as a proper type
 *
 * @param {[Article]} articles 
 */
function totalAmount(articles) {  
   return articles.reduce((total, article) => {    
   return total + addVAT(article)  }, 0)
}

@type

// inline types

/**
 * @type {number}
 */
let amount;

@callback

// defining functions (@callback works like @typedef)

/**
 * @callback LoadingCallback
 *
 * @param {number} status
 * @param {string=} response (⭐️ optional, see: @typedef)
 * @returns {void}
 */

/**
 * @param {string} url
 * @param {LoadingCallback} cb
 */
function loadData(url, cb) {
  const xhr = new XMLHttpRequest();
  xhr.open('GET', url)
  xhr.onload = () => {
    cb(xhr.status, xhr.responseText)
  }
}

import

// imports `Article` type from `article.ts` 
// and makes it available under `Article`

/** 
 * @typedef { import('./article').Article } Article 
 */

/** 
 * @type {Article} 
 */
const article = {
  title: 'The best book in the world',
  price: 10,
  vat: 0.2
}

// import from `types.d.ts` type declaration file

/** 
 * @typedef { import('./types.d').ShipStorage } ShipStorage 
 */