Introduction
In this tutorial I will cover the basics of how you can generate a Javascript code documentation for your codebase using the Grunt-plugin grunt-jsdoc. It works pretty much like Java-doc. Comments are added to your code that covers information about classes and functions, jsdoc will then generate a full API documentation using the information from these comments that can be navigated through in your browser. I will also cover how you can customize the default template of this JsDoc-webpage to match your desired look. In this tutorial I will use Grunt as my build tool. Also the site I am generating JsDoc for is built using Angular, but obviously you could still use this tutorial for any Javascript codebase. To see an example how this may look please see the JsDoc I generated for my own portfolio website.
Setup
First of all let’s add jsdoc to our dependency list in package.json.
{
"name": "myPage",
"version": "1.0.0",
"repository": {
"type": "git",
"url": "https://github.com/me/myRepo"
},
"license": "MIT",
"devDependencies": {
"angular": "1.3.15",
"grunt": "^0.4.5",
"load-grunt-config": "^0.17.2",
"load-grunt-tasks": "^3.3.0",
"grunt-jsdoc": "1.1.0"
}
}
Next add jsdoc as a Grunt build job to your Gruntfile.js.
module.exports = function(grunt) {
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
jsdoc: {
dist: {
src: [
'js/angular/**/*.js'
],
options: {
destination: 'docs',
recurse: true
}
}
}
});
grunt.loadNpmTasks('grunt-jsdoc');
grunt.registerTask('build-docs', [
'jsdoc'
]);
};
Install npm modules:
npm install
Now try running the newly created Gruntjob ‘build-docs’ just to see that you don’t get any errors. The output should be generated into the folder ./docs (as configured in options). The jsdoc should cover all Javascript code in the angular-folder, however since we haven’t added any jsdoc-comments yet the generated jsdoc site should be empty.
grunt build-docs
If you browse to localhost/docs in your browser you now see an empty jsdoc template. Now you are ready to start adding the jsdoc comments to your code.
Jsdoc global definitions
First of all we will ad a file for jsdoc global definitions, references we will use in the comments we add to our js-files. Create a js-file called jsdoc-global-definitions.js to your js-folder. Then add this file to your sources in the jsdoc Grunt task.
module.exports = function(grunt) {
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
jsdoc: {
dist: {
src: [
'js/angular/**/*.js',
'js/jsdoc-global-definitions.js'
],
options: {
destination: 'docs',
recurse: true
}
}
}
});
grunt.loadNpmTasks('grunt-jsdoc');
grunt.registerTask('build-docs', [
'jsdoc'
]);
};
In the file jsdoc-global-definitions.js I have the following configuration:
/**
* AngularJS is a structural framework for dynamic web apps. It lets you use HTML as your template language and lets you extend HTML's syntax to express your application's components clearly and succinctly. Angular's data binding and dependency injection eliminate much of the code you would otherwise have to write. And it all happens within the browser, making it an ideal partner with any server technology.
* @external "Angular"
* @see {@link https://docs.angularjs.org/guide|Angular documentation}
*/
/**
* @namespace controllers
* @description Controllers linked to a specific view.
*/
/**
* @namespace directives
* @description Reusable directives that can be used by multiple views.
*/
/**
* @namespace filters
* @description Reusable filters that can be used by {@link controllers}, {@link directives} and {@link services}.
*/
/**
* @namespace services
* @description Reusable services that can be used by {@link controllers}, {@link directives} and {@link filters}.
*/
As you can see the file contains only comments written with the jsdoc syntax. Here we define global namespaces that we will later use when commenting the javascript codebase. Obviously you will have to modify your global definition file to fit the design pattern and frontend framework you have chosen (if any). Like I said, in this tutorial I am assuming that that the website is Angular-based, which is why I have defined the following namespaces: controllers, directives, filters and services. Each namespace also have a fitting description. We also have one external library dependecy, namely Angular, which is why I also added the first comment that has a link to Angulars developer documentation. This will list Angular as an external library. Also note that in the description you can link to other namespaces by writing {@link namespace}. To read more about jsdoc links please read this.
Adding jsdoc comments to your code
Here is an example of jsdoc comments written in jsdoc syntax added to an Angular controller:
(function() {
var app = angular.module('myPage');
/**
* @constructor MyController
* @memberof controllers
* @description Controller for my webpage
* @param {$scope} $scope - See {@link https://code.angularjs.org/1.2.26/docs/api/ng/type/$rootScope.Scope}
* @param {services.myService} myService - Services used for cool stuff
*/
var MyController = ['$scope', 'myService', function($scope, myService) {
/**
* @function controllers.MyController#getFibonacciNumberByIndex
* @description Gets a number in the Fibonacci sequence by index
* @param {number} The index of the Fibonacci sequence
* @returns {number} The calculated Fibonacci number
*/
function getFibonacciNumberByIndex(index) {
var list = [1, 1];
for (var i = 0; i <= index; i++) {
var num1 = list[list.length - 1];
var num2 = list[list.length - 2];
var next = num1 + num2;
list.push(next);
}
return list[index];
}
}];
app.controller('MyController', MyController);
}());
As you can see in the controller MyController the function MyController is treated as the constructor, therefore the @constructor comment. I have also added the comment @memberof controllers which is referring to the namespace “controllers” that we defined earlier. MyController has two dependencies, $scope and myService, therefore these are documented as @param. Since $scope is a built-in Angular module I add a link to the documentation of $scope using the {@link} syntax. The other dependency is to to an Angular service in OUR codebase, therefore it is referenced to as services.myService (services is the namespace), this will generate a link to the documenation of myService.
The controller contains one function that returns a Fibonacci number by give index. For this function we define it using @function controllers.MyController#getFibonacciNumberByIndex. The syntax goes: namespace.fileName#functionName. The function takes in one parameter of the expected type {number} and returns a response also of the type {number}. To learn more about other parameter/return types read this.
Now generate your jsdoc by yet again running
grunt build-docs
and then check the generated jsdoc in localhost/docs. You should now see a menu to the right with external sources (Angular), Internal sources (MyService) and defined namespaces (controllers, directives, filters and services). If you click on MyController you should be able to see detailed description of the constructor and the function getFibonacciNumberByIndex.
Custom startpage
Right now the startpage of your jsdoc documentation should be blank, but you can add a custom template by creating a file named jsdoc.md and add a reference to it in your Grunt task:
module.exports = function(grunt) {
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
jsdoc: {
dist: {
src: [
'js/angular/**/*.js',
'js/jsdoc-global-definitions.js',
'js/jsdoc.md'
],
options: {
destination: 'docs',
recurse: true
}
}
}
});
grunt.loadNpmTasks('grunt-jsdoc');
grunt.registerTask('build-docs', [
'jsdoc'
]);
};
The jsdoc.md file should be written using Markdown syntax, same syntax used for Github readme-files. To learn more about it read here.
For an example, see how my file looks.
Custom stylings
If you see my jsdoc for my portfolio website you’ll see that it is a bit more colorful than the regular grey template. If you also wan’t your jsdoc page to have a more fabolous look follow these steps.
After you installed the grunt-jsdoc module using npm you should then be able to find the following folder: /node_modules/jsdoc/templates/default.
Copy this folder to your repository root folder:
sudo cp -rf /myRepo/node_modules/jsdoc/templates/default /myRepo/myTemplate
Now add the following setting to your Gruntfile.js:
module.exports = function(grunt) {
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
jsdoc: {
dist: {
src: [
'js/angular/**/*.js',
'js/jsdoc-global-definitions.js',
'js/jsdoc.md'
],
options: {
destination: 'docs',
recurse: true,
template: './myTemplate'
}
}
}
});
grunt.loadNpmTasks('grunt-jsdoc');
grunt.registerTask('build-docs', [
'jsdoc'
]);
};
Jsdoc will now instead of the default template in node_modules use template found in the myTemplate directory. Now you can modify this template as much as you want, this template folder includes css, scripts and markup that can be modified as you please.
That’s it! I hope you enjoyed this tutorial 🙂 🙂
Martin Sonesson 