Documenting TypeScript, Finding the Right Tools for Your Project
Authored by Nazar Hussain
TypeScript (TS) is becoming increasingly popular in the JavaScript (JS) ecosystem. Many popular libraries, like LibP2P, DiscordJS, Node-Postgres, and Selenium Driver, have already started rewriting their JavaScript codebase in TypeScript, with many others following their lead.
As the use of TypeScript grows, so does the need for documentation. So, we created this resource to help developers find the right documentation tools for their TypeScript projects.
Context
Compared to legacy versions of JavaScript, TypeScript documentation has much room for improvement. One of the main differences between the two is the type of safety brought in by TypeScript at compile time. However, during compile time, TypeScript is converted to vanilla dynamically typed JavaScript, so it becomes essential to provide accurate documentation about "types" to users, ensuring they always benefit from type safety at both compile time and runtime.
The documentation needs for a commercial, user-facing product are different from the needs of a library or developer tool.
A project with a user base of other developers should share information about "types." A commercial product needs to document business flows, with occasional reference to some code. While, for a developer tool, users need API documentation. The abovementioned examples require two forms of documentation, one "static" and one "live," and directly generated from the source code.
Is there a standard?
For static documentation it's about what the developer is proficient with and what resources they have at their disposal. It could be plain text files, Google docs, Markdown docs, a locally hosted content management system, or any combination of the above.
On the other hand, a few standards are laid out below for documenting source code. These standards provide more compatibility across the different tools using the output. One example is IntelliSense which is provided by the integrated development environment (IDEs) and helps introduce a consistent pattern and methodology across projects.
JSDoc
The JSDoc standard is old, coming from JavaScript, but still valid and used for TypeScript. JSDoc was introduced in 2011 and was extended by the JavaDoc standard. It has a large ecosystem of templates and tools for developers to use. JSDoc has evolved, currently in its third iteration, into a stable and widely used standard.
TSDoc
A newer standard, introduced by the authors of TypeScript - TSDoc - is loosely based on JSDoc and tries to standardize the loose ends found in JSDoc. Historically, different tools based on JSDoc treated the JSDoc comments differently, resulting in compatibility issues across the tools. By adhering to already established practices, TSDoc fixes this issue.
Due to their similar grammar, average users wouldn't notice a significant difference between TSDoc and JSDoc. The TS developers intentionally modeled TSDoc's grammar after JSDoc's so users could easily bridge knowledge between the two.
Note: Please don't confuse the documentation standard with the parsing tools. e.g. TSDoc is a standard, and tsdoc **** is the first implementation of that specification. Similarly, jsdoc is the first widely used implementation of the JSDoc standard.
These documentation standards are not only helpful for generating documentation but are also useful in a variety of use cases. Linting tools have to follow a standard to lint docs. IntelliSense tools also have to follow a standard to provide instant feedback.
Documentation checklist
Finding the right balance of static and live documentation support for your needs is essential. We compiled a list to find the balance that most documentation requires.
TypeScript version support
Documentation tools must be compatible with the version of TypeScript in use. Otherwise, the documentation can suffer.
Documentation standard
It's essential to know what documentation standard the tools use. This step is necessary so that developers can share the tool's knowledge with the team while also allowing the setup of some tools to validate and lint the project, ensuring consistent documentation.
TSDoc support
While it's not necessary to have TSDoc support, it would be helpful if the tool supports it for compatibility's sake. As an emerging standard, there's enormous potential that, in the future, TSDoc will become the de facto standard for the TS codebase. So, if the tool already supports it, that's a significant plus.
Linting support
Linting is a critical step in the source code life cycle. As not everyone in a given team will have the same programming approach, enforced linting rules can help keep a codebase consistent.
For example, if one developer uses the forEach iterator and another uses the for loop, linting rules will give feedback to team members, ensuring they follow a uniform pattern. The same applies to documenting the source code, so it's essential to check that the tools have linting support.
Theme support
The output of the source document must be in some human-readable form, whether these are HTML pages, a PDF, or any other format. Every project needs to have a unique user experience in its documentation. Having theme support or some ways to customize the output is a significant benefit.
Code permalink
Documenting source code brings with it the utmost importance of accessibility. Users should be able to directly jump to the source code from the documentation to explore or understand it. Having a tool capable of generating code permalinks is vital.
Exclude files, patterns, and behavior
Sometimes developers don't want to expose all of their source code functionality in the documentation. Sometimes developers don't want to list a specific function in a class. Having the ability to exclude some files helps ensure clarity.
Mixing static content
Documentation needs can differ, so static and live documentation is often the most thorough approach. Using a tool that supports static content, such as tutorials and guides, in addition to generated content, ensures your project's needs are met.
Remember, documentation standards may provide some tags but don't enforce mixed static content. It's the parsing tools or documentation generators which provide these features.
Monorepo support
These days, large JS or TS projects follow Monorepo to structure their packages. So, resolving the cross-package references to generate documentation becomes more complex but necessary. This complexity makes Monorepo support an essential feature to look for while searching for documentation tools.
Export format
The final output of any documentation must be in a human-readable format. So it's crucial to consider which export formats a tool will support. I think HTML and Markdown are necessities.
Community
Documentation tools are just as crucial as packages or libraries in a developer's dependencies list. Looking for the community behind those tools is extremely important. A strong community can provide users with support at critical times.
License
Licenses are equally essential to look into while searching for documentation tools. These must match with the legal bounds of the project so that no one gets into any future trouble.
Note: One tool may not be able to handle all requirements independently and may have some supporting toolchain for the complete flow_._
Comparing documentation tools
Note: Docusaurus does not balance in these categories but is listed and compared because of its growing popularity.
The Rushstack toolchain from Microsoft, the API-Extractor and API-Documenter, is the most extensive toolchain to consider, along with the TSDoc parser. The toolchain developers thought of not just the documentation but also the complete process involved in it.
For example, the API-Extractor is responsible for extracting the public-facing API from a user's library. It generates two kinds of outputs, one for using tools like the API-Documenter, and one to be used during a future run of the API-Extractor (so developers can identify what API changes are involved with code changes).
Users can implement this step into their CI/CD and code review process, which will be tremendously helpful in identifying API changes. The negative impact of that process is performance degradation. If users add this step to the version control such that each team member pushes the validated code, it will slow down the local commit process.
Final thoughts
The ultimate breaking point with these tools, right now, is the unavailability of code permalinks and lack of support for a mixup of static content. As of now, TypeDoc is the best tool we've used, providing excellent utility and well-presented code documentation. Users can also mix in static content, covering the needs for custom tutorials, guides, or any business process. It also has a vast community and an extensive list of plugins to extend the functionality.
We also use Docusaurus. Docusaurus provides the most modern utilities for all static documentation needs. In addition, users can inject a live documentation section into Docusaurus. This combination of both static and live content makes the documentation process futureproof.
There is an excellent package for those interested that makes this integration seamless. Our latest TS rewrite of web3.js comes included with new documentation that will follow the same approach. Get a chance to see how it looks once the new documentation has gone live!
About ChainSafe
ChainSafe is a leading blockchain research and development firm specializing in infrastructure solutions for web3. Alongside its contributions to major ecosystems such as Ethereum, Polkadot, Filecoin, Mina, and more, ChainSafe creates solutions for developers and teams across the web3 space utilizing our expertise in gaming, bridging, NFTs and decentralized storage.
As part of its mission to build innovative products for users and improved tooling for developers, ChainSafe embodies an open source and community-oriented ethos to advance the future of the internet. To learn more, click here.
