Documenting Your JavaScript | JSDoc Crash Course

Summary

This video tutorial explores JSDoc, a JavaScript documentation generator that simplifies creating a documentation website for code. It demonstrates how to install JSDoc, configure it, and utilize inline comments for variables, functions, and classes to generate documentation with type checking. The host also covers custom types, linking documentation, and tutorials integration, showcasing the tool's ability to enhance code clarity and collaboration.

Takeaways

• 😀 The video introduces JSDoc, a JavaScript documentation generator that creates a documentation website from inline JSDoc comments in the source code.
• 🛠️ JSDoc is versatile, suitable for both beginners and power users, and can be used with various frameworks like Node, Express, React, or Vue.
• 📝 It allows for the documentation of variables, classes, functions, modules, and more, including their types and descriptions.
• 🔍 JSDoc supports type checking similar to TypeScript, but without the need for compilation, and can be used alongside TypeScript.
• 📚 The documentation website created by JSDoc includes detailed information about function parameters, return types, and source code locations.
• 🔧 A configuration file (`jsdoc.json`) is used to customize JSDoc's behavior, such as specifying source files and excluding directories.
• 📖 The script demonstrates how to install JSDoc using npm as a dev dependency and set up a basic configuration file for documentation generation.
• 🎨 Customization of the documentation template is possible, either by editing the default template or creating a custom template without modifying the `node_modules` folder.
• 🔗 JSDoc supports creating links within the documentation to other parts of the code, aiding in navigating complex projects.
• 📝 The script covers how to document functions and parameters, create custom types with typedef, and document classes and their methods.
• 📑 The video also explains how to include tutorials, readme files, and other additional documentation to enhance the understanding of the codebase.

Q & A

What is the purpose of JSDoc mentioned in the video?

JSDoc is a JavaScript documentation generator that allows developers to add inline JSDoc comments to their source code, which can then be used to create a comprehensive documentation website for the code.

How does JSDoc help with type checking?

JSDoc can be used for type checking by adding type annotations in the comments. This helps in identifying type mismatches during development, similar to TypeScript, without the need for compilation.

What are the benefits of using JSDoc over TypeScript?

JSDoc provides the benefits of type checking and documentation generation without the need for compiling the code, as is required with TypeScript.

Can JSDoc be used with TypeScript?

Yes, JSDoc can be used with TypeScript, although the video does not go into detail about how to integrate the two.

What is the recommended way to install JSDoc in a project?

JSDoc can be installed as a dev dependency using npm with the command 'npm install jsdoc --save-dev'.

Why is a configuration file needed for JSDoc?

A configuration file tells JSDoc where to look for source code, which files to include or exclude, and other settings like the use of plugins and whether to recurse into subfolders.

How can JSDoc be integrated with Visual Studio Code?

The video does not explicitly mention integration with Visual Studio Code, but typically, one would use the installed JSDoc package and configure it through a 'jsdoc.json' file to work with the editor.

What are some of the tags that can be used in JSDoc comments?

Some of the tags used in JSDoc comments include @param for function parameters, @returns or @return for the return value of a function, and custom tags for additional documentation like tutorials or examples.

How can JSDoc comments be customized for a project?

JSDoc comments can be customized by using specific tags that describe the code, such as @param for parameters, @returns for return values, and by adding descriptions and type information.

What is the process for generating documentation with JSDoc?

To generate documentation with JSDoc, one must first write JSDoc comments in the source code, create a 'jsdoc.json' configuration file, set up a script in 'package.json' to run JSDoc, and then execute the script using npm run jsdoc.

How can JSDoc be used to document a class in JavaScript?

JSDoc can document a class by using the appropriate JSDoc comments above the class declaration. This includes a class description, constructor parameters, and properties and methods with their respective types and descriptions.

Can JSDoc generate documentation for modules?

Yes, JSDoc can generate documentation for both CommonJS and ES2015 modules by using the @module tag and documenting the functions or variables exported from the module.

What additional features can be added to JSDoc documentation using tutorials?

Tutorials can be added to JSDoc documentation to provide more in-depth explanations or guides on how to use the documented code. These can be written in HTML, Markdown, or other supported formats.

How can the appearance of the generated documentation be customized?

The appearance of the generated documentation can be customized by editing the template files. It's recommended to copy the default template from the 'node_modules' folder to the project directory and make changes there instead of editing the original files directly.

What are some of the benefits of using JSDoc for a project?

JSDoc provides benefits such as improved code readability, easier maintenance, better collaboration among developers, and the ability to perform type checking during development.

Outlines

00:00

📚 Introduction to JSDoc

The video introduces JSDoc, a JavaScript documentation generator that allows developers to embed documentation comments within their source code. It highlights the tool's capabilities, such as creating a documentation website, supporting type checking, and being compatible with various JavaScript environments including Node.js, React, and Vue. The tutorial also briefly mentions the documentation's potential for enhancing code readability and collaboration.

05:04

🛠 Setting Up JSDoc

This section walks through the initial setup of JSDoc, including installing it as a dev dependency using npm and creating a configuration file. The importance of the source folder, file inclusion and exclusion, and the use of plugins for markdown support and linking are discussed. It also demonstrates how to create a script in the package.json file to run JSDoc and generate documentation.

10:05

🔍 Exploring JSDoc Features

The video explores various features of JSDoc, such as documenting variables, types, function parameters, and descriptions. It shows how to use inline JSDoc comments to annotate code and generate documentation dynamically. The tutorial also touches on the ability to perform type checking similar to TypeScript without compilation and how to customize documentation templates.

15:08

🎨 Customizing Documentation Templates

