# 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.
