Over the past several months, the SitePen team has been hard at work on Dojo 2 along with the tools and infrastructure to support it. Part of that infrastructure, and one of the major priorities for Dojo 2, is to have top notch developer documentation, complete with examples, tutorials, and API documentation. The early fruits of this labor can be seen on the new dojo.io website.

For API documentation of JavaScript projects, JSDoc is a solid tool that gets the job done, and we wanted to be able to use something similar for TypeScript. JSDoc has support for type annotations in source code documentation comments, but this is redundant in TypeScript as the type annotations are provided in the code. We wanted to find a tool that was similar and a defacto standard, but that would take advantage of the TypeScript compiler API to derive the types of nodes.

Choosing a TypeScript API documentation tool

This is the role filled by TypeDoc. It is an API documentation generator, similar to JSDoc, but for TypeScript projects where it takes advantage of the type annotations and inference in the language to assist in the documentation creation. The comment structure is similar to JSDoc, but the type annotations are omitted. TypeDoc leverages the TypeScript compiler API to walk the abstract syntax tree (AST) and query the compiler service for a node’s type and relation to other syntax tree nodes within a module or project.

In our initial work with TypeDoc, we ran into a few issues with generating API docs for Dojo 2. So we searched for and experimented with several API documentation solutions, including the creation of a simple prototype of our own that would fit our needs, before we decided to use TypeDoc. Instead of leveraging comments for type annotations, TypeDoc determines type information from the TypeScript compiler API, utilizing TypeScript’s own self-documenting type syntax. It works well and generates API documentation, but as noted there were some issues we noticed in our early efforts, primarily that it did not support some of the new features in TypeScript 2.0+. This provided us with an opportunity to give back to the open source community by contributing some fixes and improvements to the TypeDoc codebase.

Improving TypeDoc

TypeDoc was written for an earlier version of TypeScript and the codebase followed some of the early patterns of development with TypeScript. We made several contributions including:

  • Adopting a more modern code style by utilizing more of the recent additions to ES6+. We converted all var usage to const and let
  • Adding TSLint to the project to normalize some inconsistencies in the code and set a standard for future contributions. This change sounds simple, but involved making style updates to 130 files in the project! This added consistency should ease maintenance and new feature development.
  • Several small changes to the project for bug fixes and improved compatibility with the newest versions of TypeScript
  • Adding support for more of the compilerOptions that can be set in tsconfig.json such as lib, which is used to load in specific ambient declarations for language and DOM features that will be used within a project.
  • Letting unknown to TypeDoc options to pass through to the TypeScript Program
  • Fixing an issue where Union types that are also arrays were not being rendered properly in the docs.

Future efforts

We did not find the TypeDoc codebase to be entirely intuitive upon our initial review, and while we’ve made several improvements, there is more to do to improve the codebase. TypeDoc currently relies on a number of plugins that listen for events being fired by the TypeDoc converter in order to render and apply properties to each type of node. The parsing of all of the options that TypeDoc supports is also a source for confusion, and there are a number of classes that are imported and instantiated through decorators. Going forward, we will be working to improve this and to simplify the converter code so that it relies more directly on TypeScript’s compiler API, to give it the information it needs to generate its internal project structure. We will also be researching how we can simplify other areas of the codebase. For example, signatures are constructed for each of the Node types that are in the AST, but could be achieved through a simpler querying mechanism through TypeScript’s Language Service API.

At SitePen, we understand the value that contributing to the open source community provides. TypeDoc is an established and popular solution for API documentation generation for TypeScript projects and we are happy to contribute back to make the project better for everyone, rather than simply forking the project for our needs. These contributions benefit our work on Dojo 2 and also benefit the projects that rely on it for their needs.