Enhance your Coding with JSDoc

all right so today i'm going to be talking about jsdoc which is a great tool for encouraging developers to actually write good comments in their code but it also will help you with defining what variables are and as you're writing your code it gives you hints to what you're doing plus it can also dynamically automatically generate documentation for you for your functions for your modules for your applications so i have here a very fairly basic file i've got a few global variables defined at the top i've got a url i've got an array of values i've got a string which is a fake api key and i've got a global variable that i'm going to use later on in my code i've got a few functions here one for making a fetch call to an endpoint it's going to call another function which is actually going to take whatever endpoints passed in it's going to add the api key it's going to add the base url to it does the fetch call when it's successful it's going to call another function to build some html on the page my initial function here is going to add some event listeners or add an event listener to a button that's on the page it's going to then set this main in the global variable so that i can use it later on uh here's the add event listener function it just adds the click listener to that main element when somebody clicks on it it's going to call the function from above to get some data and keep in mind this is all just sort of mocked up code it doesn't really do anything there is no real api attached to it it's just something that's fairly standard that you would see this type of thing in a lot of applications here's the function for building that url taking my base url adding the endpoint putting the api key onto it returning a url object from this function then we have our build url function it's going to take the array of data that's passed in it's going to loop through that extracting a few properties from each one of those objects in the array of data that comes back and then i'm going to take three of those things saving them as this variable and i'm going to return that from this map method it's going to be saved as a products array the products array i'm then going to map through that and generate some html and i'm exporting my init function which starts the whole thing running okay so if you want a copy of this code there's a link down in the description to the code just with this code so you can play around with it what i want to do now is i have some comments already in here i've already got some jsdoc stuff set up but i'm going to add a few more things as we go along talking about this now in the website for js doc they've got fairly good documentation you know there's a getting started guide basically what you're doing is you are adding zoom in here a little bit we've got these tags everything starts with an at sign and you use these to define what the variables are what the functions are what the return values are what default values you have and things like that so it gives you a way to identify the different parts of your file as you're writing them vs code thankfully comes with support for jsdoc so if you are using their notation to comment your code it's going to add some extra features into your file automatically so let's take a look at that start of every file i'm defining a bunch of stuff you know who is the author what version of the file is this is there a general description this is actually a link to a tutorial that's going to be generated for us i'll come back and talk about this a little bit later but i've defined the fact that this is a module here's the path to this file so within my project it's just right at the root okay so here are the tags and depending on what it is there's different things that you pass in so for author do his name and an email address the email address gets the standard angle bracket tags around it version just is looking for a number when we come down to things like variables and i want to define this so it can be used later you can see right now with my cursor over top of the word base url it's giving the default value for what it is but then it's got at constant it's a string base url portion of the api url so it's giving me some information about that and that's stuff that i added into my code right here in this comment i said add constant i've defined what data type this variable is going to be this is the name of the variable so connects the two things together and then this is the description and this shows up when i hover over it now you may say well there's not much value because it's on the line right above it but anywhere in my code that i'm using base url so if i go down here and i find base url here it is i move my mouse over it there i've got the definition i know what it's supposed to be or what the value currently is of that thing and that's all thanks to my comments my tags that i'm adding as part of js doc so we've got one for base url here's one with colors now i've said set here this could be an array inside the curly braces we're defining what the data type is going to be so if it's an array or an object you can then specify what are the parts so this is an array of strings that i've got right here and i can say it's a series of enumerated values so enum lets us do that here's one which is basically just another string like the one base url so constant string api key so this is a string and here's the comment that's going to be seen later on when i mouse over that value okay here's another one where i haven't actually created a variable here typedef this is a type definition so i'm defining something called product anytime i use product as an object type down below when i say type product it's going to connect type product in my js docs up to this type definition for product and you can see i put my mouse over product there type product is an object that has three parameters id name and price and it's got the data types for each of those so later on in our code i have a little bit of a contrived example here but nonetheless we've got um right here yes um prod this variable i'm creating an object that has these three things inside of it now if i put my cursor over this it knows it's a type product and that's because i've added a comment in here to say that this thing is type product so i'm attaching this definition this type def that i put up at the top of my file to this so i automatically know what these things are supposed to be so prop property price is supposed to be a number property name is supposed to be a string and id is also supposed to be a number okay right here i'm defining a type i'm saying that products is going to be an array of things of type product so array is our general type dot and then this could be string number whatever i want but i want it to be an array of product objects all right back up to the top here that was our type def that we just talked about connecting type definitions with types and then what you should be doing for every function is providing some information about what a function does so here's my description and you know if that's the very least that you do is adding comments to say what a function does great that is an excellent first step but going beyond that once you've got descriptions of what the functions are you can start to do things like defining what these are so endpoint the parameter that's being passed into my function my comments now explain to me when i mouse over it it says that it's supposed to be a string and there's a little note saying it's the api api endpoint to be added to the base url for my api call okay fantastic so endpoint i know is a string so i'm passing in the string endpoint right here i know what it is it is a string and when i call build url it knows that build url is a function [Music] now it's saying right now build url accepts something called endpoint and it can be any data type and then it's going to return a url okay that bit right there that one line that is actually being built by vs code it's trying to make its best guess as to what's going on so it knows the return value for the function it knows it's a url object but it doesn't know what endpoint in that function is so let's go down to this build url function take a look right here build url it does not know what it is so right now vs code is saying it can be anything i don't know what it's supposed to be well for js docs i'm going to actually come in here and say what it's going to be now all i did was forward slash two asterisks and then it automatically threw in the slash i'll go back like this when i hit enter i'll have to back up a little bit when i hit the enter key vs code is actually looking to see how many parameters are being passed in and it knows there's one and it's called endpoint so it wrote this for me and inside of here i can say it's supposed to be a string i can now add a comment [Music] something like that returns okay vs code was guessing it saw this and figured okay well it's a url that's being returned i can do the same thing here i can say that it is returning a url you know we could if there's other things that are similar we can find them in this list but url that is actually the thing that we want so there it is my function definition now says returning url and it's only accepting a string so we go back up to the top here where we had it where we were calling build url and now it knows the endpoint being passed in needs to be a string all right colors right here here's something that i've defined up above as a constant well it knows that it isn't a colors is an array of strings and there's my note list of possible color values to be used so there it is i have it in my documentation through js docs so just mousing over it vs code is able to say what this thing is supposed to be or what it is provide me extra information my ad event listeners i've got a description for the function param the main this thing right here this main argument being passed in the data type is html element so i know what's supposed to be passed in now if i import this file into another one i'm going to be able to tell through js talks and via js docs and vs code that this thing that's being passed in needs to be an html element html we talked about that one already i think the only other one that doesn't have a comment is just the init so same idea start the comment the double comment two stars hit enter and it's going to fill in how many parameters button what's that supposed to be well it's going to be an html element and so is main these are both html elements that are being passed in and we can add a note saying the button to be clicked and the html area where content is added [Music] okay so there's js docs now there's lots and lots of these tags that you can learn over time start off with description [Music] version author param constant returns just those basic things start off with those get into the habit of using those in your code then once you've got them so we know vs code is going to do a lot for us with just those basic comments that's fantastic this is gs code a node module that we can actually install on our computer so we can install this globally and then have access to the functionality that lets us generate documentation so that's our next step inside vs code in my terminal we'll do an npm install dash g so it's a global install and then js dock that's the thing that we want to install i already have it i can do it again it's not going to hurt anything i install this now i have the functionality on my computer that if i open this up you can see this is where i am right now app.js i can run jsdoc and then say hey the file or the folder that i want to do this is the one app.js when i hit enter and run this you can see here it created this folder called out and inside of there it generated all these things all these files based on the fact that i had at module here based on the fact that i gave this file name it read through here knew what was being imported if there were anything that was being imported and it generated these html files now i've already got this up and running in my browser here it is if i refresh there we go so modules here's my app.js one and we've got api key base url colors these are the things that i declared globally methods these are my functions from my page and it knows what's being passed in it knows the data type of those things there's a description it tells me where in the file it came from so we have all of these things built in and there's a type definition for product exactly what is a product just another way of getting around here so depending on what you have this navigation this is completely generated by jsdoc for us so we've got all these pages so we can once we have our file tell jsdocs that we want to generate these tutorials so we've got a js docs command app.js that will generate this and you can delete this as many times as you want i came in here and i were to delete this not a problem it will just create it again every time we run this and inside of here if i want to add these tutorials there's just the one flag that we add app.js dash u and then we say where we want to place it which folder do we want it to look for [Music] our tutorials there could be multiple files inside of here we're going to go inside of slash tutorials this is the folder we want to go in something that's not happy about here no such file folder oh yes i should put a period in front of this to say starting from the current location there we go so i'll do this there we go starting from the current location go into the tutorials folder find any files and we've got tutorial overview here and it has generated this file so it's going to be called tutorialoverview.html which back here this is the name that we gave so it'll be tutorial hyphen this name dot html and that's going to be here oh i closed the server here we'll go live again but i'll do it with this file there we are so here is the markdown generator tutorial that we have that's the tutorial section in our modules there we have all of our functions with all the parameters all right so that should be enough for you to get started with js docs so vs code's got the built-in support as we write these things js docs i encourage you to go through and just play around with some of these any of these are you're not sure not sure how they work you can just click on them and they've got examples little description of how they work so it's all here in the documentation when you want to generate your documentation just install and it is just the npm install command install it globally js talk and then that is the command jsdoc run that command with the name of the script or scripts that you want to generate just like here so js doc and there's the name of your javascript phone okay so good luck with that have fun and as always thanks for watching

Channel: Steve Griffith - Prof3ssorSt3v3

Views: 2,219

Keywords: MAD9013, MAD9014, MAD9022, web development, JavaScript, JS, HTML, steve flix, steveflix, web dev, professor Steve, prof3ssorSt3v3, 100daysofcode, MAD9135, comments, documentation, best practices, markdown, jsdoc, jsdocs, js doc, jsdoc tutorial, how to use jsdoc, convert comments to documentation, convert markdown to html, convert md to html

Id: 3RIaH0NnG64

Length: 19min 36sec (1176 seconds)

Published: Tue Sep 14 2021