TypeScript Tutorial: Building a Simple Web-Based Code Documentation Viewer

Written by

learnmodernjavascript

in

In the world of software development, clear and accessible documentation is absolutely crucial. Imagine trying to understand a complex codebase without any guides or explanations – it would be a nightmare! This tutorial will guide you through building a simple web-based code documentation viewer using TypeScript. We’ll cover the basics, from setting up your project to displaying code documentation in a user-friendly format. This project empowers you to create readable, maintainable code, and it also makes it easier for others to understand and contribute to your projects. This tutorial is designed for developers who are new to TypeScript and want to learn how to build practical applications.

Why Build a Code Documentation Viewer?

Creating a code documentation viewer offers a multitude of benefits. Here are a few key reasons why you should consider building one:

  • Improved Code Understanding: Documentation viewers make it easier to understand the purpose, usage, and structure of code, which helps you and your team work more efficiently.
  • Enhanced Collaboration: Well-documented code promotes better collaboration among developers. They can quickly grasp the functionality of different code components.
  • Simplified Maintenance: Documentation helps in maintaining code over time. As code evolves, documentation acts as a roadmap, making it easier to make changes and fix bugs.
  • Faster Onboarding: New team members can quickly get up to speed with a codebase by using a documentation viewer.

Setting Up Your Project

Let’s get started by setting up the project. We’ll use Node.js and npm (or yarn) to manage our dependencies and build the project.

  1. Create a Project Directory: Open your terminal or command prompt and create a new directory for your project. Then, navigate into the directory.
mkdir code-documentation-viewer
cd code-documentation-viewer
  1. Initialize npm: Initialize a new npm project using the `npm init -y` command. This will create a `package.json` file.
npm init -y
  1. Install TypeScript: Install TypeScript and the necessary type definitions for Node.js and the DOM (if you plan to interact with the browser).
npm install typescript @types/node @types/dom --save-dev
  1. Create a TypeScript Configuration File: Create a `tsconfig.json` file in the root of your project. This file will configure the TypeScript compiler. Here’s a basic configuration: 
    {
  "compilerOptions": {
  "target": "es2016",
  "module": "commonjs",
  "outDir": "./dist",
  "rootDir": "./src",
  "strict": true,
  "esModuleInterop": true,
  "skipLibCheck": true,
  "forceConsistentCasingInFileNames": true
  }
}
  1. Create Source Directory: Create a `src` directory where you’ll store your TypeScript files. 
    mkdir src

Creating a Simple Documentation Parser

The core of our documentation viewer will be a parser that reads code comments and extracts information. We’ll use a simple approach to parse comments. This example focuses on parsing JSDoc-style comments, which are commonly used in JavaScript and TypeScript projects.

Let’s create a file named `src/parser.ts`.

// src/parser.ts

/**
 * Represents a function's documentation.
 */
interface FunctionDocumentation {
  name: string;
  description: string;
  parameters: { name: string; type: string; description: string }[];
  returnType: string;
}

/**
 * Parses a TypeScript file and extracts function documentation.
 * @param code The TypeScript code as a string.
 * @returns An array of FunctionDocumentation objects.
 */
function parseDocumentation(code: string): FunctionDocumentation[] {
  const documentation: FunctionDocumentation[] = [];
  const functionRegex = //**([sS]*?)*/s*functions+([a-zA-Z0-9_$]+)(.*?)/g;
  let match;

  while ((match = functionRegex.exec(code)) !== null) {
  const comment = match[1];
  const functionName = match[2];

  const descriptionMatch = comment.match(/@descriptions+(.*)/i);
  const description = descriptionMatch ? descriptionMatch[1].trim() : '';

  const parameterMatches = comment.matchAll(/@params+{([^}]+)}s+([a-zA-Z0-9_$]+)s+(.*)/g);
  const parameters = Array.from(parameterMatches, (paramMatch) => ({
  name: paramMatch[2].trim(),
  type: paramMatch[1].trim(),
  description: paramMatch[3].trim(),
  }));

  const returnTypeMatch = comment.match(/@returns+{([^}]+)}/i);
  const returnType = returnTypeMatch ? returnTypeMatch[1].trim() : 'void';

  documentation.push({
  name: functionName,
  description: description,
  parameters: parameters,
  returnType: returnType,
  });
  }

  return documentation;
}

export { parseDocumentation, FunctionDocumentation };

This code does the following:

  • Defines a `FunctionDocumentation` interface to structure the extracted information.
  • Defines the `parseDocumentation` function to extract the documentation from the comments.
  • Uses regular expressions to find JSDoc-style comments and function declarations.
  • Parses the `@description`, `@param`, and `@return` tags from the comments.

Creating a Simple Example File

Let’s create a simple TypeScript file (`src/example.ts`) with some functions and JSDoc comments to test our parser.

// src/example.ts

/**
 * This function adds two numbers.
 * @description Adds two numbers and returns the sum.
 * @param {number} a The first number.
 * @param {number} b The second number.
 * @return {number} The sum of a and b.
 */
function add(a: number, b: number): number {
  return a + b;
}

/**
 * This function multiplies two numbers.
 * @description Multiplies two numbers and returns the product.
 * @param {number} a The first number.
 * @param {number} b The second number.
 * @return {number} The product of a and b.
 */
function multiply(a: number, b: number): number {
  return a * b;
}

export { add, multiply };

Building the Documentation Viewer

