.   .   .
We're Hiring‼️ 🚀😄 And we're passionate about innovation, family, and community. Join us as we help tech startups and enterprise customers build their web apps. Apply today!
.   .   .

As we’ve been working on more npm packages in recent months, we wanted to make sure we properly documented our codebases. More than the usual code comments. We wanted to create documentation pages so new developers on our team would be able to easily dive in without a million questions.

A few days ago, we got the process down using JSDoc 3 and GitHub pages. Here’s the run down.

Getting Started with JSDoc

JSDoc while it seems antiquated from the website’s homepage is a set of conventions you can use to comment your javascript along with a CLI script to turn those comments into HTML documentation.

You can visit the JSDoc homepage for a complete dive into what it’s capable of, but I’m going to start with the basics needed to document your npm module.

Standard Comments vs JSDoc comments

Typically comments in javascript follow one of the following formats

// hello world

/* hello world */

/*
 * hello world
 */

To create JSDOC comments, you simply create all of your comments in one of the following formats (note the extra star after the first slash)

/** hello world */

/**
 * hello world
 */

You can read more here to get a better understand of how it works if you wish.

Commenting Functions

This is a little bit of an oversimplification. But you can comment each of your functions as shown below.

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number} Sum of a and b
 */
function sum(a, b) {
    return a + b;
}

More details here.

Commenting Classes

Simply comment your classes with the following comment convention.

/**
 * Creates a new Person.
 * @class
 */
function Person() {
}

var p = new Person();

More details here.

Commenting the rest

For anything you want JSDoc to document, like objects you’re exporting or anything else in that matter, you can do by simply creating a standard JSDoc comment. Like the following.

/**
 * Exported object
 *
 */
const obj = {
  importantThing: 'hello',
  importantOtherThing: 'world',
}

module.exports = obj;

Lastly, denoting your modules

Add this to the top of any file that’s exposing a public export.

/** @module */

The JSDoc website goes into much more detail than I’ve taken advantage of, so feel free to read this and surpass me, but for my purposes simply adding the above got the job done for me.

With that being said, those were the core pieces you need to have in place. Once you do, you’re ready to generate the docs.

Configuring The JSDoc CLI

Once your codebase is marked up with JSDoc syntax. It’s time to get started with the JSDoc CLI.

Start by installing JSDoc

yarn add jsdoc

Next create a JSDoc configuration file

Create a file named jsdoc.conf and add the following contents.

{
  "source": {
      "exclude": ["node_modules", "another-folder"]
  },
  "opts": {
    "template": "node_modules/docdash"
  }
}

You can get much more creative than I did, as there are a million more ways to expand JSDoc, but what I provided will get you off the ground.

You’ll also noticed that I chose the lodash template in the configuration file. That’s just a personal preference that I think makes the documentation look better out of the box.

Prepare you package.json

Add this line to the scripts section of your package.json file.

"scripts": {
  "generate-docs": "jsdoc -r  . -d docs -c jsdoc.conf README.md"
}

This update allows you to run yarn run generate-docs to generate your documentation. It recursively searches your entire codebase and generates documentation in a folder named docs. Lastly, in incorporates your README.md into the documentation on the homepage.

Give it a try

Run the following to generate your docs.

yarn run generate-docs

Then open the documentation folder in your browser

open docs/index.html

If everything went as planned, you should now see beautiful documentation generated for your javascript project. All you need to do is make sure you generate the documentation each time you make important changes to the codebase.

But the cake still needs icing. So assuming you’re pushing your code to GitHub, we’re going to get GitHub to automatically update and host your documentation page as you deploy updated docs.

Deploying to GitHub Pages

Now that your documentation has been generated in your docs folder and has been pushed to GitHub, it’s time to complete the final step and host that documentation with GitHub pages. With that being said, GitHub pages are always public. So if you don’t want your documentation available for the world to see, skip this step.

Connect GitHub Pages to Your project

Visit the settings page for your GitHub Project and connect your project to GitHub pages is the following section.

Set up GitHub pages

Visit your hosted documentation

When you finish connecting GitHub pages to your project, you’ll see a notice with the URL for your documentation. Visit that page.

Visit Your Page

If all went as planned, your documentation is live and it will automatically update as you update the docs folder in your repo.

Closing Thoughts

As I mentioned earlier, there’s way more you can do with JSDoc than what I described in this guide so be sure to check out the docs and see how far the rabbit hole goes!

If you gave this a shot and something isn’t working, it’s possible I left something out. So just let me know in the comments.

If everything worked like a charm, then heck yeah!

I hope this helped someone. Enjoy.

.   .   .

We're Hiring‼️ 🚀😄 Looking to join our team of web developers? We're passionate about innovation, family, and community. Apply today!