Documenting a code is very important, specially when you are working in a team. For java, JavaDoc has been my favorite. But there seems to be a lack of documentation tools for Javascript. The one that I found most easy to use (transitioning from JavaDoc) was jsdoc-toolkit. But since there was no good tutorial for how to begin documenting jQuery plugins with jsdoc, I decided to write one.
Installation in Ubuntu is simple. Just use apt-get install.
sudo apt-get install jsdoc-toolkitI won’t go into the details for other platforms but it should be pretty simple to install on other platforms as well. To generate the documentation, use:
jsdoc -d=./doc ./srcThis would generate the documentation in doc directory for the files in src. The main issues start from here because when you try to document your jQuery plugin using this, it doesn’t recognize the friendly $. Nor does it know what jQuery is.
Trying to document jMatrixBrowse as a member of undocumented symbol jQuery
Trying to document jMatrixBrowse as a member of undocumented symbol jQuery.fnTrying to document jMatrixBrowse as a member of undocumented symbol $
Trying to document jMatrixBrowse as a member of undocumented symbol $.fnThere is a simple way to tell this to it. Just write these comments at the top of the file where you would like to use jQuery.
/**
* See (https://jquery.com/).
* @name jQuery
* @class
* See the jQuery Library (https://jquery.com/) for full details. This just
* documents the function and classes that are added to jQuery by this plug-in.
*/
/**
* See (https://jquery.com/)
* @name fn
* @class
* See the jQuery Library (https://jquery.com/) for full details. This just
* documents the function and classes that are added to jQuery by this plug-in.
* @memberOf jQuery
*/This tells jsdoc about jQuery and jQuery.fn and you can then begin writing documentation for your plugin.
/**
* myAwesomePlugin - an awesome jQuery plugin.
*
* @class myAwesomePlugin
* @memberOf jQuery.fn
*/
jQuery.fn.myAwesomePlugin = function() {
}You can also write a file overview to be included in the documentation by writing this at the top.
/**
* @fileOverview Contains the awesome plug-in code.
* @version 0.1
* @author Pulkit Goyal <pulkit110@gmail.com>
*/The detailed documentation for functions is very similar to JavaDoc style. Here’s a sample.
/**
* Get user defined options from data-* elements.
* @param {jQuery object} elem - the element to retrieve the user options from.
* @returns {Object} options - User's options for the plugin.
*/
function getUserOptions(elem) {
}