{"id":1252,"date":"2016-04-10T21:06:38","date_gmt":"2016-04-10T19:06:38","guid":{"rendered":"https:\/\/www.speich.net\/articles\/?p=1252"},"modified":"2019-12-29T12:47:21","modified_gmt":"2019-12-29T11:47:21","slug":"use-jsdoc-3-and-phpstorm-to-generate-javascript-documentation","status":"publish","type":"post","link":"https:\/\/www.speich.net\/articles\/en\/2016\/04\/10\/use-jsdoc-3-and-phpstorm-to-generate-javascript-documentation\/","title":{"rendered":"Use JSDoc 3 and PhpStorm to generate JavaScript documentation"},"content":{"rendered":"\n

This is an update to my former installation guide How to Generate JavaScript Documentation with JSDoc 3 and PhpStorm<\/a>, which was written in 2013. Since then, JSDoc 3 moved from Mozilla’s Rhino to Node.js to generate the documentation, which is why that guide no longer works (unless you use an older version of JSDoc 3). This installation guide is written for Windows, but should also work on Linux and Mac.<\/p>\n\n\n\n

Install and integrate Node.js<\/h2>\n\n\n\n
  1. Download and install Node.js<\/a>.<\/li>
  2. Integrate Node.js into PhpStorm:
    Open Settings (Ctrl+Alt+S) -> Plugins -> Install JetBrains Plugins -> Search for Node.js -> Install the Plugin
    \"Install<\/figure>Open Settings (Ctrl+Alt+S)  again and go to Languages & Frameworks -> Node.js and NPM. In the Node interpreter<\/span> field, specify the local Node.js interpreter to use. Also press the Enable Node.js core button to enable code assist. For more details about Node.js in PhpStorm read IntelliJ IDEA 2016.1 Help | Node.js<\/a><\/li>
  3. Install the node package manager npm from within PhpStorm:
    Install the npm package manager by clicking on the green add button
    \"icon<\/figure>. Beware to make the installation global by setting Options to -g<\/em>, otherwise you end up with npm in your project folder. The -g<\/em> option will install npm into your folder %AppData%\/npm\/<\/em>
    \"step02\"<\/figure>For more details about using the package manager in PhpStorm read Installing and Removing External Software Using Node Package Manager<\/a>.<\/li><\/ol>\n\n\n\n\n\n\n\n

    Install and integrate JSDoc<\/h2>\n\n\n\n
    1. Install JSDoc with the npm package manager directly from within PhpStrom:
      Open Settings (Ctrl+Alt+S) -> Languages & Frameworks -> Node.js and NPM. Click on the green add button
      \"addbutton\"<\/figure> to install a new package and search for JSDoc. Install the package. Again, use the Options checkbox and specify which folder JSDoc should be installed into or type -g<\/em> to install globally, e.g. %AppData%\/npm\/node_modules\/jsdoc\/<\/em>.
      \"Screenshot<\/figure><\/li>
    2. Optional: Install a different template such as DocStrap<\/a>. You can do this also directly from within PhpStorm the same way you just installed JSDoc above by using the npm package manager. Just search for ink-docstrap<\/em>. Remember: Don’t forget the global switch!Note: I have to document a lot of dojo AMD modules, which return a class created with dojo\/_base\/declare(). I tested several templates, so far the standard JsDoc template is the only one that documents both the module and the class.<\/li>
    3. Integrate JSDoc into PhpStorm by creating an external tool and custom menu:
      Open the Settings Window again (Ctrl+Alt+S), select External Tools<\/em> and click the green add button
      \"icon<\/figure>.
      \"step04\"<\/figure>
      Then provide the following information in the Edit Tool Window:
      Name<\/strong>: JSDoc
      This name will show up in your Tools Menu.
      Group<\/strong>: Documentation
      If you fill in a group name, this will be shown in Tools menu and the name JSDoc will become a submenu of it.
      \"Screenshot<\/figure>
      Program<\/strong>: <Path to node.exe>
      Fill in the path to node.exe, e.g. C:\\Program Files (x86)\\tools\\nodejs\\node.exe
      <\/em>Parameters<\/strong>: <Path to jsdoc.js> -c \u201c<Path to the conf.json file>\u201d
      Fill in the path to jsdoc.js, e.g. C:\\Users\\Simon\\AppData\\Roaming\\npm\\node_modules\\jsdoc\\jsdoc.js
      <\/em>Instead of passing all the       command-line arguments<\/a> to JSDoc, we will use a configuration file by using the -c<\/em> parameter. Also, we use the PhpStorm macro variable $FilePrompt$<\/em> instead of hard coding the path to the configuration file that we will create below. This macro variable will open a file picker dialog to select the config file every time we run the JSDoc Tool (I love PhpStorm!).
      Important: If any of your paths contain spaces, you have to enclose them in quotes. This is also true for the $FilePrompt$<\/em> macro!!!
      Working directory<\/strong>: <Path to the project you want to document>
      Also, instead of hard coding the path to the project you want to document such as C:\\Users\\Public\\Websites\\remoteFileExplorer<\/em>, we use the macro variable $ProjectFileDir$,<\/em> so JSDoc will always document the project currently open in PhpStorm.<\/li><\/ol>\n\n\n\n

      Configure JSDoc<\/h2>\n\n\n\n

      The easiest way of configuring JSDoc, is to use the configuration file conf.json<\/em> (rename the conf.json.example<\/em> in the JsDoc directory) instead of the command-line arguments:<\/p>\n\n\n\n

      {\n    \"tags\": {\n        \"allowUnknownTags\": true,\n        \"dictionaries\": [\"jsdoc\"]\n    },\n    \"source\": {\n        \"include\": [\".\/\"],\n        \"includePattern\": \".+\\\\.js$\",\n        \"excludePattern\": \"(docs)\"\n    },\n    \"plugins\": [],\n    \"templates\": {\n        \"cleverLinks\": false,\n        \"monospaceLinks\": true,\n        \"systemName\": \"NAFIDAS\",\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\": \"..\/ink-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>: \u201c.\/\u201d references the current working directory, so don\u2019t change that.
      includePattern<\/strong>: Only files ending in \u201c.js\u201d will be processed.
      excludePattern<\/strong>: Don\u2019t document the documentation!
      destination<\/strong>: \u201c<Path to where to generate the docs>\u201d 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<\/em>
      recurse<\/strong>: true. Process all subfolders recursively.
      template<\/strong>: Optional. “<path to the docstrap template>”<\/p>\n\n\n\n
      That\u2019s all. Happy documenting!<\/p>\n","protected":false},"excerpt":{"rendered":"
      This is an update to my former installation guide How to Generate JavaScript Documentation with JSDoc 3 and PhpStorm, which was written in 2013. Since then, JSDoc 3 moved from Mozilla’s Rhino to Node.js to generate the documentation, which is why that guide no longer works (unless you use an older version of JSDoc 3). … <\/p>\n
      Continue reading “Use JSDoc 3 and PhpStorm to generate JavaScript documentation”<\/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":[48,228,75],"class_list":["post-1252","post","type-post","status-publish","format-standard","hentry","category-javascript","tag-jsdoc-3","tag-node-js","tag-phpstorm","entry"],"_links":{"self":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/1252","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=1252"}],"version-history":[{"count":29,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/1252\/revisions"}],"predecessor-version":[{"id":1749,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/posts\/1252\/revisions\/1749"}],"wp:attachment":[{"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/media?parent=1252"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/categories?post=1252"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.speich.net\/articles\/wp-json\/wp\/v2\/tags?post=1252"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}