Documenting Your JavaScript | JSDoc Crash Course

[Music] this video is sponsored by lenôtre what technology stack you build on the node makes it easy for both beginners and power users to host apps sites and projects in the cloud to get $20 towards your new account visit Llano comm / travis e hey what's going on guys in this video we're gonna look at Jas dock which is something I've been experimenting with lately that I really like it is a JavaScript documentation generator so basically you can add these inline j/s doc comments right into your source code and you can use Jas doc to scan through and create an entire documentation website for your code and you document just variables classes functions modules whatever function parameters their types you can add descriptions you can even add tutorials and stuff like that so it's really cool and you can also use it for type checking so I'm going to show you how we can do that similar to how you would use typescript only you don't need to compile it like typescript and you can also use it with typescript which I'm not going to get into but you can do that as well and this is the documentation j/s dot app and there's a lot of good information here you can see all the different tags I'm not going to go over all of these because this is a crash course but you can look more into it on this website here so let's jump into vs code and we can install J a stock with NPM and you can use it on the backend with node Express you can also use it on the front end you can use it with react or view or whatever you want to use it with to document your code alright so let's go ahead and NPM in it - why just to create a package Jason I'm gonna try to go kind of fast because I don't want the video to be too too long so let's NPM install as a dev dependency J s doc okay so that should get added to our package dot JSON file now jaya stock needs a config file actually you don't need to create it it will use defaults if you don't but we're gonna go ahead and create J s dot Jason and I'm gonna just just grab this real quick I'm gonna paste this in so I don't have to type it all out and just go over it so basically source is is where J s stock is gonna look and we're gonna have a folder called source you can have an array here of different folders if you want but we're gonna have one source folder we're gonna include anything that ends with dot J s and we're gonna exclude any node modules or Docs folders because Docs is what I used as the destination when it when it goes through and creates the documentation website it'll be put in this Doc's folder if you don't have this it'll just create a folder I believe called opt opt and then plugins so this plot will allow you allow you to use markdown this mono space clever links this is just going to make it so that when you have links within your documentation it'll have a mono space font and then recurse will allow us to basically recurse into subfolders okay so it'll look below just the root level so let's save this and then what we want to do is go to our package dot jason and create a script to run this you can also install it oops you can install it globally if you want but we're gonna just we're gonna do it local and just add a script so let's say J s doc and then we want to do the config file which is j j s dark jason okay so it always look at this config file for whatever settings we have alright and then let's create our source folder okay so this is where your actual code goes and we'll just have an index dot JSON i'm gonna run npm run doc all right so as you can see over here I created a folder called Docs and this is our documentation website it was just generated for us and we have no code right now but it still will generate and if we take take a look at the index.html it'll look like this by default and this is the default template there's a couple other templates you can use you can create your own templates if you want to change something like this home right here I'm going to show you how we can edit the default template without actually changing it in the node modules folder but we'll get to that in a little bit so let's go ahead and just add something to our index j/s so I mean I'm just gonna add a variable for now so it's a student name and let's set that to John Doe basically I want to add this to my documentation and I want to also add a type I want to use type checking to add a j/s doc comment envious code we can just do slash and then two asterisks and it will automatically finish for us and then we can hit enter and then add whatever j/s doc tags we want in this case we want to add a type and this is gonna be a string type we can also add a description here so we can say like student name which is pretty obvious and that's it so I'm gonna save this and go down here and generate our Doc's and then visit the website here and now you'll see we have global because we're in the global scope and then we have our student name variable or member and it gives us the name of it the description that we put the type which is string and then the source which is the file and the line number and I can actually click on the line and it will show me in my documentation that line highlighted okay so pretty cool and if we want this if we want to have actual type checking which I do have enabled you'll see if I change this to a one I'm gonna get this red squiggly line that says type 1 is not assignable to string so it works kind of like typescript now by default this isn't going to work what I what I've done is in my set if I go to my settings JSON file right here this is the this is what's allowing that to happen so JavaScript thought implicit project config guess is true if I set that to false or I don't have this at all then it's not going to do that so I couldn't show me that red line or anything all right it'll also show me in the property down I'll actually no it doesn't does it set that back to true yeah so now you'll see down here type 1 is not assignable to string all right now if you don't want to add that global setting what you can do is in your file you can add inside of a comment ts check like that and that will do the same thing without needing that setting all right so that's a string let's change it back to John Doe and you can do numbers boolean basically all the JavaScript types you can also do a raise in objects so I just want to show you that real quick let's say we have an array of grades so 98 seven point seven decimals are numbers in JavaScript 76 and 89 if I want this to be an array we can go ahead and add a type not a type def we'll get into that after so type is gonna be array okay and for the description we'll say an array of grades okay now if I put in let's say a boolean here that's fine right now because I'm just saying it's type array but if we want it to be an array of numbers we can add some angle brackets and say number and now you can see I get an error that says type true is not assignable to number okay so if you know it's gonna be an array of numbers or strings or whatever you can put that in here now let's say we wanted an object like to do with an ID and a text value which is a string okay so if we want to do that in jaya stock we can add type and inside double curly braces we can say this has to have an ID that's a number and it has to have a text value that is a strength if I add something else in here I'm gonna get an error because it doesn't adhere to basically the model which is an ID and text just like you can do in typescript and then if I change let's see I'll change this to a string I'm gonna get an error because this is supposed to be a number now you can also have multiple types let's say this ID it can be a number or a string we can simply put a pipe character in here and put string and now it can be either so let's see let's save that and generate the documentation and now you can see we have our student named art to do gives us the type the description and the line number I actually didn't add a description here we'll just say to do object all right now before we move on to functions and params and stuff like that I want to show you how we can edit the template if we want so if we go into node modules and then J stock and then templates you'll see the default template that's used by default and we can describe what template we want to use from within our config but what I want to do is edit the default template and you never want to edit something in your node modules folder almost never so what we can do is just copy this folder this default and we can put it right in our route and let's just rename it to custom - template okay and then we can go to our config rjs doc dot jason and we can add in our opps right here we can add template and set it to custom template it's in the same directory so that's fine and now let's go into custom template and publish j/s and do a search for home and let's say we want to change this to what do we want to change is to just say Jas dark example but this home right here will also change to j a stock example or whatever you want and then i'll save and then let's regenerate our documentation and if we go back if we go right here j a stock example j a stock example okay and if you want to get rid of this there's different there's basically partials if you look in right here this TMP l there's all these TMP l files where you can you can edit those as well but you never want to edit the actual template in the node modules folder alright so let's see what else do you want to do let's move on to functions and params so let's say we have a function i'm actually gonna just just grab this real quick alright so it's just a very simple function to calculate tax and you can use an arrow function or you know regular function it doesn't matter it'll still document it the same way so it takes in an amount like 100 and then a percentage like 50 actually lets to like point ten point one and we'll save this and just run the file so we can say node source slash index or since it's called index we can just do node source and we get a hundred and ten dollars now i want to document this so let's actually just get rid of the console.log so we'll put in a slash and then two asterisks and enter and notice that it actually looks at the params and creates the params with the name of the variables here and then we just want to change the type to number all right we'll give the function description will just say calculate tax but also you could put any function you want this is just something quick I just put in and then we can put a description for each parameter so we'll just say total amounts and this is the tax percentage okay and then with functions we can do a return or returns turns if it doesn't have a return value you can do void but this actually returns a string and it returns the total with a dollar sign okay so yeah because I'm returning a temple literal here with backticks and I have a dollar sign in front of the amount let's save that and let's run a documentation I'm sorry that's not right we want to run npm run dock and if we take a look now over here you'll see calculate tax now these are all our members basically our global variables and then we have methods okay so any methods we create will be put here we have calculate tax which returns a string we have the description and then it gives us this cool little table for parameters so the name the type and the description and then of course we can locate that function in our source code so this is great for someone that you know just I mean if you're working with someone else's code this really helps see what everything is what it does so I mean it can be really helpful when you're collaborating with other people so next thing I want to show you is how to create custom types something called a type def or a type definition so let's say we want to create a type called student so let's go down here and let's say inside our J a stock we'll say a student I'll just say yeah that's the student that's fine and then we want to use at type def okay so we're defining a type which is gonna be an object of and it's gonna be called student okay and then the student is gonna have certain properties so we'll say property give this property a type of number and we'll call this ID give it a description and we'll say students ID all right we'll just copy this down a couple times so this next one here is gonna be the name so say name and that's gonna be oops I did that wrong this should be string and this should be name student name let's do the age of the student so this will be and for this one I'll do a string or a number either one will be fine and I also want to make it optional if you want an optional value here you can put brackets around it okay so we'll say student age which is optional and then let's say let's do a boolean because we haven't done a boolean yet so we'll say boolean and we'll call this one is active so student is active and then down here let's go ahead and use it so we're gonna put in another j/s doc comment and we're gonna put in our type okay just like we did for our variables above except now instead of string or number or something like that we're gonna put in our student type all right and then let's say Const students and I'll say ID 1 oops ID 1 let's say name John Doe what else age 20 and is active true ok and everything is fine here now if I were to change let's see is active to a 1 we're gonna get an error because it's supposed to be a number I'm sorry it's supposed to be a boolean but it is a number if I get rid of his active we're gonna get an error because is active is not optional however if I get rid of age since we put brackets around it we're not gonna get warning ok and again it's up to you if you want to use it for type checking or not and you know if you want to enable that that functionality but let's go ahead and generate our Docs and let's take a look over here and we have student okay we also have student name so student name is the member right here and if we look at the type well I guess oh wait no it's not student name student that's right here a student and it has the type of student okay see that and then if we go down actually wait a minute all right it's right in front of my eyes type definition so we have a student type ultimately it's an object but our properties here ID number and you can have attributes as well so ID name age which is optional is active and then if we want to locate that type def it'll take us to that in our documentation so now what I want to do is give you an example of a class okay cuz up to this point we've been just kind of working in the like the global scope so let's create a class and we'll call this person just something very simple and we want to give this basically just a description so we'll say class to create a person object and then let's have a constructor and I mean I'm not going to explain what a class is or construct or anything like that this is geared towards people people that already know that if you don't I would suggest watching either my JavaScript crash course on YouTube or my modern JavaScript from the beginning on you to me so constructor let's say it takes in an object called person info so we can put here a per am tag so if we put our j/s doc here we can say per am object person info we can put a description here if we want like in for information about the person and in our constructor let's take say this dot name will create a name property and set it to that person info name and then let's take this dot age and set that to the person info dot age okay and then we can adhere our jeaious doc and we can add a property so let's say property because it's a property of a class it's a string of name they'll say person's name alright we could do the same thing for age so person's age age okay so that's our constructor and then let's just create we'll just create a method here and let's call this greet and we're just gonna do a console log here of a template string and let's say hello my name is and we can say this dot name and I am this dot age so I kind of a silly example but it's just to kind of show you how to use jeaious dock so above greets so above any method we can go ahead and put in here a property and this is a function called greet say a greeting with the name and age and then we can put a returns okay so this is going to return void because it's just a console log so it's not going to return anything okay so let's see well go ahead and save that and let's run our dock and you can see it actually created a new file called person HTML so any class you create it will create that file and if we check it out notice that now in addition to just our global scope we have classes and if we click on person this gives us all the information about our person class gives us the description so the constructor the parameters for the constructor which is the person info which is an object we have the members which is an age named methods we only have one method called greet and we can go to it here if we want and I just want to show you real quick link so let's say we have let's just it initialize a person here so we'll say we'll call this person one said it's a new person okay so we're just using our person class and remember it takes in an object with a name and an age and then I don't know just to a console log here of person one dots greet and we'll just run the file see if that works so node source we get hello my name is John Doe and I am 30 not sure what the undefined is actually I don't know but that's fine it doesn't really matter what I want to show you here is we can actually link to stuff so we can say like C let's say person person one but I just want to show you we can do C and then we can use link like this link and then we want to link to the person class because this variable is related to that person class so if I go ahead and generate our Doc's and now we take a look over here you'll see person 1 and right here person 1 the description and C person so if I click on that it'll actually take me to the class so you can link to other parts of the documentation you know from certain parts which is pretty cool alright I'll probably just get rid of that so I want to do that so let's do modules so a lot of times you might have separate modules and this works with both common j/s which is you know when you're working in nodejs and you use the require syntax or es2015 modules when you use import/export you know if you're in react or view or wherever you want to use es2015 modules so i'm gonna create a new file here called in my source folder called calculator dot j/s and it's just going to be a bunch of methods so I'm going to let's say yeah I'm just gonna paste this in just give me a second all right so I'm gonna paste this in and just go over it so when we create another file basically that we're gonna bring in it's a module and we can just define it with the module tag here calculator give it a description and then I just have a you know add multiply subtract and divide just as separate functions I'm using shorthand arrow functions syntax and I just have just like I showed you before just the params and then the return okay so nothing new here it's just all in a module and we just called it calculator so let's save this and let's go to index J s and bring this in up top so I'm I'm using node so I'm gonna use the common J's syntax so we'll say Const and then we'll just bring in we'll use D structuring to bring in all the methods from calculator or actually I'm sorry we need to do dot slash calculator okay so we can bring in you know add subtract divide and multiply and then if we want to use it we can go down here and we'll just say I don't know console.log and we can take add we'll add 20 and 50 and notice that it gives me that checking okay so it tells me that it needs two arguments so say 20 and 30 and I'll just run this node source and we get 50 okay now let's generate our documentation and take a look let's just reload this actually let's go to okay so over here now you'll see we have modules so for every module you create whether it's es2015 or common j/s it'll show that the module here and if I click on it we get all the information about that module so the description the source all the methods along with their parameters okay so you can see you know number and one and two first number second number and it just basically documents that module okay just like a documents a class and then any global entities that we have here so it's pretty cool I really like this I think it's it is very verbose I mean you know having to put all these comments and but it makes things clearer even just in the code you know so you know what's what so I mean there's pros and cons to it my job isn't to try to convince you to use it it's to just show it to you and then you take it upon yourself if you want to use it or not all right so let's see what else do I want to show you guys let's do let's look at tutorials because you can actually add tutorials to your documentation so what we can do is go to our Jaso Jason and from here we can add tutorials and then we can have a folder where we want to display our tutorials which is gonna be tutorials alright actually let's do dot slash I should probably do that yeah so inside our root here we're gonna create a folder called tutorials now tutorials can be either HTML or markdown I believe they can be XML there's a there's a couple different formats you can use but I'm gonna create a new file here and I'm gonna call it program - tutorial dot HTML and then it'll just generate an HTML file and let's say program tutorial and we'll just put a paragraph here with a bunch of dummy text alright so I'll save that let's create one more so this one let's say calculator tutorial and this would let's just make this one markdown just to show you so I'll do dot MD and then I'll just put in I'm just gonna paste in a bunch of text here as well and obviously you can use you know all kinds of markdown so we have two tutorials now I'm gonna go ahead and generate my Docs and let's take a look and how we have tutorials we have our calculator tutorial our program tutorial now this doesn't look too good this title here it's basically just it's going to use the name of the file by default but what we can do is inside of the tutorials folder we can create a file called tutorials dot jason and in here let's go ahead and open up some curly braces and we can put program basically the name of the file tutorial and set that to an object and then we can have title program title calculator tutorial and set that to have title tutorial alright so save that and to generate the doc again and check it out and look at that program title calculator wait wait I put program title should be program tutorial or whatever you want it doesn't really matter just showing you how to do it alright so that's pretty cool now let's say in our calculator j/s we actually want to point to that tutorial so we can go ahead and in the description here let's uh oops the hell I just do let's go up to the description here and let's add C and we can actually open up some curly braces and we can put at tutorial and then we can point to the calculator - tutorial and now I'm gonna generate the docs go back and now if I go and I look at my calculator module you can see right here see calculators tutorial and it will point me to that tutorial alright so obviously you know this is just a mess of code it's not it's not an actual program or anything but you can really structure this to make a lot of sense and really help you know other people out as well as yourself a lot of times we write code we don't look at it for a few months and then we go back and we're like what the hell does this even do you know so this will document everything for you which is really cool in addition to that it'll give you some type checking functionality all right so I think we're just about done here let's go back to the home now for this area here there's a few things we can do we can actually add in let's go back to index j s and i'll have this code in the description I'm not sure what I'm gonna put it in it might be a github repo or it might be like a plunker or something but here let's add C we'll go right here and we can actually put in some J s stock and we can use at file and this so there's so many of these tags that I'm not gonna go over that you can check out in the documentation but let's just say index J s is the root file for this example app and we can actually put other things like author we can put if we want maybe we want to point to an external website we could do C and we can put a link in here like this just put my website here alright so maybe you have a you know a website you want to put in here stuff like that and if I save this and then run it take a look now we have this here it gives you it'll have the file name and then the description author source and the website alright and another thing we can do is we can actually add a readme here if we want to so and you can directly edit the template as well as long as it's not the actual template in the node modules folder but let's say we have we create a readme file you don't have to do all this stuff I'm just kind of showing you guys that you you know some of your options that you have so we'll just say this is just a sample script how to use J s doc okay so we'll save this and then what we can do is go to our config file and in this config file we can add a readme obviously your readme would probably have a lot more than that but just to give you an example and then we're just going to point to that file so readme dots MD okay so let's run this and take a look and there it is so this comes from our readme file so we've built this documentation for just a nonsense program but you can see all of all the different things that you can do with it and there's a lot more I'm just getting into kind of the fundamentals of j/s doc now if you're really interested in jeaious doc and you want to start using it what I would do is I'm actually going to assign you some homework so take something you've already built some kind of JavaScript program it could be something tiny it could have been a tutorial that you followed on my channel or someone else's it could be a large project and implement jeaious talk into it install it set up the config file and add your j/s doc comments where neat where you want and create some documentation because as I said in my last video about tutorial hell just following along isn't enough you need to dive in and do stuff on your own so I think that's a nice little homework assignment is to take something you've already built and just implement J has docked comments and generate some documentation alright guys that's it hopefully you enjoyed this if you did please leave a thumbs up and I'll see you next time

Channel: Traversy Media

Views: 81,648

Keywords: jsdoc, javascript documentation, type checking, javascript types, typescript

Id: YK-GurROGIg

Length: 36min 31sec (2191 seconds)

Published: Mon Nov 18 2019