{"id":588,"date":"2021-03-30T22:30:48","date_gmt":"2021-03-31T03:30:48","guid":{"rendered":"https:\/\/www.becomebetterprogrammer.com\/?p=588"},"modified":"2022-04-25T09:46:38","modified_gmt":"2022-04-25T14:46:38","slug":"the-ultimate-guide-to-javascript-documentation-using-jsdocs","status":"publish","type":"post","link":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/","title":{"rendered":"The Ultimate Guide to JavaScript Documentation Using JSDocs"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">First and most importantly, I want to congratulate you.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><em>Wait, What?<\/em><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Yes, you heard it right. Congratulations! Writing proper documentation helps you get one step closer to writing clean code. If you don\u2019t believe me, you might want to read the book <a href=\"http:\/\/cleancoder.com\/products\" target=\"_blank\" rel=\"noreferrer noopener\">Clean Coder<\/a> from \u201cUncle\u201d Bob. Trust me, it is an excellent investment in your programming career.<a href=\"https:\/\/becomebetterprogrammer.com\/blogs\/is-it-really-worth-reading-the-clean-coder-takeaways-chapter-by-chapter\"> I wrote an article sharing the major takeaways from reading the Clean Coder<\/a>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Enough talking and straight to the topic.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I am a firm believer in the following statement: high quality written code doesn\u2019t need to be documented.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The reason why is because the code should be written in a way that is easy to read.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">It\u2019s like reading any of the <a href=\"https:\/\/www.dummies.com\/\" target=\"_blank\" rel=\"noreferrer noopener\">dummies<\/a> books, they are written with the purpose of making the learning process easy.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In a similar way, code needs to be written for dummies.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><em>Are you calling me a dummy?<\/em><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">No, but you deserve one for that question dummy.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Write code that is easy to read. However, I know what you are going to tell me\u2026<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><em>Even after writing quality code, it can take time to understand how everything works for someone new to the codebase.<\/em><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In this case, I have to acknowledge you are right. In my years of experience in the software development industry, I must admit documenting your code is not a luxury, but a necessity.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I love writing code using JavaScript. It allows me to develop the front-end and the back-end of an application with the same programming language.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">JavaScript is known for its high flexibility, and it is because of that flexibility that too many problems can arise if you are not experienced enough with the programming language. Among the several issues found is the lack of data types defined in functions or variables.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Yes, TypeScript has been the solution for this never-ending JavaScript problem. However, sometimes you are in projects in which it is impossible to start all the way from zero to write your code in TypeScript rather than JavaScript. This is mostly found in Node.js + Express.js APIs as well as React.js apps.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Writing proper documentation in JavaScript does take your code to the next level.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I mean it.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">You can write JavaScript documentation using JSDoc. Please, allow me to be your instructor for today.<\/p>\n\n\n\n<div id=\"ez-toc-container\" class=\"ez-toc-v2_0_84 counter-hierarchy ez-toc-counter ez-toc-custom ez-toc-container-direction\">\n<div class=\"ez-toc-title-container\"><p class=\"ez-toc-title\" style=\"cursor:inherit\">Table of Contents<\/p>\n<\/div><nav><ul class='ez-toc-list ez-toc-list-level-1 ' ><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-1\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#What_is_JSDoc\" >What is JSDoc?<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-2\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Configure_Visual_Studio_Code\" >Configure Visual Studio Code<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-3\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Learn_By_Example\" >Learn By Example<\/a><ul class='ez-toc-list-level-4' ><li class='ez-toc-heading-level-4'><a class=\"ez-toc-link ez-toc-heading-4\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Simplest_form_of_Documentation_by_providing_a_description\" >Simplest form of Documentation by providing a description<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-4'><a class=\"ez-toc-link ez-toc-heading-5\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Using_JSDoc_tags_to_describe_your_code\" >Using JSDoc tags to describe your code<\/a><\/li><\/ul><\/li><\/ul><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-6\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Most_Commonly_used_JSDoc_Tags\" >Most Commonly used JSDoc Tags<\/a><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-7\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#return_or_returns_tag\" >@return or @returns tag<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-8\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#param_tag\" >@param tag<\/a><\/li><\/ul><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-9\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#What_are_the_data_types_supported_by_JSDoc\" >What are the data types supported by JSDoc?<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-10\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Using_Custom_Data_Types\" >Using Custom Data Types<\/a><ul class='ez-toc-list-level-3' ><li class='ez-toc-heading-level-3'><a class=\"ez-toc-link ez-toc-heading-11\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Defining_the_Type_Definition_using_typedef_and_property_tags\" >Defining the Type Definition using @typedef and @property tags<\/a><\/li><\/ul><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-12\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Using_Custom_Data_Types_in_multiple_files\" >Using Custom Data Types in multiple files<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-13\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Using_Custom_Data_Types_Without_Defining_the_Data_Type\" >Using Custom Data Types Without Defining the Data Type<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-14\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Resources\" >Resources<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-15\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Funny_Fact\" >Funny Fact<\/a><\/li><li class='ez-toc-page-1 ez-toc-heading-level-2'><a class=\"ez-toc-link ez-toc-heading-16\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/#Conclusions\" >Conclusions<\/a><\/li><\/ul><\/nav><\/div>\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"What_is_JSDoc\"><\/span>What is JSDoc?<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">According to Wikipedia, <em><a href=\"https:\/\/en.wikipedia.org\/wiki\/JSDoc\" target=\"_blank\" rel=\"noreferrer noopener\">JSDoc<\/a> is a markup language used to annotate JavaScript source code files.<\/em><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">If this doesn\u2019t make sense, <strong>I will explain it with my own words: JSDoc allows you to add comments to document your JavaScript code.<\/strong><\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Configure_Visual_Studio_Code\"><\/span>Configure Visual Studio Code<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Before we start learning how to implement JSDocs in our JavaScript code, we are going to modify the configuration in Visual Studio Code.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In Visual Studio Code, go to <em>Preferences &gt; Settings<\/em>. Then, add the following configuration:<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\"javascript.implicitProjectConfig.checkJs\": true<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Once this process is completed, you will start noticing Visual Studio Code is acting as TypeScript. Feel free to change this configuration back to its default value if you don\u2019t like it after completing this tutorial.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Learn_By_Example\"><\/span>Learn By Example<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">One of the most effective ways to learn is by example, and that\u2019s exactly what we are going to do in this simple, yet important tutorial.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Simplest_form_of_Documentation_by_providing_a_description\"><\/span>Simplest form of Documentation by providing a description<span class=\"ez-toc-section-end\"><\/span><\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s start with a simple function. In this case, you will see the <strong>getCities <\/strong>function.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>function getCities() {\n    return [ \n       'Barranquilla', 'San Francisco', 'Austin', \n       'Miami', 'Chicago', 'New York', 'London',\n       'Bogota', 'Buenos Aires', 'Madrid'\n    ];\n }\n<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s analyze this for a second.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Based on the function\u2019s name, we can infer we are going to expect to get cities. For many of you, this doesn\u2019t need documentation.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">However, depending on how serious you are about writing documentation, you would add comments prior to your function.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * gets a list of cities from all over the world\n *\/\n function getCities() {\n    return [ \n       'Barranquilla', 'San Francisco', 'Austin', \n       'Miami', 'Chicago', 'New York', 'London',\n       'Bogota', 'Buenos Aires', 'Madrid'\n    ];\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Now, we are using JSDocs. Generally, we provide a brief description of what the function does.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Sometimes you will find yourself feeling like explaining something that is already self-explanatory. However, you will get good at writing simple, yet meaningful descriptive comments.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Although this is a start, let me tell you that you became better than most average JavaScript programmers.<br>I\u2019m serious.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s keep learning more.<\/p>\n\n\n\n<h4 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Using_JSDoc_tags_to_describe_your_code\"><\/span>Using JSDoc tags to describe your code<span class=\"ez-toc-section-end\"><\/span><\/h4>\n\n\n\n<p class=\"wp-block-paragraph\">JSDoc provides special tags that can be used to provide more information related to your code. Using our previous example, we could use the tag <strong>@description<\/strong> to mention that the comment next to the tag represents a description.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of cities from all over the world\n *\/\n function getCities() {\n    return [ \n      'Barranquilla', 'San Francisco', 'Austin', \n      'Miami', 'Chicago', 'New York', 'London',\n      'Bogota', 'Buenos Aires', 'Madrid'\n    ];\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">There is a longer list of special tags you could use with JSDocs, which you can find in their <a href=\"https:\/\/jsdoc.app\/index.html#block-tags\" target=\"_blank\" rel=\"noreferrer noopener\">website<\/a>.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Most_Commonly_used_JSDoc_Tags\"><\/span>Most Commonly used JSDoc Tags<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In this section we are going to cover the special tags that are used over and over to document JavaScript code.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"return_or_returns_tag\"><\/span>@return or @returns tag<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s make some changes to our <strong>getCities <\/strong>function. After all, our code can be changed at any point. In this case, I\u2019m going to convert the function to return the countries associated with the cities.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of location objects with cities from all over the world\n *\/\n function getLocations() {\n    return [\n       { country: \"Colombia\", city: \"Barranquilla\" },\n       { country: \"USA\", city: \"San Francisco\" },\n       { country: \"USA\", city: \"Austin\" },\n       { country: \"England\", city: \"London\" },\n       { country: \"Argentina\", city: \"Buenos Aires\" },\n       { country: \"Spain\", city: \"Madrid\" },\n    ];\n };<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">If you noticed, our function is no longer called <strong>getCities<\/strong>, and now it is called <strong>getLocations<\/strong>. We updated the result and the documentation if you didn\u2019t notice.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">If you are using Visual Studio Code as your IDE of choice, you should hover over the function, and you will notice the description of the function as well as the object structure of the result.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"802\" height=\"436\" src=\"https:\/\/www.becomebetterprogrammer.com\/wp-content\/uploads\/2021\/03\/VS-Code-displaying-documentation.png\" alt=\"\" class=\"wp-image-597\" srcset=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/VS-Code-displaying-documentation.png 802w, https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/VS-Code-displaying-documentation-300x163.png 300w, https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/VS-Code-displaying-documentation-768x418.png 768w\" sizes=\"auto, (max-width: 802px) 100vw, 802px\" \/><figcaption>Visual Studio Code Intellisense Tool in action when implementing JSDoc<\/figcaption><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">You could also specify what kind of object the function returns using the <strong>@return<\/strong> or <strong>@returns<\/strong> tag.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of location objects with cities from all over the world\n * \n * @returns {{country: string, city: string}[]} - locations \n *\/\n function getLocations() {\n    return [\n       { country: \"Colombia\", city: \"Barranquilla\" },\n       { country: \"USA\", city: \"San Francisco\" },\n       { country: \"USA\", city: \"Austin\" },\n       { country: \"England\", city: \"London\" },\n       { country: \"Argentina\", city: \"Buenos Aires\" },\n       { country: \"Spain\", city: \"Madrid\" },\n    ];\n };<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">To specify the object type returned using the @returns tag, you will have to wrap the data type inside curly braces. You can see other examples below.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @returns {string} country record\n *\/\n function getCountry() {\n    return 'Colombia';\n }\n \/**\n * \n * @returns {string[]} list of countries\n *\/\n function getCountries() {\n    return ['Colombia', 'USA', 'England', 'Argentina', 'Spain'];\n }\n \/**\n * \n * @returns {number[]} list of country codes\n *\/\n function getCountryCodes() {\n    return [57, 1, 44, 54, 34];\n }\n \/**\n * @returns {{country: string, city: string}} - location recorded\n *\/\n function getLocation() {\n    return { country: \"Colombia\", city: \"Barranquilla\" };\n }\n \/**\n * @returns {Date} the current date\n *\/\n function now() {\n    return new Date();\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">If you noticed, I\u2019ve used different data types such as string, array of strings, array of numbers, date, and even custom objects.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Are you starting to feel like you are using <a href=\"https:\/\/www.typescriptlang.org\/\" target=\"_blank\" rel=\"noreferrer noopener\">Typescript<\/a>? In my opinion, I am.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"param_tag\"><\/span>@param tag<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">The likelihood of us writing functions without parameters is slim, and parameters are part of the codebase that needs to be documented.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s look at a simple example of how we use the <strong>@param<\/strong> tag. That\u2019s why we are going to make minor changes to our <strong>getLocations <\/strong>function to add the ability to filter the locations based on the country provided.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of location objects with cities from all over the world\n *\n * @param {string} country - provide the country of the cities to fetch\n *\n * @returns {{country: string, city: string}[]} locations\n *\/\n function getLocations(country) {\n    return [\n      { country: \"Colombia\", city: \"Barranquilla\" },\n      { country: \"USA\", city: \"San Francisco\" },\n      { country: \"USA\", city: \"Austin\" },\n      { country: \"England\", city: \"London\" },\n      { country: \"Argentina\", city: \"Buenos Aires\" },\n      { country: \"Spain\", city: \"Madrid\" },\n   ].filter((location) =&gt; location.country === country);\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Now, let\u2019s attempt to call the function using VSCode and let\u2019s inspect the results.<\/p>\n\n\n\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"585\" height=\"271\" src=\"https:\/\/www.becomebetterprogrammer.com\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-2.png\" alt=\"\" class=\"wp-image-599\" srcset=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-2.png 585w, https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-2-300x139.png 300w\" sizes=\"auto, (max-width: 585px) 100vw, 585px\" \/><\/figure><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Did you see what happened?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Visual Studio Code Intellisense to the rescue!<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">In this case, Intellisense is providing us with meaningful information about the parameter data type we need to provide. In this example, we can infer the parameter <strong>country <\/strong>will be a data type of string.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">However, I will make changes to the function again and include the parameter <strong>id<\/strong>.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of location objects with cities from all over the world\n *\n * @returns {{country: string, city: string}[]} locations\n *\/\n function getLocations(id) {\n    return [\n       { id: 1, country: \"Colombia\", city: \"Barranquilla\" },\n       { id: 2, country: \"USA\", city: \"San Francisco\" },\n       { id: 3, country: \"USA\", city: \"Austin\" },\n       { id: 4, country: \"England\", city: \"London\" },\n       { id: 5, country: \"Argentina\", city: \"Buenos Aires\" },\n       { id: 6, country: \"Spain\", city: \"Madrid\" },\n    ].filter((location) =&gt; location.id === id);\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">What do you think the value of <strong>id<\/strong> should be? A <em>string<\/em>? A <em>number<\/em>?<\/p>\n\n\n\n<figure class=\"wp-block-image size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"699\" height=\"262\" src=\"https:\/\/www.becomebetterprogrammer.com\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-3.png\" alt=\"\" class=\"wp-image-600\" srcset=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-3.png 699w, https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-3-300x112.png 300w\" sizes=\"auto, (max-width: 699px) 100vw, 699px\" \/><\/figure>\n\n\n\n<p class=\"wp-block-paragraph\">How many times have you jumped into a new project and read the code for a while to know the kind of data type of the <strong>id <\/strong>parameter?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Even worse, have you had to check the database table to understand the data types as you still can\u2019t easily figure out the <strong>id <\/strong>data type after inspecting the code?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Making a small change like adding the <strong>@param<\/strong> tag to the documentation might initially seem irrelevant, but in the long run other programmers will thank you.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/* @param {string} id - provide the id of the location to fetch<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">After making our changes, we get an understandable description of what the function does, and we no longer need to guess what data types each parameter of our function has.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"727\" height=\"451\" src=\"https:\/\/www.becomebetterprogrammer.com\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-4.png\" alt=\"\" class=\"wp-image-601\" srcset=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-4.png 727w, https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-4-300x186.png 300w\" sizes=\"auto, (max-width: 727px) 100vw, 727px\" \/><\/figure><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">This is much better and makes our JavaScript development much smoother.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"What_are_the_data_types_supported_by_JSDoc\"><\/span>What are the data types supported by JSDoc?<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">In the previous examples, you noticed the usage of some data types. However, in case you are not familiar with the available options, the following are data types that can be used with JSDocs:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>Null<\/li><li>Undefined<\/li><li>Boolean<\/li><li>Number<\/li><li>String<\/li><li>Object<\/li><li>Array<\/li><li>Set<\/li><li>Date<\/li><li>Void (Used if your function doesn\u2019t return anything)<\/li><li>Function<\/li><\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">All these data types are built-in JavaScript types.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Using_Custom_Data_Types\"><\/span>Using Custom Data Types<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">As you know JavaScript provides tons of flexibility when it comes to generating, i.e., custom Objects or Arrays. This can be either a benefit or the root of messy code depending on the opinion you have about JavaScript.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Nevertheless, we are faced with custom data types day in day out. Fortunately, we can define custom data types with JSDoc.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Defining_the_Type_Definition_using_typedef_and_property_tags\"><\/span>Defining the Type Definition using @typedef and @property tags<span class=\"ez-toc-section-end\"><\/span><\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">In <strong>getLocations <\/strong>function example, you saw we were returning an array of location objects. Therefore, we defined the object returned the following way:<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/* @returns {{id: number, country: string, city: string}[]} locations<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">This is perfectly fine. However, if this location object is used over and over for several processes in our code, it will turn into a bulkier documentation. Also, in case we decide to return more values related to a <em>LocationOption <\/em>object, i.e. longitude and latitude, we will have to update the object structure everywhere we have decided to use a location object in our code\u2026<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">\u2026 and that\u2019s not fun.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Or, what usually happens, you will forget to update the documentation everywhere else.<br>Therefore, we are going to define our custom data type object using @typedef and @property tags like in the following example:<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @typedef LocationOption\n * \n * @property {number} id\n * @property {string} country\n * @property {string} city\n *\/<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Having defined our <em>LocationOption <\/em>data type, we can now update our <strong>getLocations <\/strong>function\u2019s documentation\u2026<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of location objects with cities from all over the world\n *\n * @param {number} id provide the id of the location to fetch\n *\n * @returns {LocationOption[]} locations\n *\/\n function getLocations(id) {\n    return [\n       { id: 1, country: \"Colombia\", city: \"Barranquilla\" },\n       { id: 2, country: \"USA\", city: \"San Francisco\" },\n       { id: 3, country: \"USA\", city: \"Austin\" },\n       { id: 4, country: \"England\", city: \"London\" },\n       { id: 5, country: \"Argentina\", city: \"Buenos Aires\" },\n       { id: 6, country: \"Spain\", city: \"Madrid\" },\n     ].filter((location) =&gt; location.id === id);\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">\u2026and the best of all this is when you are leveraging Visual Studio Code to your own benefit to understand the correct data type of a variable:<\/p>\n\n\n\n<div class=\"wp-block-image\"><figure class=\"aligncenter size-large\"><img loading=\"lazy\" decoding=\"async\" width=\"670\" height=\"168\" src=\"https:\/\/www.becomebetterprogrammer.com\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-5-1.png\" alt=\"\" class=\"wp-image-604\" srcset=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-5-1.png 670w, https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-content\/uploads\/2021\/03\/The-Ultimate-Guide-to-Write-Professional-JavaScript-Documentation-using-JSDocs-Image-5-1-300x75.png 300w\" sizes=\"auto, (max-width: 670px) 100vw, 670px\" \/><\/figure><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">I feel I\u2019m in TypeScript land without using it, ditching the compilers required to convert your TypeScript code to JavaScript.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Using_Custom_Data_Types_in_multiple_files\"><\/span>Using Custom Data Types in multiple files<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s be honest, our applications are often composed by multiple files. Multiple files representing, i.e., in the case of APIs, controllers, services, routes, queries, middlewares, etc.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Let\u2019s say our custom <em>LocationOption<\/em> data type will be used in different services. If you want to use the custom data type on your documentation, you will need to define the same data type on each service file.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><em>\u201cNope, I ain\u2019t doing that!\u201d<\/em><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Don\u2019t worry, I hear you on that.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Lately, I\u2019ve been using the following approach to solve this is by defining a <em>myService.typedefinitions.js<\/em> file. There I define the custom data type definitions.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">If you configured your Visual Studio Code to enable semantic check for JavaScript file, the IDE should recognize in all your files the existence of the custom data types.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">However, if you didn\u2019t set this configuration, you will need to import <em>myService.typedefinitions.js<\/em> files to your JavaScript files.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>require('.\/example.typedefinitions');<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Another approach for this is to set up a <em>@types\/myProject<\/em> folder where you will generate all the files containing all the type definitions used on your project, i.e.:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li><em>@types\/myProject<\/em><ul><li><span style=\"text-decoration: underline;\"><em>car.typedefinitions.js or car.d.js<\/em><\/span><\/li><li><span style=\"text-decoration: underline;\"><em>person.typedefinitions.js or person.d.js<\/em><\/span><\/li><li><span style=\"text-decoration: underline;\"><em>location.typedefinitions.js or location.d.js<\/em><\/span><\/li><\/ul><\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Using_Custom_Data_Types_Without_Defining_the_Data_Type\"><\/span>Using Custom Data Types Without Defining the Data Type<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">There are different circumstances when you don\u2019t want to set a custom data type as it could be a one case scenario where you will see this custom data type.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">One example of this is when configuring an API using Node.js + <a href=\"https:\/\/expressjs.com\/https:\/\/expressjs.com\/\" target=\"_blank\" rel=\"noreferrer noopener\">Express.js<\/a>. If you have used Express.js, you know you can set a <a href=\"https:\/\/expressjs.com\/en\/starter\/hello-world.html\" target=\"_blank\" rel=\"noreferrer noopener\">simple endpoint<\/a> with the route of <em>\/locations<\/em>:<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>const express = require('express');\n const app = express();\n const port = 3000;\n app.get('\/locations', getLocations));\n app.listen(port, () =&gt; {\n    console.log(`Example app listening at http:\/\/localhost:${port}`)\n });<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Once again, we need to make small changes to our <strong>getLocations <\/strong>function to accept the Express request and response as parameters. We will still provide an <strong>id <\/strong>to filter locations based on the <strong>id <\/strong>query parameter.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Finally, we will send the results as part of the response body.<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/**\n * @description gets a list of location objects with cities from all over the world\n *\n *\/\n function getLocations(req, res) {\n    res.send(\n      [\n         { id: 1, country: \"Colombia\", city: \"Barranquilla\" },\n         { id: 2, country: \"USA\", city: \"San Francisco\" },\n         { id: 3, country: \"USA\", city: \"Austin\" },\n         { id: 4, country: \"England\", city: \"London\" },\n         { id: 5, country: \"Argentina\", city: \"Buenos Aires\" },\n         { id: 6, country: \"Spain\", city: \"Madrid\" },\n      ].filter((location) =&gt; location.id === req.query.id)\n    );\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">However, who else is going to know the parameter <strong>req<\/strong> which is an object containing a <strong>query <\/strong>property and is also an object containing our <strong>id<\/strong>?<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">We can help by setting our custom object while defining the parameters accepted in the function like the following:<\/p>\n\n\n\n<div class=\"wp-block-codemirror-blocks-code-block code-block\"><pre>\/* @description gets a list of location objects with cities from all over the world\n * \n * @param {Object} req Express Request \n * @param {Object} req.query Query Parameters\n * @param {number} req.query.id provide the id of the location to fetch\n * @param {Object} res Express Response\n * @param {Function} res.send Express function to send response in the body\n * \n * @returns {void}\n *\/\n function getLocations(req, res) {\n    res.send(\n       [\n          { id: 1, country: \"Colombia\", city: \"Barranquilla\" },\n          { id: 2, country: \"USA\", city: \"San Francisco\" },\n          { id: 3, country: \"USA\", city: \"Austin\" },\n          { id: 4, country: \"England\", city: \"London\" },\n          { id: 5, country: \"Argentina\", city: \"Buenos Aires\" },\n          { id: 6, country: \"Spain\", city: \"Madrid\" },\n       ].filter((location) =&gt; location.id === req.query.id)\n     );\n }<\/pre><\/div>\n\n\n\n<p class=\"wp-block-paragraph\">Look at how we are defining the <strong>req <\/strong>Object in our documentation. What is happening there is:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li><strong>Req<\/strong>: the <strong>req <\/strong>parameter is an object.<\/li><li><strong>Req.query<\/strong>: the <strong>req <\/strong>object contains a <strong>query <\/strong>property which is an object.<\/li><li><strong>Req.query.id<\/strong>: the <strong>query <\/strong>object contains an <strong>id <\/strong>property which is a number.<\/li><\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Other things to notice:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>The <strong>res <\/strong>parameter is also an object which contains a <strong>send<\/strong> function property.<\/li><li>The <strong>getLocations <\/strong>function doesn\u2019t return anything. Therefore, the<strong> @returns<\/strong> got updated with a void.<\/li><\/ul>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>NOTE<\/strong>: If you are using express, you could define <strong>Express.Request<\/strong> or <strong>Express.Response<\/strong> as valid data types for your <strong>req <\/strong>and <strong>res<\/strong> parameters.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Resources\"><\/span>Resources<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Interested in digging up more information about JSDocs? You can find helpful information in the following links:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li><a href=\"https:\/\/jsdoc.app\/\" target=\"_blank\" rel=\"noreferrer noopener\">https:\/\/jsdoc.app\/<\/a><\/li><li><a href=\"https:\/\/github.com\/jsdoc\/jsdoc\" target=\"_blank\" rel=\"noreferrer noopener\">https:\/\/github.com\/jsdoc\/jsdoc<\/a><\/li><li><a href=\"https:\/\/devhints.io\/jsdoc\" target=\"_blank\" rel=\"noreferrer noopener\">https:\/\/devhints.io\/jsdoc<\/a><\/li><\/ul>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Funny_Fact\"><\/span>Funny Fact<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Recently, one coworker sent me a message to Slack saying thanks.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">I was like: <em>You\u2019re welcome! But\u2026 What did I do? <\/em><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">He was going through some code I had written a while ago on one of the microservices I worked on probably about year ago.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">The reason he said thanks was because I had left plenty of comments throughout the code. It was the first time I had received a comment like that.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">However, programmers silently thank other programmers who previously worked on the same project for making it easy to read.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Going the little extra mile to write good comments almost instantly allows you to stand out among many programmers in this world.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\"><span class=\"ez-toc-section\" id=\"Conclusions\"><\/span>Conclusions<span class=\"ez-toc-section-end\"><\/span><\/h2>\n\n\n\n<ul class=\"wp-block-list\"><li>As professional programmers, we are on the mission of making easy the process of reading the code not just for ourselves, but for future generations of programmers.<\/li><li>It is a lifesaver. After two months, two weeks, or even two days you will forget what piece of code you wrote. Decreasing the time spent to understand the code is critical when the code needs modifications, especially whenever there is a production failure and there is not much time for guessing.<\/li><li>It removes any ambiguity caused by the flexibility of JavaScript. Never again will you have to guess whether an id parameter or property is a number or string.<\/li><li>It brings joy to programming in JavaScript without the need of using TypeScript, especially in projects that cannot be started in TypeScript as there is major development progress made on JavaScript.<\/li><\/ul>\n","protected":false},"excerpt":{"rendered":"<p>First and most importantly, I want to congratulate you. Wait, What? Yes, you heard it right. Congratulations! Writing proper documentation helps you get one step closer to writing clean code. If you don\u2019t believe me, you might want to read the book Clean Coder from \u201cUncle\u201d Bob. Trust me, it is an excellent investment in &#8230; <a title=\"The Ultimate Guide to JavaScript Documentation Using JSDocs\" class=\"read-more\" href=\"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/the-ultimate-guide-to-javascript-documentation-using-jsdocs\/\" aria-label=\"More on The Ultimate Guide to JavaScript Documentation Using JSDocs\">Read more<\/a><\/p>\n","protected":false},"author":1,"featured_media":611,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"nf_dc_page":"","_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[16,12],"tags":[],"class_list":["post-588","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-javascript","category-programmers-knowledge","generate-columns","tablet-grid-50","mobile-grid-100","grid-parent","grid-50"],"_links":{"self":[{"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/posts\/588","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/comments?post=588"}],"version-history":[{"count":5,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/posts\/588\/revisions"}],"predecessor-version":[{"id":2522,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/posts\/588\/revisions\/2522"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/media\/611"}],"wp:attachment":[{"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/media?parent=588"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/categories?post=588"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.becomebetterprogrammer.com\/staging\/4563\/wp-json\/wp\/v2\/tags?post=588"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}