JsDoc kullanımı ve API açıklamaları oluşturma

JSDoc JavaScript kaynak dosyalarına ek açıklama için kullanılan metin işaretleme dilidir. JSDoc yorumları kullanarak programcılar uygulamanın ne yaptığını yazabilir ve bunu dökümante edebilir. Bundan sonra yazılanlar farklı araçlar vasıtası ile HTML veya Zengin Metin Biçimi haline getirilir.

Kurulum

npm install jsdoc --save-dev

ES6 Class‘larının düzgün işlenmesi için

npm install jsdoc-export-default-interop --save-dev

Kullanım

JSDoc configürasyonu

jsdoc_conf.json

{
  "tags": {
      "allowUnknownTags": true
  },
  "source": {
      "includePattern": ".+\\.js(doc|x)?$",
      "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": ["node_modules/jsdoc-export-default-interop/dist/index"],
  "templates": {
      "cleverLinks": false,
      "monospaceLinks": false,
      "default": {
          "outputSourceFiles": true
      }
  }
}

npm script;

  "scripts": {
    "doc-html": "jsdoc <işlenecek js dosyalarının bulunduğu klasör> -r -c <configürasyon dosyasının adı>.json -d <çıktı klasörü>"
  }

örnek;

  "scripts": {
    "doc-html": "jsdoc lib -r -c jsdoc_conf.json -d jsdoc_out"
  }

HTML dosyalarını statik olarak sunmak için;

npx serve jsdoc_out

Markdown üretimi

npm install jsdoc-to-markdown --save-dev

Eger markdown dosyası BitBucket üzerinde tutulacak ise;

npm install dmd-bitbucket --save-dev

Döküman şablonu oluşturma

ApiDocs.hbs

# Documentation


{{>main}}

npm script;

  "scripts": {
    "doc-md": "jsdoc2md --plugin dmd-bitbucket -c jsdoc_conf.json -t <şablon dosyası>.hbs lib/**/*.js > <çıktı>.md",
  }

örnek;

  "scripts": {
    "doc-md": "jsdoc2md --plugin dmd-bitbucket -c jsdoc_conf.json -t ApiDocs.hbs lib/**/*.js > ApiDocs.md",
  }

Eslint ile JsDoc açıklamalarının kontrolü

npm install eslint eslint-plugin-jsdoc --save-dev

---
plugins:
  - jsdoc
extends:
  - plugin:jsdoc/recommended

npm script;

  "scripts": {
    "lint": "eslint .",
    "doc-md": "jsdoc2md --plugin dmd-bitbucket -c jsdoc_conf.json -t ApiDocs.hbs lib/**/*.js > ApiDocs.md",
    "doc-html": "jsdoc lib -r -c jsdoc_conf.json -d jsdoc_out"
  },