TOAST UI Doc: A Tool That Will AWESOMEIFY Your JavaScript API Documentation

If you are reading this, it may be safe to assume that you are a developer who has had an experience with writing an API documentation. Let's assume that someone told you to write API documentation for hundred functions. What kind of image comes to your mind? Is it an image of you opening a new excel or a word document and enumerating hundred different functions and descriptions while meticulously staring at the source code? If you are one of the lucky ones who are fortunate enough to have prior experience with documenation generators and therefore are aware of the benefits they provide, such nightmare would not have crossed your mind for even a little bit.

For those who are yet to know what a documentation generator is, like Java's Javadoc and Python's Sphinx, documentation generator is a tool that parses through the comments made in the source file, and compiles the information regarding classes, methods, and the API into an HTML document. If the source file has been adequately commented during development, you can forgo the tedious process of manually writing the API documentation with a single line of command provided by the documentation generator. Obviously, such tool exists for JavaScript as well, and JSDoc is one of the most famous documentation generators for JavaScript.

At NHN Cloud's FE Development Lab, we have enthusiastically utilized such documentation generators. We have even built on the original JSDoc to build our own customized TOAST UI JSDoc Template, and have used this very module to document our TOAST UI APIs. Also, recently, we have published the TOAST UI Doc, our own documentation generator. While it may be similar to the previous TOAST UI JSDoc Template, this project was started in order to build a JavaScript documentation generator that is better in terms of development and management. In this article, I plan on sharing the story of how TOAST UI Doc came to be, including the general timeline of the development cycle, used technology, and offered benefits. With hopes that TOAST UI Doc would be able to be recognized as one of the most helpful documentation generators for JavaScript, let's dig in!

How TOAST UI Doc Came to be Released

Before TOAST UI Doc was released, TOAST UI JSDoc Template, JSDoc Template for simplicity's sake, was used in drafting API documentation for TOAST UI products. The image below illustrates the process of generating API documents.

JSDoc Template was nothing more than a template, not a documentation generator. JSDoc parses the comments from JavaScript, and gives it structure in the shape of an HTML file with the help of templating. If you set the template to be tui-jsdoc-template in JSDoc's config file, the TOAST UI's template will be applied instead of the default template. The LNB (tabs, search, toggle menu etc.) and the Examples page, as visible on the JSDoc Template's demo page, are added features that we have extended from the JSDoc.

