{"id":739,"date":"2013-08-16T14:23:38","date_gmt":"2013-08-16T12:23:38","guid":{"rendered":"http:\/\/www.speich.net\/articles\/?p=739"},"modified":"2019-10-06T12:21:03","modified_gmt":"2019-10-06T10:21:03","slug":"quick-tip-how-to-document-a-dojo-amd-module-for-jsdoc-3","status":"publish","type":"post","link":"https:\/\/www.speich.net\/articles\/en\/2013\/08\/16\/quick-tip-how-to-document-a-dojo-amd-module-for-jsdoc-3\/","title":{"rendered":"Quick tip: How to document a dojo AMD module for JSDoc 3"},"content":{"rendered":"\n

Unfortunately, JSDoc 3 <\/a>does not fully support documenting AMD style modules<\/a> that return a declare function, e.g.:<\/p>\n\n\n\n

define(['dojo\/_base\/declare'], function(declare) {\n    ...\n    return declare([], {\n        ...\n    });\n});<\/code><\/pre>\n\n\n\n
But with a bit of verbosity each module and the class will be properly documented:<\/p>\n\n\n\n\n\n\n\n
\/**\n * Module returning a class to create and handle the legend for absolute values of the mapping application.\n * @module NAFIDAS\/mapping\/LegendProportional\n * @see NAFIDAS.mapping.LegendProportional\n *\/\ndefine([\n    'dojo\/_base\/declare',\n    'NAFIDAS\/mapping\/Legend',\n    ...\n], function(declare, Legend, ...) {\n\n    \/**\n     * Class to create and handle the legend for absolute values of the mapping application.\n     * @class NAFIDAS.mapping.LegendProportional\n     * @extends {NAFIDAS.mapping.Legend}\n     * @property {String} templateString\n     * @property {Object} surface reference to gfx surface\n     * @property {Object} surfaceSize dimensions of the surface\n     * @property {Number} surfaceSize.w width\n     * @property {Number} surfaceSize.h height\n     * @property {Number} minVirtSpacing defines minimal vertical spacing of legend items\n     *\/\n    return declare([Legend, ...], \/** @lends NAFIDAS.mapping.LegendProportional.prototype *\/ {\n\n        templateString: template,\n        surface: null,\n        surfaceSize: {\n            w: 300,\n            h: 90\n        },\n        minVirtSpacing: 14,\n        ...\n\n        \/**\n         * Calculates and sets the canvas height.\n         * If there are negative and positive numbers, canvas height has to be enlarged \n         * by the height of the smaller maximum circle.\n         * @return {*}\n         * @private\n         *\/\n        _setSizes: function() {\n           ...\n        },\n\n        \/**\n         * Returns a radius calculated proportionally from the maximum value and area.\n         * @param {Number} val value\n         * @param {Number} maxVal maximum value\n         * @param {Number} maxArea maximum area\n         * @return {Number}\n         *\/\n        calcRadiusFromValue: function(val, maxVal, maxArea) {\n            ...\n        },\n\n        ...\n\n    });\n});<\/code><\/pre>\n\n\n\n
\"jsdoc-output-module\"<\/figure><\/div>\n\n\n\n
\"jsdoc-output-class\"<\/figure><\/div>\n\n\n\n
Running JsDoc 3 with the code documented above will generate the nicely formatted HTML output below:Another option would be to use dojo’s own doc parser<\/a> with dojo inline documentation<\/a> instead of JsDoc 3, but that does not integrate well with an IDE such as PhpStorm (no or only partial code assist).<\/p>\n\n\n\n
BTW, if you want to see the documented code in action head over to to he mapping application of the Swiss National Forest Inventory.<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"
Unfortunately, JSDoc 3 does not fully support documenting AMD style modules that return a declare function, e.g.: define([‘dojo\/_base\/declare’], function(declare) { … return declare([], { … }); }); But with a bit of verbosity each module and the class will be properly documented:<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[26],"class_list":["post-739","post","type-post","status-publish","format-standard","hentry","category-javascript","tag-dojo","entry"],"_links":{"self":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/739","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/comments?post=739"}],"version-history":[{"count":5,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/739\/revisions"}],"predecessor-version":[{"id":1685,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/739\/revisions\/1685"}],"wp:attachment":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/media?parent=739"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/categories?post=739"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/tags?post=739"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}