Sample Code
Install
Node JS
must be installed first.
Download Node JS
Global Install
npm install -g jsdoc
Local Install
npm install --save-dev jsdoc
Basic Intro
Using VSCode
Before a function. Just start with /**
and press enter. Vscode will create a comment block skelton.
eg:
/**
*
* @param {*} title
* @param {*} author
*/
function Book(title, author) {
}
The above could be modified like
/**
* <pre>
* This is a description of the foo function.
* Represents a book.
* </pre>
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
}
Generate Documentation
This command will create a directory named out/ in the current working directory. Within that directory, you will find the generated HTML pages.
jsdoc <filename>
Start
Create a package.json
with the following command.
npm init -y
Basic package.json will be like
{
"name": "tut2",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Configuration file
Create jsdoc.json
. reference
Details of each label
{
"source": {
"include": ["src"],
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"plugins": ["plugins/markdown"],
"templates": {
"cleverLinks": true,
"monospaceLinks": true
},
"opts": {
"recurse": true,
"destination": "./docs/"
}
}
Modify package.json
reference
add
"scripts": {
"doc": "jsdoc -c jsdoc.json"
},
and
"devDependencies": {
"jsdoc":"^3.6.3"
}
Create test JS script
Create folder 'src' and index.js inside it
Create first documentation
- Run
npm run doc
, in hte root folder- which means run node with
doc
command as defined injsdoc.json
. ie the command results injsdoc -c jsdoc.json
"scripts": { "doc": "jsdoc -c jsdoc.json" },
- it will create a
docs
(because"destination": "./docs/"
) folder which stores the documentation.
- which means run node with
- Add the following in index.js and run
npm run doc
again/** * Student Name * @author Sreekanth Dayanand * @type {string} */ const studentName = "John Doe";
This will create a
docs
folder and documentation
Trivia : To run a js script run the command
node src
, which means run node in folder mentionedsrc
,(by defaultindex.js
if file name not mentioned)
@file tag
This tag makes the file appear in home page of documentation
/**
* @file index.js is the root file for this example app
* @author Sreekanth Dayanand
* @see <a href="https://outsource-online.net">Outsource Online Internet Solutions</a>
*/
Final jsdoc.json
note : Tutorials folder
and readme.md
(contents of readme will be shown in home page), will augment documentation
{
"source": {
"include": ["src"],
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"plugins": ["plugins/markdown"],
"templates": {
"cleverLinks": true,
"monospaceLinks": true
},
"opts": {
"recurse": true,
"destination": "./docs/",
"tutorials": "./tutorials",
"readme": "./readme.md"
}
}
Final index.json
Final calculator.js
/**
* Calculator module
* See {@tutorial Calculator}
* @module calculator
*/
/**
* Add two parameters
* @param {number} n1 First number
* @param {number} n2 Second number
* @returns {number} Sum of n1 & n2
*/
exports.add = (n1,n2) => n1 + n2;
/**
* Multiply two parameters
* @param {number} n1 First number
* @param {number} n2 Second number
* @returns {number} Product of n1 & n2
*/
exports.multiply = (n1,n2) => n1 - n2;
|
|