# JSDoc

{% tabs %}
{% tab title="🔴 主題" %}

* [`@mixin`](https://jsdoc.app/tags-mixin.html) - a [mixin](https://lochiwei.gitbook.io/web/js/val/obj/extend/mixin "mention") object.
  {% endtab %}

{% tab title="📘 手冊" %}

* [JSDoc](https://jsdoc.app/index.html)
* TypeScript ⟩ [JSDoc Reference](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html)
  {% endtab %}

{% tab title="⭐️ 重點" %}
{% hint style="danger" %}
if you write <mark style="color:orange;">**three or more stars**</mark> (<mark style="color:yellow;">**\***</mark>), the comment will be <mark style="color:red;">**ignored**</mark>;&#x20;

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

{% endhint %}
{% endtab %}

{% tab title="📗 參考" %}

* [ ] [TypeScript without TypeScript - JSDoc superpowers](https://fettblog.eu/typescript-jsdoc-superpowers/) ⭐️
* [ ] DEV ⟩ [Document your Javascript code with JSDoc](https://dev.to/paulasantamaria/document-your-javascript-code-with-jsdoc-2fbf)
* [ ] VSCode ⟩ [JSDoc support](https://code.visualstudio.com/docs/languages/javascript#_jsdoc-support)
* [ ] Kevin Bridges ⟩ [Integrating GitBook with JSDoc to Document Your Open Source Project](https://medium.com/@kevinast/integrate-gitbook-jsdoc-974be8df6fb3)
  {% endtab %}

{% tab title="📗 書" %}

* TypeScript in 50 Lessons (2020), **Lesson 4: Adding Types with JSDoc**
* Modern JavaScript Web Development Cookbook (2018) ⟩ [Documenting your code with JSDoc](https://subscription.packtpub.com/book/web-development/9781788992749/1/ch01lvl1sec09/documenting-your-code-with-jsdoc)
  {% endtab %}

{% tab title="🛠 工具" %}

* Google Apps Script ⟩ [play JSDoc](https://script.google.com/home/projects/1RYgVurvrkoXE05mYJMs9jlCDClD6bCiE1ieiD4RyW43N4oQ51IZliEiF/edit)
* GitHub ⟩ [vscode-docthis](https://github.com/joelday/vscode-docthis) - auto-generated JSDoc.
* VSCode ⟩ [Document This](https://marketplace.visualstudio.com/items?itemName=oouo-diogo-perdigao.docthis) (vscode-docthis?)
* DevHints ⟩ [JSDoc cheatsheet](https://devhints.io/jsdoc)
  {% endtab %}
  {% endtabs %}

{% tabs %}
{% tab title="@param" %}

```typescript
/**
 * 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)
 }
```

{% endtab %}

{% tab title="@typedef" %}

```typescript
// 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)
}
```

{% endtab %}

{% tab title="@type" %}

```typescript
// inline types

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

{% endtab %}

{% tab title="@callback" %}

```typescript
// 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)
  }
}
```

{% endtab %}

{% tab title="import" %}

```typescript
// 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 
 */
```

{% endtab %}
{% endtabs %}