Initial Release: 1999 Extended from JavaDoc

https://jsdoc.app/index.html

npm init -y

mpm i -D jsdoc

create a jsdoc.json in root.

• source is where jsdoc looks

• includePattern includes evrything that ends of .js.

• excluding node_modules/ and docs.

• docs will be our destination.

• plugins allows us to use markdown.

• monospace will be the font of our links in the documentation.

• recurse to recurse into sub folders.

{
  "source":{
    "include": ["src"],
    "includePattern": ".js$",
    "excludePattern": "(node_modules/|docs)",
  },
  "plugins": ["plugins/mardown"],
  "templates": {
    "cleverLinks": true,
    "monosplaceLinks": true
  },
  "opts":{
    "recurse": true,
    "destination": "./docs/",
    "template": "custom-template"
  }
}

"scripts":{
  "doc":"jsdoc -c jsdoc.json"
}

• -c: config file

• create an scr folder in root.

and run npm run doc.

• one index.html will be generater.

other than a multi-line comment

/*
this is a multi-line comment
*/

we can use the jsDoc comment to write our documentation

/**
 * It is a jsDoc. Can be found above methods and Class definitions.
 */

jsDoc can be used for Type Checking

• define the type of a variable

/**
 * variable name
 * @type {string}
 */
const name = 'name';

• define the type an array is made of

/**
 * @type {Array<number>}
 */
const arr = [2,3,4,5];

• define the types an Object is made of

/**
 * @type {{id: number, text:string}}
 */
const obj = {
  id: 1,
  text: 'Hello'
};

• define multiple types

/**
 * @type {{id: number|sting, text:string}}
 */
const obj = {
  id: '1',
  text: 'Hello'
};

• jsDoc will automatically recognize a function and pull the parameters from it.

/**
 * Function Description
 * @param {number} amount - This is a Description of the Parameter intorduced with a Hyphon -
 * @param {string} tax - This is a  Description of the Parameter
 * @returns {void} - This is a  Description of the Return
 */

this is how it looks like in the Documentation.

• define your own type.

/**
 * @typedef {Object} Student
 */

*defining Object named Student

• define properties of the object

/**
 * @property {number} id
 * @property {string} name
 * @property {string|number} [age]
 * @property {boolean} isActiv
 */

• use the defined type

/**
 * @type {Student}
 */
const student = {

/**
 * {@Link Person}
 */
const person1 = new Person();

/**
 * Calculator module
 * @module Calculator
 */

• create a tutorials folder in root.

• insert the tutorials key with the path the folder into jsdoc.json.

"opts": {
  "tutorials": "./tutorials"
}

• create tutorial files inside the tutorials folder

• when running jsDoc it will incoporate the tutrials into the Documantation.

• create a tutorial.json inside the tutorials folder.

{
  "program-tutorial": {
    "title": "Program Tutorial"
  },
  "calculator-tutorial": {
    "title": "Calculator Tutorial"
  }
}

Each tutoral file gets a title defined

• use the @tutorial tag plus name in Braces

/**
 * Calculator module - See {@tutorial calculator-tutorial}
 */

• insert the readme key with the path the readme file into jsdoc.json.

"opts": {
  "readme": "./README.md"
}

• copy the default folder from node_modules/jsdoc/ templates and past it into root. Rename it to 'custom-template` for example.

• insert the template into your jsdoc.json

"opts":{
  "template": "custom-template"
}

• go into custom-template/publish.js

• search for Home and rename it.

jsDoc can be used for implicit type checking

make sure your VSCodes settings.json contains:

"javascript.implicitProjectConfig.checkJs": true,

alternatively put

// @ts-check

at the beginning of a file.