The presenter explains how to customize JSDoc templates by copying the default template and modifying it to create a unique look for the documentation website. It emphasizes the importance of not editing the original template files within the node_modules folder and demonstrates how to point JSDoc to the custom template using the configuration file.

20:10

🔢 Documenting Data Types and Objects

This part of the video focuses on documenting different data types such as strings, numbers, booleans, and objects using JSDoc. It shows how to define custom types with type definitions and how to enforce type checking within the code editor for better code quality and maintenance.

25:11

📘 Documenting Functions and Parameters

The tutorial moves on to document functions and their parameters using JSDoc. It illustrates how to describe function behavior, parameter details, and return types. The video also explains how JSDoc can automatically generate a table of parameters and their descriptions in the documentation, aiding in code comprehension and collaboration.

30:13

🏫 Creating Tutorials and Links

The video introduces the concept of adding tutorials to the JSDoc documentation. It shows how to create tutorial files in HTML or markdown format and how to link these tutorials to specific modules or code sections. The presenter also demonstrates adding external links and customizing the home page of the documentation.

35:17

📝 Adding a README and Final Touches

In the final part of the video, the presenter discusses adding a README file to the JSDoc documentation for an overview of the project. It also suggests customizing the home page with additional information such as author details, external links, and file descriptions. The video concludes by assigning homework to the viewers, encouraging them to implement JSDoc in their own projects.

Keywords

💡JSDoc

JSDoc is a JavaScript documentation generator that allows developers to annotate their source code with special comments. These comments, referred to as JSDoc comments, are then used to create an entire documentation website for the code. In the video, JSDoc is central to the theme as it is demonstrated how to integrate it into a project to document variables, classes, functions, and modules, enhancing code readability and maintainability.

💡Type Checking

Type checking in the context of the video refers to the process of verifying the data types of variables against their declared types in JSDoc comments. This feature is akin to TypeScript's type system but operates on JavaScript code. The script mentions using JSDoc for type checking to ensure variables are used with their intended types, providing an example where assigning a number to a string type variable results in a type error.

💡Documentation Website

A documentation website, as discussed in the video, is a web-based platform automatically generated by JSDoc from annotated source code. It provides a detailed overview of the project's codebase, including variables, functions, classes, and their usage. The script illustrates the process of generating such a website, which serves as a comprehensive reference for developers.

💡Inline Comments

Inline comments are annotations placed directly in the source code to explain what the code does. In the video, the term is used in the context of JSDoc, where developers add special comments in the form of '/** ... */' within the code to document functions, variables, and their usage. These comments are then parsed by JSDoc to create the documentation.

💡Templates

Templates in the JSDoc context refer to the predefined HTML structures that format the generated documentation. The video mentions the ability to customize these templates or use default ones to style the documentation website. It also shows how to point JSDoc to a custom template for a personalized documentation look.

💡Type Definitions

Type definitions in JSDoc are custom types created by the developer to specify the structure of an object. In the script, a 'student' type is defined with properties such as 'ID', 'name', 'age', and 'isActive'. This allows for more precise type checking and documentation of complex data structures used within the code.

💡Modules

Modules in JavaScript are a means of organizing code into reusable, interchangeable pieces. The video discusses how JSDoc can document modules, whether they are using CommonJS 'require' syntax or ES2015 'import/export' syntax. It demonstrates documenting a 'calculator' module with functions for basic arithmetic operations.

💡Tutorials

The script touches on the ability of JSDoc to include tutorials in the generated documentation. Tutorials can be written in HTML or markdown and are used to provide additional educational content or guides alongside the code documentation. An example is given where 'program-tutorial.html' and 'calculator-tutorial.md' are created to supplement the documentation.

💡Readme

A readme file is a text file that provides information about the project, its purpose, and how to use it. In the video, the concept of including a readme file in the JSDoc configuration is introduced, allowing the readme content to be part of the generated documentation. This is useful for giving an overview and instructions to users or developers interacting with the code.

💡Annotations

Annotations in the video refer to the JSDoc comments that are inserted into the source code to provide metadata about the code's functionality. These annotations are key to the documentation process as they describe the types, parameters, return values, and overall purpose of functions, variables, and classes.

Highlights

Introduction to JSDoc, a JavaScript documentation generator that creates a documentation website from inline comments in the source code.

JSDoc's capability to document variables, classes, functions, modules, and their types, enhancing code readability and maintainability.

The use of JSDoc for type checking similar to TypeScript without the need for compilation.

Compatibility of JSDoc with both backend (Node/Express) and frontend technologies like React or Vue.

Installation of JSDoc via npm and setup as a dev dependency in a project.

Explanation of the JSDoc configuration file and its role in defining source files and documentation settings.

How to create a documentation website with JSDoc by running a script from the package.json file.

Demonstration of adding JSDoc comments for variables, including types and descriptions, and generating documentation.

JSDoc's type checking feature, which provides real-time feedback on type errors in the code editor.

Enabling type checking in JSDoc by adjusting settings in the Visual Studio Code settings.json file.

Creating custom types using typedef in JSDoc for complex data structures.

Linking JSDoc comments to specific parts of the documentation for better navigation.

Documenting functions and their parameters in JSDoc, including return types and descriptions.

How to create and use a class in JSDoc, including constructors and methods.

Inclusion of tutorials in JSDoc documentation to provide additional learning resources.

Customization of the JSDoc template to fit the project's needs without altering the original files.

JSDoc's support for both CommonJS and ES2015 modules, documenting functions and their usage.

Assignment of homework to the viewers to implement JSDoc in an existing JavaScript project as a practical exercise.

Encouragement for viewers to explore JSDoc further and apply it to their projects for better code documentation.

Transcripts

[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