How to use JSDoc - Basics & Introduction

hey guys hey going so in today's video I'll be giving you an introduction to J stock and basically just showing you how to use it so if you're not too sure what J stock is essentially it provides you with a way to document your JavaScript code and it can also be exported to HTML but you don't need to do that that's completely an optional step but it also integrates really well with text editors and ideas such as visual studio code and after watching this video if you want more information on J stock definitely check out J stock app for some further documentation but anyway let's just dive right into how to actually use J s doc so let's go inside the text editor right here I've got this main J's file Sonia let's actually create a function in which will be documenting using jeaious doc so let's make a new function here and call this function creates a person as the name implies this function is going to be creating a person so it's gonna be accepting a name an age and also another parameter called is developer basically just a boolean to say is this person a developer this function is going to be returning an object with three properties of course it's going to be named as being named 8 as being age and is developer as being his developer so are quite a straightforward function okay and obviously by looking at this function you may notice that or you might assume that the name parameter is gonna be off type string the age is gonna be a number and is developer is gonna be a boolean and that is obviously quite acceptable to assume given the simple nature of this function however if you have larger functions then it can be hard to determine or figure out what it actually does and what these parameters types are and also what the function returns so that is what J stock is for I definitely recommend you still document your simple functions however it definitely comes in handy more with larger functions so let's go up here now before this function and document it using jaeseok so in most text editors or Lys with an extension installed forge a stock you can simply put forward slash and put two asterisks like this as you can see here that is a snippet for a J's comment in Visual Studio code if I press ENTER it's gonna generate for me the J's dock comment for now let's just not worry about this parameters part but I do want to say that if that didn't work for you try installing a J stock extension or if that didn't work it is quite straightforward to simply just write out this syntax right here you simply put the forth / - asterisk then on a new line you put a space and an asterisk so once you have this this sort of syntax ready for your comment and to describe the function create person we're going to be doing it up here so we're gonna say for example this function will accept details about a person and create an object for them so that what there is gonna be you a function description again for this simple function this is quite useless but of course larger functions it's gonna be a lot more helpful so that is where you put your function description when it comes to jeaious dock so now that's quite straightforward moving on to the parameters here this right here line 5 this is how to specify a type name and description for a parameter so in this case right here it is dubbed the name name and it's put it right here so essentially you say ax / M and then inside here within curly braces you put the type of the parameter then followed by the actual name inside here so for the parameter type we're gonna say in this case that's going to be a string so we simply put strings right there previously when it was an asterisk this right here basically just means that the parameter could be anything of course by putting string it means that the parameter is supposed to be a string okay we can also go inside here and put after this and we can describe the parameter for example we can say the person's full okay and we can do the same thing down here we're gonna say number four age and we can say the person's age and what is developer we're gonna obviously does parse in here boolean and we're gonna say whether or not the person is a developer okay and that is basically how to specify your types and the descriptions for your parameters so now if you're good if you could so if you go down here now and you actually found use your function for example we can say create a person we can see on the right there Visual Studio code has picked up the dress doc and it is telling us right here that the descriptions of the parameters and it's also telling us the function description and it's also telling us the types of the parameters which have been specified up here we can say name as being string age number and is developer as being boolean so obviously we can see how we can take advantage of J of stock in order to you know see what the types are when we are working on the jeaious code okay anyway let's go down here now and we're gonna also go inside the function and we're gonna try and write out a name as we can see here again on the right side we can see it knows it's a string which means if I say dot we get all of the methods forward the string and this is just the feature obvious code because it knows how to read J of stock and we can see once again how it can be useful in the functions okay let's move on now to another another annotation and that is going to be for the return type so down here we're gonna say absolute returns and we can I say very similar syntax we're gonna say in curly braces we're gonna say objects just like this and we're gonna say as a description D person objects so once again quite straightforward it's gonna be your type inside here followed by a description also if you don't want to use this style for descriptions you can also put a dash and that is perfectly fine okay so now we have this well-documented function let's export this to HTML so obviously you don't need to export to HTML to take advantage of a stock however in may it may be something to know so anyway let's go inside here and open the terminal and we're gonna be installing jeaious duck on my system so in order to do this using NPM you simply say npm install and then j of stock but i am gonna be supplying here the - g global flag so if you're starting to use j stock and what you're just testing our globe was perfectly fine but you may want to instead install locally in your project anyway by pressing enter here it's gonna install j stock on your system and then you may need to restart your terminal or your text editor for the next step but to export this to HTML you simply say drag stock and then provide the name of your file in this case main dot J is pressing enter here is gonna generate an HTML document inside the outer directory right here and a false to go to that file inside the text editor so full of such out we can see right here we get a nicely formatted HTML file that describes the documentation which we dress wrote if I was to go on the right here we can press on create person under the global heading because of course this function right here is global ok so under this heading right here create person we can see right there we get all the documentation which we just wrote in a nice and formatted manner ok we get the function description that parameter list description etc the source and the return table so definitely useful for reference and if you want to you know maintain a larger code base but anyway let's go back inside here now and explore just a couple more features of JS Dokken so pass something which may be useful to you so let's go down here now and create a new class person and this class right here is gonna simply take in the same parameters for a constructor you can say constructor and take in these parameters right here I'm gonna copy the JSE doc from above so all of this stuff right here and paste it just down here okay and I'm gonna be changing just the description to be creates a person okay and inside here I'm gonna say this dot name equal to name at least eight people to age and this stock is developed by equal to is developed so the reason why I made a class is because I'm gonna be showing you how classes work they work in a very similar fashion in Drey stock and when it comes to the types so this means that it falls to make a new function down here now called print details about a person okay we can say person just like this one we can say in the jeaious doc we can say per ampere s'en we can say this right here is going to be accepting a type of person with the capital P to refer to this person right here the class okay which means that I'll just say up here outputs details about person okay inside here we can say console dot log and I can say for example I'm not just copy and paste this bit right here okay so I can say console lot and I can say person dot name age is developed cetera is this particular you know years old okay but I also want to show you here that now if I say person dot we get all of the properties of the person right here because the jeaious dog has obviously described that this is a person so it knows to display these particular parameters so definitely once again just showing how useful it's gonna be in your code okay Aston anyway let's just go down here now and rerun the J's locked at main jeaious and see the output so now in the brow refresh and we get here classes are new heading inside here we get the person the same sort of thing and also down here of course print details very similar thing also in the top section you press on this and it goes to the actual person so definitely really interesting and useful right there but I also do wanna show you one more thing and that it's gonna be for arrays so let's go back inside here and make a new function once again and this function is going to be called gift numbers and basically this function is gonna be returning a bunch of numbers so we can say return and then 1081 30 and 150 so now of course we are returning an array of numbers so you may have guessed that already with J stock you can specify the return type and you can say an array of a particular type so let's just say right here gives you numbers as the description and inside the parameter a / M I'm gonna stay right here so you're not mistake it needs to be at return so add returns we're gonna say inside here curly braces and we're gonna say number and then use square brackets just like that and basically it's just saying this function is going to return you an array of number so now if I was to say down here Const numbers is equal to get numbers just like this and now if I was to say for you know const end of numbers we can see here if I give console dot log n we can see right there B's code knows it is a number we can see number right there I say dot once again all of the methods related to only a number so once again that is how useful it's gonna be in your code especially like the array one because typically if you just say returns array you won't know the type of the array typically your arrays of a single type I might just save this here and once the game on dress talking one last time and this is the result inside the browser we can see right here we get an array of number as be returned and that is an introduction to J stock and of course how to use it thanks for watching guys and I'll see you later

Channel: dcode

Views: 20,209

Keywords: code, coding, programming, tutorial, introduction, beginner, walkthrough, guide, software, development, simple, easy, english, with, example, examples, developer, lecture, recording, how, to, web, website, app, application, javascript, js, doc, documenting, comments, es6, ecmascript, jsdoc, paramater, function, annotate, annotations, data, type, string, number, boolean, object

Id: Nqv6UkTROak

Length: 13min 4sec (784 seconds)

Published: Thu Jan 16 2020