Now, let’s create a basic HTML structure and use our parser to display the documentation. We’ll create a simple HTML file (`public/index.html`) and a main TypeScript file (`src/index.ts`) that will render the documentation in the browser.

  1. Create `public/index.html`: This file will contain the basic HTML structure.



  
  
  <title>Code Documentation Viewer</title>


  <div id="app"></div>
  1. Create `src/index.ts`: This file will load the TypeScript file, parse its contents, and render the documentation on the page.
// src/index.ts
import { parseDocumentation, FunctionDocumentation } from './parser';
import * as fs from 'fs';
import * as path from 'path';

// Read the example file
const exampleFilePath = path.join(__dirname, 'example.ts');
const exampleCode = fs.readFileSync(exampleFilePath, 'utf-8');

// Parse the documentation
const documentation = parseDocumentation(exampleCode);

// Render the documentation
function renderDocumentation(docs: FunctionDocumentation[]): void {
  const appElement = document.getElementById('app');
  if (!appElement) {
  console.error('Could not find element with id "app"');
  return;
  }

  docs.forEach((doc) => {
  const docElement = document.createElement('div');
  docElement.innerHTML = `
  <h2>${doc.name}</h2>
  <p>${doc.description}</p>
  <h3>Parameters</h3>
  <ul>
  ${doc.parameters
  .map(
  (param) => `<li><b>${param.name}</b>: ${param.type} - ${param.description}</li>`
  )
  .join('')}
  </ul>
  <p><b>Return Type:</b> ${doc.returnType}</p>
  `;
  appElement.appendChild(docElement);
  });
}

renderDocumentation(documentation);

This `index.ts` file:

  • Imports the `parseDocumentation` function from `parser.ts`.
  • Reads the content of `example.ts` using `fs` module.
  • Calls `parseDocumentation` to parse the code.
  • Creates a simple HTML structure to display the documentation.
  • Renders the documentation in the `app` div.

Compiling and Running the Application

Now that we have the code in place, let’s compile the TypeScript code and run the application.

  1. Compile the TypeScript code: Open your terminal and run the following command to compile the TypeScript code. This will generate the JavaScript files in the `dist` directory. 
    tsc
  2. Open the HTML file in your browser: Open `public/index.html` in your web browser. You should see the documentation for the `add` and `multiply` functions displayed on the page.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect File Paths: Double-check your file paths in `src/index.ts` and ensure they match your project structure.
  • Missing Dependencies: Make sure you have installed all the necessary dependencies using `npm install`.
  • Compiler Errors: If you encounter compiler errors, carefully review the error messages and fix the TypeScript code.
  • Browser Console Errors: Open your browser’s developer console (usually by pressing F12) and check for any JavaScript errors. These errors can provide valuable clues about what’s going wrong.
  • Incorrect Regex: The regular expressions used in `parser.ts` are very basic. They might not work correctly with all types of JSDoc comments or code structures. Review and update the regex if necessary.

Improving the Documentation Viewer

The code documentation viewer we have built is a basic example, but you can enhance it in many ways. Here are some ideas:

  • Add Support for More JSDoc Tags: Extend the parser to handle more JSDoc tags, such as `@throws`, `@example`, and `@see`.
  • Implement a User Interface: Create a more user-friendly interface with features like search, filtering, and navigation. Use a framework like React, Vue, or Angular to build a dynamic and interactive UI.
  • Integrate with a Code Editor: Integrate the documentation viewer with a code editor, so you can view the documentation directly within your IDE.
  • Support Different Code Languages: Adapt the parser to support other programming languages besides TypeScript.
  • Add Code Highlighting: Use a library like Prism.js or highlight.js to add syntax highlighting to the code snippets.
  • Fetch Documentation from Files: Instead of reading the files locally, implement the functionality to fetch code from a remote location, like a Git repository.

Key Takeaways

  • Understanding TypeScript: You have gained practical experience in using TypeScript to build a real-world application.
  • Parsing Code: You have learned how to parse code comments and extract information.
  • HTML and JavaScript Interaction: You have learned how to use HTML, TypeScript, and JavaScript to display the parsed data.
  • Project Structure: You’ve learned how to structure a simple TypeScript project.

FAQ

  1. Can I use this documentation viewer for other programming languages?

    Yes, but you will need to modify the parser to handle the specific syntax and comment styles of each language. The core logic of the viewer (reading files, parsing data, and rendering it) can be adapted.

  2. How can I handle large codebases with this viewer?

    For large codebases, you should optimize the parsing process and consider using a more robust parsing library. Also, implement features like search and filtering to make it easier to navigate the documentation.

  3. What are some good UI frameworks to use?

    React, Vue.js, and Angular are popular choices. They provide components, data binding, and other features that can simplify the development of a user interface.

  4. How can I deploy this documentation viewer?

    You can deploy it on a web server or use a service like Netlify or Vercel. You will need to build the project and upload the `dist` directory and `public` directory to the server.

This tutorial provides a solid foundation for building a code documentation viewer in TypeScript. By following the steps and exploring the enhancements, you can create a powerful tool that helps you write better code, collaborate more effectively, and maintain your projects with ease. The ability to automatically generate documentation from your code is a significant advantage, ensuring that your projects remain well-documented and easy to understand as they grow and evolve. Building a documentation viewer is not just about creating a tool; it’s about fostering good coding practices and streamlining the development process, making software development more efficient and enjoyable.

More posts