While it attracted and helped many users in that it offered a wider range of features than the default template does (it was even linked to JSDoc's Github Readme,) users have also claimed that it lacked readability, making the API not as accessible. In order to target such issue, we have decided to improve our JSDoc Template's design.

Is Improving the Design Enough?

As we were getting ready to start the design improvement process, we thoroughly examined the JSDoc Template and found some issues ourselves. Because it is a template that was extended from the JSDoc's default template, it had numerous JSDoc module dependencies, and the code was messy. Therefore, it became even more complicated when we tried to add or modify a feature, in that we needed to have a strong grasp on the inner workings of JSDoc and its implementation. Also, JSDoc's processing of Taffy type parsing data and using the template file (*.tmpl) made JSDoc Template maintenance an extremely convoluted task.

Therefore, before we could do anything about the design, we needed to figure out a way to solve the maintenance issue, so we started looking for alternatives to JSDoc. There was a number of documentation generators for JavaScript. The image below is a popularity comparison of JavaScript documentation generators conducted in July, 2018.

JSDoc reigned supreme. We considered other tools on the list, but none satisfied the three qualities that we valued.

1. It must be able to parse JSDoc comments.
2. It must offer a template, and it must be extendable.
3. It must have had active commits within the last six months.

We have considered YUIDoc as well as ESDoc, but both have suffered blows when JSDoc rose to popularity. It was then that we found a new tool. While we were looking at npm trend's npm download comparison chart, we ran into documentation.js.

Discovering documentation.js

documentation.js checked all of our boxes! Following are the characteristics that we found satisfactory.

• It supports ES5, ES2017, JSX, Vue, and Flow type.
• It offers JSDoc parsing data as Markdown and JSON.
• It offers API that can be used in the Node environment.

In terms of functionality, it was worth a shot. As a final check, we tested how we could extend the existing template. Upon speculation, documentation.js's default template had a UI that was similar to that of JSDoc Template, so we presumed that it would be an easy road ahead. However, we had to reimplement features like search and Examples page with respect to the documentation.js's template. In other words, we had to start all over from when we were first building our JSDoc template.

Two roads diverged in front of us. We could have either fixed the designs of JSDoc Template and be happy with already implemented features, or rebuild according to documentation.js despite the obviously glaring efforts.

Why Not Build a Wrapper?

While we leaned towards the latter, we knew that simply adding functionality to templates could not fix the problems that we had with JSDoc Template. documentation.js uses handlebars as templates, and much like JSDoc Templates, the process of extending a template complicated the code while providing numerous restrictions on data modification. Instead, we focused on the fact that documentation.js allowed us to use parsed data as JSON. If we have access to the parsing data we could have just built our own documentation generator without having to rely on other tools' templates.

Then, we found a way to create templates and generate documentations: the Static Site Generators! Static webpages are pages built purely with HTML, CSS, and JavaScript. Using static site generators, we could retrieve the product as an HTML file like the documentation generators and build our own templates.

If you are familiar with Github pages, you should also be familiar with Jekyll. Furthermore, recently, numerous static site generators are offered as open source projects.

We decided to build a wrapper with a built-in static site generator that could generate JavaScript API documentation. The following is a simple breakdown of the wrapper's structure.

Choosing Gatsby

All that was left to do was to choose which static site generator to use. Two candidates were considered: Gatsby and Docusaurus. Both have active contributors and can support React components when building templates. Additionally, they both make page generation and distribution incredibly easy with the help of CLI and option configurations.

While Docusaurus seemed more appropriate than Gatsby for a documentation generator because of the version control capabilities and easy CI configuration, it had more limitations when it came to UI extension. For example, we had to use options to implement the LBN and headers instead of using React components. In other words, we were still dealing with templates. Lastly, the main problem was that Docusaurus only allowed Markdown to be used internally, making it difficult to implement the intricate designs.

Contrarily, Gatsby allowed us to implement everything that we had in mind. The image below depicts Gatsby's workflow, and while the overall flow is not much different from that of other static site generators, the technology stack used is stronger than any other tool out there.

(Source : https://www.gatsbyjs.org/)

The following sections examine Gatsby's most important features.

SPA Development

Using Gatsby, you can develop Single Page Applications (SPAs) using GraphQL and React. GraphQL helps us to get data from the data source, and Gatsby even supports static query through GraphQL. Furthermore, because it is built with React, we can easily build components to extend the features, and can work as if we were developing a regular React application.

Variety of Plugin Support

Gatsby plugins also help us to reduce manual labor that goes into development. For example, instead of manually configuring code highlighting features, you could simply install the gatsby-remark-prismjs plugin and start using it immediately.

Convenient Build Process

Gatsby provides us with a Gatsby CLI to facilitate development and build. Gatsby generates static websites using Webpack, and because Gatsby has a built-in Webpack configuration, as a user, you simply have to execute Gatsby commands. If your project requires more intricate configuration, you can use Gatsby's configuration file to better suit your needs. Furthermore, by providing the development server, you can view the product in live time as you build.

Distribution as a Static Site

Sites that have been developed as SPAs create pages on the server side according to the accessible paths while the build is underway. The static sites are built through such process, and can be used with Github pages, despite the fact that Github pages do not support SPAs.

The following is a summary of benefits that come with using Gatsby as a new documentation generator.

1. It can process data as JSON with the help of GraphQL and plugins. In other words, it can help us use the parsed data from documentation.js.
2. It is easy to maintain, as the template can be built as a single application using React components.
3. Because the produced document is an SPA, it offers better user-experience compared to documentation generated using other tools, in that users do not have to refresh the page.

Gatsby was perfectly suitable for our new documentation generator.

The Creation of TOAST UI Doc

Finally, we had a more solid picture of replacing the JSDoc Template. TOAST UI Doc (package name: @toast-ui/doc), with the help of documentation.js and Gatsby, was our own and brand new documentation generator.

Benefits of Using TOAST UI Doc

TOAST UI Doc is an upgraded version of the JSDoc Template in terms of functionality and as well as design. TOAST UI Doc does not merely serve as a documentation for the JavaScript API, but is much more. Now, let's explore deeply into TOAST UI Doc, and allow me to introduce the benefits TOAST UI Doc offers!

AWESOME! Design

API Documentation must allow developers to easily access necessary API information at first glance. The readability issue is a lot more complicated than tinkering with font sizes and colors. The UI must be well designed to aptly display the information according to different types of the API. TOAST UI Doc carefully considered such issues so that the improved design may effectively display relevant API information.

The following image is an actual screenshot of TOAST UI Grid API documentation generated using TOAST UI Doc. Compared to previous documentations with JSDoc Template and documentation.js template, the documentation generated using TOAST UI Doc is much easier on the eyes.

The following features help TOAST UI Doc to be comparatively more readable.

Segmented LNB Menu Structure

TOAST UI Doc's LNB is one of its main features. While LNB menu allows users to navigate through the document's different pages, it serves a more important purpose. The LNB menu enables users to grasp the general API information regarding different types and implementations used in the library. TOAST UI Doc provides seven implementations and five API types, and the LNB is structured according to the JSDoc information defined in the code.

• Seven Implementations (Main Menu)

  • MODULES
  • EXTERNALS
  • CLASSES
  • NAMESPACES
  • MIXINS
  • TYPEDEF

• Five API Types (Sub Menu)

  • EXTENDS
  • MIXES
  • STATIC PROPERTIES
  • STATIC METHODS
  • INSTANCE METHODS
  • EVENTS

Clear Parameter Exposure

Information regarding parameters during instance creation or a method call is incredibly valuable. It is difficult to obtain necessary information if the parameter is an object that is buried deeply under multiple layers of lower properties. In order to solve this problem, TOAST UI Doc uses the multi table structure to display parameter information. Furthermore, although table's columns are used for optional and default values, declarative syntax like [foo], bar = 0 are accepted, and each type (number, boolean, string, array, object, function, and etc.) has different color as to be even more distinguishable.

Numerous Emphasis Features

Furthermore, we carefully considered ways to put emphasis so that users can fully deliver any API information including LNB menu state, icon, and code highlights. Especially for code highlighting feature, because it is built using the TOAST UI's brand colors, it is much more readable than other code highlighting themes.

Using Examples Pages to Introduce Libraries

When working with component level JavaScript libraries, it would be helpful if there were a way for users to experiment with the library themselves. TOAST UI Doc uses the Examples Pages to achieve such goal. Users can access variety of examples by clicking on the 'Examples' tab at the top of the LNB, and each page is complete with simple demos and necessary scripts and markups when using the library. With the help of TOAST UI Doc, you don't need to manage the API and Examples separately. You can easily view, find, and explore necessary information with a click of a button.

Convenient Search

TOAST UI Doc provides a search feature for users to search through APIs within the document. The search bar is located at the top of the LNB, and can be used to search through the APIs and Examples pages. The search bar is complete with autocomplete feature that displays possible search targets, and can be used to access and search information quickly.

Using Permalinks to Inspect Code

Permalinks provide a permanant URL to a designated page. Github also offers permalinks to source codes, and TOAST UI Doc uses these permalinks to link the original source code to the API documentation. File name of the source code that prompted JSDoc and the line number are displayed at the right section of the API area as a link, and by clicking on the link, users are redirected to the actual Github repository. This feature is incredibly useful when studying the implementation detail of the API with JSDoc.

TOAST UI Doc User's Manual

Now that you know how the TOAST UI Doc came to be and its benefits, let's actually start using it. And it is easy as advertised.

Install and Environment Configuration

First, install the TOAST UI Doc globally from npm.

$ npm install -g @toast-ui/doc

Next, navigate to the project folder for which to create the documentation, and create the configuration file (tuidoc.config.json) at the root. Use this config file to customize necessary information when generating the documentation. Each option and respective values are explained in greater detail here.

project/
  ├─ ...
  ├─ package.json
  └─ tuidoc.config.json

Drafting the JSDoc

When the TOAST UI Doc is executed, documentation.js will parse the JSDoc from the JavaScript file and process it as a JSON file. Draft your JSDoc according to your API information. In the example below, information regarding MyDoc class and its member getValue() method. You can try it yourself using the demo code and experiment with different ways to generate examples.

/**
 * @class MyDoc
 */
class MyDoc {
  constructor() {
    /**
     * @type {string}
     * @private
     */
    this.title = 'Hello TOAST UI Doc!';
  }

  /**
   * Returns value of title.
   * @returns {string} Title of MyDoc class
   */
  getValue() {
    return this.title;
  }
}

Generating the Documentation

TOAST UI Doc provides a CLI for users to be able to generate documentation conveniently. The tuidoc command, when executed, generates the documentation, and --serve option can be used to preview the generated product in local server. Then, add the script to the package.json as shown in the example below. If the documentation has been created without any issues, you should be able to see that two new folders called _latest and _[SemVer] have been created under the root. Simply upload these folders to either Github pages or to the server, and you're done!

npx tuidoc

Now that wasn't so hard, was it? You have just created your first TOAST UI Doc documentation!

Closing Remarks

TOAST UI Doc is a longterm project that took us over a year to build. We faced numerous challenges when Gatsby proceeded with a major update as we started developing with Gatsby v1.0, and when we were ready to publish, we had to apply it to all of TOAST UI products and had to make sure that we did not miss anything. Like any other project, we were bound to face difficulties. However, these hardships that we faced have become a valuable chance for us to learn the alpha and the omega, ins and outs of the documentation generators. Now that we have awesomified our TOAST UI documentation, it is your turn to awesomeify your JavaScript library API documentation!💪

The TOAST UI Doc is available for download here.