{"id":462,"date":"2013-07-19T18:00:36","date_gmt":"2013-07-19T16:00:36","guid":{"rendered":"http:\/\/www.speich.net\/articles\/?p=462"},"modified":"2019-10-06T12:22:39","modified_gmt":"2019-10-06T10:22:39","slug":"generate-javascript-documentation-with-jsdoc-3-and-phpstorm","status":"publish","type":"post","link":"https:\/\/www.speich.net\/articles\/en\/2013\/07\/19\/generate-javascript-documentation-with-jsdoc-3-and-phpstorm\/","title":{"rendered":"How to Generate JavaScript Documentation with JSDoc 3 and PhpStorm"},"content":{"rendered":"\n

This guide is outdated<\/strong>. I wrote the new tutorial Use JSDoc 3 and PhpStorm to generate JavaScript documentation<\/a><\/p>\n\n\n\n

This is an update to my previous article How to create JavaScript documentation in PhpStorm<\/a>, since the JsDoc Toolkit is no longer under active development. It got replaced by JSDoc 3, with better support for current coding practices, particularly the CommonJS Modules<\/a> standard and also its improved format, Asynchronous Module Definition<\/a> (AMD).<\/p>\n\n\n\n

This guide should not only work for Jetbrains’ PhpStorm, but any IDE, such as Eclipse or Aptana, that lets you call an external tool with parameters. It is written for Windows 7, but should also work for Mac\/Unix users with minor modifications. It assumes you have installed Java Runtime JRE 1.7 and added it to the Window system path.<\/p>\n\n\n\n\n\n\n\n

We will set up JSDoc 3 as an external tool to PhpStorm in such a way that it will work for any project by using PhpStorm macro variables and the configuration file conf.json for JSDoc 3. Furthermore, we use a template called DocStrap instead of the default template.<\/p>\n\n\n\n

Step by Step Instructions<\/h2>\n\n\n\n

1.<\/strong> Start PhpStorm and clone JSDoc 3<\/a> from GitHub.
If you put it somewhere under C:\\Users\\Public you don’t have to worry about permissions. I put it to C:\\Users\\Public\\Website\\Tools\\jsdoc3<\/p>\n\n\n\n

2<\/strong>. [optional]. If you want to use the default template you can skip this step, otherwise clone DocStrap<\/a> from GitHub into the templates directory of JSDoc 3, e.g. C:\\Users\\Public\\Website\\Tools\\jsdoc3\\templates<\/p>\n\n\n\n

3.<\/strong> Open the project containing the JavaScript files you want to document and create a file named conf.json which is going to be the configuration file for JSDoc 3<\/a>. Then add the following json object to it:<\/p>\n\n\n\n

{\n    \"tags\": {\n        \"allowUnknownTags\": true\n    },\n    \"source\": {\n        \"include\": [\".\/\"],\n        \"includePattern\": \".+\\.js(doc)?$\",\n        \"excludePattern\": \"docs\"\n    },\n    \"plugins\": [],\n    \"templates\": {\n        \"cleverLinks\": false,\n        \"monospaceLinks\": true,\n        \"systemName\": \"remoteFileExplorer\",\n        \"footer\": \"Created by Simon Speich\",\n        \"copyright\": \"2013\",\n        \"navType\": \"vertical\",\n        \"theme\": \"spacelab\",\n        \"linenums\": true,\n        \"collapseSymbols\": true,\n        \"inverseNav\": false\n    },\n    \"opts\": {\n        \"template\": \"C:\\\\Users\\\\Public\\\\WebsiteTools\\\\jsdoc3\\\\templates\\\\docstrap\\\\template\",\n        \"encoding\": \"utf8\",\n        \"destination\": \"docs\/js\",\n        \"recurse\": true,\n        \"private\": true\n    }\n}<\/code><\/pre>\n\n\n\n
include<\/strong>: “.\/” references the working directory we will set up in PhpStorm External Tools, so don’t change that.
includePattern<\/strong>: Only files ending in “.js” and “.jsdoc” will be processed.
excludePattern<\/strong>: Don’t document the documentation!
destination<\/strong>: “<Path to where to generate the docs>” If the path to where you want the documentation generated is outside of your project, you can also use Windows absolute paths with backslashes, but you need to escape them, e.g. C:\\\\Users\\\\Public\\\\Websites\\\\remoteFileExplorer\\\\docs\\\\js
recurse<\/strong>: true. Process all subfolders recursively.<\/p>\n\n\n\n
Note: All quotation marks are required and all path settings are always relative to the working directory (e.g. your project) we will set up in PhpStorm below.<\/p>\n\n\n\n
4.<\/strong> Open the Settings Window (Ctrl + Alt + S) in PhpStorm, select External Tools
and click the add button +.<\/p>\n\n\n\n
\"Screenshot<\/a><\/figure><\/div>\n\n\n\n
Then provide the following information in the Edit Tools Window:<\/p>\n\n\n\n
\"Screenshot<\/a><\/figure><\/div>\n\n\n\n
Name<\/strong>: JSDoc 3
This name will show up in your Tools Menu.<\/p>\n\n\n\n
Group<\/strong>: Documentation
If you fill in a group name, then this will be shown in the Tools menu and the name JSDoc 3 will become a submenu of it.<\/p>\n\n\n\n
\"Screenshot<\/a><\/figure><\/div>\n\n\n\n
Program<\/strong>: <Path to JSDoc 3jsdoc.cmd>
Fill in the path to the jsdoc.cmd, e.g.: C:\\Users\\Public\\Website\\Tools\\jsdoc3\\jsdoc.cmd Important on Windows: Do not use the jsdoc file directly, instead use the provided command file jsdoc.cmd, which sets up all the correct paths for you. For Mac and Unix users, the jsdoc file will probably do fine (not tested).<\/p>\n\n\n\n
Parameters<\/strong>: -c “<Path to the conf.json file>”
Instead of hardcode the path to the configuration file we’ve created in step 2, we use the PhpStorm macro variable $FilePrompt$. This macro variable will open a file picker dialog to select the config file every time we run the JSDoc 3 Tool (did I already mention that I love PhpStorm?!).<\/p>\n\n\n\n
Note: Enclose the macro variable in quotes if your path contains spaces!<\/p>\n\n\n\n
Working directory<\/strong>: <Path to the project you want to document>
Also instead of hard wiring the path to the project you want to document such as C:\\Users\\Public\\Websites\\remoteFileExplorer, we use the macro variable $ProjectFileDir$ so JSDoc will always document the project currently open in PhpStorm.<\/p>\n\n\n\n
That’s all. Happy documenting!<\/p>\n","protected":false},"excerpt":{"rendered":"
This guide is outdated. I wrote the new tutorial Use JSDoc 3 and PhpStorm to generate JavaScript documentation This is an update to my previous article How to create JavaScript documentation in PhpStorm, since the JsDoc Toolkit is no longer under active development. It got replaced by JSDoc 3, with better support for current coding … <\/p>\n
Continue reading “How to Generate JavaScript Documentation with JSDoc 3 and PhpStorm”<\/span><\/a><\/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":[9,18,48,75],"class_list":["post-462","post","type-post","status-publish","format-standard","hentry","category-javascript","tag-amd","tag-commonjs","tag-jsdoc-3","tag-phpstorm","entry"],"_links":{"self":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/462","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=462"}],"version-history":[{"count":6,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/462\/revisions"}],"predecessor-version":[{"id":1686,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/462\/revisions\/1686"}],"wp:attachment":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/media?parent=462"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/categories?post=462"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/tags?post=462"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}