Skip to content

📘 Use JSDoc and a few carefully crafted comments to document your JavaScript code!

Notifications You must be signed in to change notification settings

docdis/learn-jsdoc

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Learn JSDoc

Use JSDoc and a few carefully crafted comments to document your JavaScript!

Undocumented Code

"Good code is its own best documentation.
As you're about to add a comment, ask yourself,
'How can I improve the code so that this comment isn't needed?'
Improve the code and then document it to make it even clearer." ~ Steve McConnell (Code Complete)

"Always code as if the guy who ends up maintaining your code
will be a violent psychopath who knows where you live." ~ Martin Golding

Installation

Once you have Node.js installed in your terminal run:

npm install jsdoc

or if you have an existing node project, add jsdoc to devDependencies in package.json

Baby Steps

Create a javascript file and add the following comments/code

/**
 * Hello "Name"
 *
 * @param {string} name person/thing you want to say hello to.
 * @returns {string} Hello + name 
 */
function hello(name) {
  return "Hello "+name +"!";
}

Now run jsdoc in your command line: jsdoc

This will create the out directory which contains the mini-documentation for the simple hello function. Open the out/index.html file in your browser

JSDoc Hello World Example

The vast majority of JSDoc tags are useless. For a full list of tags see: http://usejsdoc.org/#JSDoc3_Tag_Dictionary

I will update this tutorial as and when I use a new tag. For now I'm only using @param, @returns and @example

FAQ

Q: Do I need Java to run JSDoc?
A: No. Java is not required. :-)

Useful Links

Tutorials

Investigate

Useless But Interesting Programming Quotes

Package.json

@todo Move this to main node.js tutorial

About

📘 Use JSDoc and a few carefully crafted comments to document your JavaScript code!

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • CSS 56.7%
  • HTML 37.0%
  • JavaScript 6.3%