🔨Documentation Tools

While your code is for machines, documentation is for humans. Using tools can make your documentation clearer, more standardised, and easier to navigate.

Overview

There are countless tools available that can help automate, enhance, and simplify the documentation process.

API Documentation with Swagger

Swagger, now known as OpenAPI, is a framework for API specification that includes a suite of tools for auto-generating documentation.

Introduction

Swagger helps you design and document APIs at scale. With its annotations, you can add metadata to your code, and Swagger uses this to generate beautiful, interactive documentation.

How-to guide

1. Annotate your code with Swagger-specific comments.

2. Use the Swagger UI tool to generate a visual documentation webpage.

JavaScript and TypeScript Documentation

JSDoc & TypeDoc

• JSDoc: A classic in the JS world, it lets you generate API docs from /** ... */ style comments in your code. Especially great for vanilla JavaScript projects.

• TypeDoc: Specifically for TypeScript lovers. Generates documentation similarly to JSDoc but is fine-tuned for TypeScript's unique features.

Docco

This is a slightly different approach, producing side-by-side annotated source docs. Perfect for when you want readers to dive deep into the code.

Java Documentation with Javadoc

Javadoc is a tool for generating API documentation in HTML format from Java source code.

Basics

Javadoc uses special annotations in code comments. When the tool runs, it scans these annotations and generates the documentation.

Best practices

• Always document public classes and methods.

• Use meaningful descriptions and avoid redundancy.

Other Notable Tools

• Docusaurus: A tool for building websites, especially suited for docs.

• MkDocs: A fast and simple static site generator geared towards building project documentation.

• Slate: Helps you create responsive API documentation with a clean, intuitive design.

Exercises & Examples

1. Write a basic Java method and document it using Javadoc.

2. Explore the Swagger UI with a popular open-source API.

3. Experiment with JSDoc on a small JavaScript function and view the generated documentation.