TypeScript Tutorial: Building a Simple Web Application for a Code Documentation Generator

Written by

learnmodernjavascript

in

In the world of software development, clear and concise documentation is as crucial as the code itself. Imagine trying to navigate a complex codebase without any guides or explanations – it would be a developer’s nightmare! This is where code documentation generators come to the rescue. They automatically parse your code and generate documentation, saving you time and effort while ensuring your projects remain understandable and maintainable. In this tutorial, we’ll dive into building a simple web application using TypeScript that serves as a code documentation generator. We’ll focus on a simplified version to keep things manageable for beginners to intermediate developers, but the core concepts will be applicable to more complex scenarios.

Why Code Documentation Matters

Before we jump into the code, let’s briefly touch upon why code documentation is so important:

  • Improved Collaboration: Well-documented code allows team members to quickly understand and contribute to projects.
  • Enhanced Maintainability: Documentation makes it easier to update and maintain the codebase over time.
  • Reduced Debugging Time: Good documentation can help developers identify and fix bugs more efficiently.
  • Knowledge Retention: Documentation serves as a valuable resource for future reference, especially when revisiting projects after a long break.

Setting Up Your Development Environment

To get started, you’ll need the following:

  • Node.js and npm (or yarn): These are essential for managing project dependencies and running our application. You can download them from https://nodejs.org/.
  • A Code Editor: Choose your favorite code editor, such as Visual Studio Code, Sublime Text, or Atom.
  • TypeScript Compiler: We’ll install this locally in our project.

Let’s create a new project directory and initialize it with npm:

mkdir code-doc-generator
cd code-doc-generator
npm init -y

Next, install TypeScript and a few other packages we’ll need:

npm install typescript ts-node --save-dev
  • typescript: The TypeScript compiler.
  • ts-node: Allows us to run TypeScript files directly without compiling them first.

Now, let’s create a tsconfig.json file to configure the TypeScript compiler. Run the following command:

npx tsc --init

This will generate a tsconfig.json file with default settings. You can customize this file to suit your project’s needs. For this tutorial, the default settings will suffice. You might want to adjust the outDir to specify where the compiled JavaScript files will be placed. Let’s create a src folder to put our code.

Building the Code Documentation Generator

Our generator will take a simple JavaScript or TypeScript file as input, parse its comments and function/class definitions, and generate a basic HTML documentation page. We’ll start with a simplified example to keep things clear.

1. Creating the Input File

Let’s create a sample TypeScript file (e.g., src/example.ts) that we’ll use as input. This file will contain a function and a class with some comments:

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

/**
 * Represents a simple Person class.
 */
class Person {
  /**
   * The person's name.
   */
  name: string;

  /**
   * Creates a new Person instance.
   * @param name The person's name.
   */
  constructor(name: string) {
    this.name = name;
  }

  /**
   * Greets the person.
   * @returns A greeting message.
   */
  greet(): string {
    return `Hello, my name is ${this.name}.`;
  }
}

Notice the comments above the function and class definitions. These are JSDoc-style comments, and our generator will parse these to create the documentation.

2. Parsing the Code and Extracting Information

Now, let’s create a TypeScript file (e.g., src/generator.ts) that will contain the logic for parsing the code and extracting the necessary information. We’ll use the typescript module to parse the code. First we need to install it.

npm install typescript

Here’s the basic structure of the generator:

import * as ts from 'typescript';
import * as fs from 'fs';
import * as path from 'path';

interface FunctionDoc {
  name: string;
  description: string;
  parameters: { name: string; description: string }[];
  returnType: string;
}

interface ClassDoc {
  name: string;
  description: string;
  methods: FunctionDoc[];
  properties: { name: string; description: string }[];
}

function parseFile(filePath: string): ClassDoc[] | FunctionDoc[] {
  const program = ts.createProgram([filePath], { allowJs: true, checkJs: false });
  const sourceFile = program.getSourceFile(filePath);

  if (!sourceFile) {
    throw new Error(`Could not find file: ${filePath}`);
  }

  const classDocs: ClassDoc[] = [];
  const functionDocs: FunctionDoc[] = [];

  function visit(node: ts.Node) {
    if (ts.isClassDeclaration(node)) {
      const className = node.name?.getText(sourceFile) || 'AnonymousClass';
      const classDescription = getJsDocDescription(node, sourceFile);
      const methods: FunctionDoc[] = [];
      const properties: { name: string; description: string }[] = [];

      node.members.forEach(member => {
        if (ts.isMethodDeclaration(member)) {
          const methodName = member.name?.getText(sourceFile) || 'AnonymousMethod';
          const methodDescription = getJsDocDescription(member, sourceFile);
          const parameters = member.parameters.map(param => ({
            name: param.name.getText(sourceFile),
            description: getJsDocDescription(param, sourceFile) || ''
          }));
          const returnType = member.type?.getText(sourceFile) || 'void';
          methods.push({
            name: methodName,
            description: methodDescription || '',
            parameters,
            returnType
          });
        }
        if (ts.isPropertyDeclaration(member)) {
          const propertyName = member.name.getText(sourceFile);
          const propertyDescription = getJsDocDescription(member, sourceFile);
          properties.push({
            name: propertyName,
            description: propertyDescription || ''
          });
        }
      });

      classDocs.push({
        name: className,
        description: classDescription || '',
        methods,
        properties
      });
    }

    if (ts.isFunctionDeclaration(node)) {
      const functionName = node.name?.getText(sourceFile) || 'AnonymousFunction';
      const functionDescription = getJsDocDescription(node, sourceFile);
      const parameters = node.parameters.map(param => ({
        name: param.name.getText(sourceFile),
        description: getJsDocDescription(param, sourceFile) || ''
      }));
      const returnType = node.returnType?.getText(sourceFile) || 'void';
      functionDocs.push({
        name: functionName,
        description: functionDescription || '',
        parameters,
        returnType
      });
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  return [...classDocs, ...functionDocs];
}

function getJsDocDescription(node: ts.Node, sourceFile: ts.SourceFile): string | undefined {
  const jsDocComments = ts.getLeadingCommentRanges(sourceFile.text, node.getFullStart());
  if (!jsDocComments) {
    return undefined;
  }

  const commentText = jsDocComments
    .map(comment => sourceFile.text.substring(comment.pos, comment.end))
    .join('n');

  // Extract description from JSDoc comments (e.g., from the first comment)
  const descriptionMatch = commentText.match(/*s*(.*?)(?:ns**s*@|$)/s);
  return descriptionMatch?.[1]?.trim();
}

function generateHTML(docs: ClassDoc[] | FunctionDoc[]): string {
  let html = '<title>Code Documentation</title>';

  docs.forEach(doc => {
    if ('methods' in doc) {
      // Class Documentation
      html += `<h2>Class: ${doc.name}</h2>`;
      html += `<p>${doc.description}</p>`;
      if (doc.properties && doc.properties.length > 0) {
        html += `<h3>Properties:</h3><ul>`;
        doc.properties.forEach(prop => {
          html += `<li><strong>${prop.name}</strong> - ${prop.description}</li>`;
        });
        html += `</ul>`;
      }
      if (doc.methods && doc.methods.length > 0) {
        html += `<h3>Methods:</h3><ul>`;
        doc.methods.forEach(method => {
          html += `<li><strong>${method.name}</strong> - ${method.description}</li>`;
          if (method.parameters && method.parameters.length > 0) {
            html += `<ul>Parameters:`;
            method.parameters.forEach(param => {
              html += `<li><strong>${param.name}</strong> - ${param.description}</li>`;
            });
            html += `</ul>`;
          }
          html += `<li>Returns: ${method.returnType}</li>`;
        });
        html += `</ul>`;
      }
    } else {
      // Function Documentation
      html += `<h2>Function: ${doc.name}</h2>`;
      html += `<p>${doc.description}</p>`;
      if (doc.parameters && doc.parameters.length > 0) {
        html += `<h3>Parameters:</h3><ul>`;
        doc.parameters.forEach(param => {
          html += `<li><strong>${param.name}</strong> - ${param.description}</li>`;
        });
        html += `</ul>`;
      }
      html += `<p>Returns: ${doc.returnType}</p>`;
    }
  });

  html += '';
  return html;
}

async function main() {
  const filePath = path.resolve(process.argv[2]); // Get the file path from command line arguments
  if (!filePath) {
    console.error('Please provide a file path as an argument.');
    process.exit(1);
  }

  try {
    const docs = parseFile(filePath);
    const html = generateHTML(docs);
    const outputFilePath = path.join(path.dirname(filePath), 'documentation.html');
    fs.writeFileSync(outputFilePath, html);
    console.log(`Documentation generated at: ${outputFilePath}`);
  } catch (error: any) {
    console.error('Error generating documentation:', error.message);
    process.exit(1);
  }
}

main();

Let’s break down this code:

  • Import Statements: We import necessary modules like typescript, fs (for file system operations), and path (for path manipulation).
  • Interfaces (FunctionDoc, ClassDoc): These interfaces define the structure of the data we’ll extract from the code.
  • parseFile(filePath: string) Function:
    • This is the core function for parsing the TypeScript file.
    • It uses the typescript module to create a program and get the source file.
    • The visit(node: ts.Node) function recursively traverses the Abstract Syntax Tree (AST) of the code.
    • When it encounters a class or function declaration, it extracts relevant information like name, description, parameters, and return type.
    • It uses getJsDocDescription() to extract the description from JSDoc comments.
  • getJsDocDescription(node: ts.Node, sourceFile: ts.SourceFile) Function: This function extracts the description from JSDoc comments.
  • generateHTML(docs: ClassDoc[] | FunctionDoc[]) Function: This function takes the parsed documentation data and generates an HTML page.
  • main() Function:
    • This is the entry point of the script.
    • It retrieves the input file path from the command line arguments.
    • It calls parseFile() to parse the code.
    • It calls generateHTML() to generate the HTML documentation.
    • It writes the HTML to a file (documentation.html) in the same directory as the input file.

3. Running the Generator

To run the generator, save the code above as src/generator.ts and execute the following command in your terminal:

npx ts-node src/generator.ts src/example.ts

Replace src/example.ts with the path to your TypeScript file. This will generate a documentation.html file in the same directory as your input file (e.g., if your input file is src/example.ts, the documentation will be generated at src/documentation.html).

Understanding the Code: Step-by-Step

Let’s break down some key parts of the code to understand how it works.

1. Parsing with the TypeScript Compiler

The typescript module provides the tools for parsing and analyzing TypeScript code. The core concept is the Abstract Syntax Tree (AST). The AST is a tree-like representation of the code’s structure. The TypeScript compiler creates this tree, and we can traverse it to extract information.

In the parseFile function, we use the following steps:

  • ts.createProgram([filePath], { allowJs: true, checkJs: false }): Creates a program, which represents a compilation process. The first argument is an array of file paths. The second argument is a set of compiler options.
  • program.getSourceFile(filePath): Gets the source file from the program.
  • ts.forEachChild(node, visit): This function recursively traverses the AST, calling the visit function for each node.

2. Traversing the AST

The visit function is crucial. It examines each node in the AST and determines what type of code element it represents (e.g., a class declaration, a function declaration, a variable declaration). It then extracts the relevant information.

For example, if the node is a class declaration (ts.isClassDeclaration(node)), the code extracts the class name and description. It then iterates through the members of the class (methods and properties) and extracts their information.

3. Extracting JSDoc Comments

JSDoc comments are essential for documenting your code. They are special comments that start with /** and contain descriptions, parameter information, and return types.

The getJsDocDescription function extracts the description from these comments. It uses the ts.getLeadingCommentRanges function to find the comment ranges associated with a node and then extracts the text from the comment.

4. Generating the HTML

The generateHTML function takes the extracted information and creates an HTML page. It iterates through the parsed documentation data and generates HTML elements for each class and function, including their descriptions, parameters, and return types.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to avoid them:

  • Incorrect File Paths: Make sure you provide the correct file path to your TypeScript file when running the generator. Double-check the path relative to your current working directory.
  • Missing JSDoc Comments: If your documentation is not showing up, ensure you have JSDoc-style comments above your functions, classes, and properties.
  • Compiler Errors: If you encounter compiler errors, check your tsconfig.json file and ensure you have the correct settings. Also, make sure your TypeScript code is valid.
  • Incorrect Package Installation: Double-check that you have installed all the necessary packages (typescript, ts-node) using npm or yarn.
  • Typo in JSDoc Tags: Be sure your JSDoc tags (e.g., @param, @returns) are correctly written. A typo can cause the generator to misinterpret the comments.

Enhancements and Next Steps

This is a basic example, but you can enhance it in several ways:

  • More Detailed Parsing: Add support for parsing more TypeScript features, such as interfaces, enums, and types.
  • Advanced HTML Formatting: Improve the HTML output with CSS styling, better layout, and navigation.
  • Integration with Build Tools: Integrate the documentation generation process into your build pipeline (e.g., using a task runner like Grunt or Gulp).
  • Support for Different Output Formats: Add support for generating documentation in other formats, such as Markdown or JSON.
  • Error Handling: Implement more robust error handling to provide better feedback to the user.
  • Command-Line Options: Add command-line options to customize the output (e.g., specify the output file name or format).
  • Automatic Detection of Input Files: Modify the script to automatically detect TypeScript files in a directory and generate documentation for all of them.

Key Takeaways

  • Code documentation is crucial for software development, improving collaboration, maintainability, and understanding.
  • TypeScript provides powerful tools for parsing and analyzing code, allowing you to extract information for documentation.
  • JSDoc comments are a standard way to document your code in TypeScript.
  • You can create custom code documentation generators to automate the process and tailor it to your needs.

FAQ

Here are some frequently asked questions:

  1. Q: Can I use this generator with JavaScript files?

    A: Yes, you can. The typescript module can parse JavaScript files as well. You might need to adjust the compiler options in your tsconfig.json file to allow JavaScript files.

  2. Q: How do I handle complex types in the documentation?

    A: The current example only handles basic types. You can extend the code to parse and display more complex types by examining the AST and extracting the type information from the nodes.

  3. Q: Can I generate documentation for external libraries?

    A: Yes, but it’s more complex. You would need to include the type definition files (.d.ts files) for the external libraries in your project and modify the parsing logic to handle the external code.

  4. Q: How can I customize the HTML output?

    A: The generateHTML function is where you control the HTML output. You can modify this function to add CSS styling, improve the layout, and include any other desired features.

  5. Q: What are the alternatives to building my own generator?

    A: There are many existing documentation generators for TypeScript, such as TypeDoc, JSDoc, and Compodoc. These tools are more feature-rich and often easier to use for larger projects. However, building your own generator provides a deeper understanding of the process and allows for greater customization.

Building a code documentation generator in TypeScript is a great way to learn about parsing code, working with the TypeScript compiler, and automating documentation tasks. While this tutorial provides a basic foundation, the possibilities for customization and enhancement are vast. By understanding the underlying principles, you can create a documentation solution that perfectly fits your project’s needs. Remember that well-documented code is a key ingredient for successful software development, ensuring that your projects remain understandable, maintainable, and enjoyable to work on for both you and your team. Embrace the power of automated documentation, and watch your projects thrive. The journey of software development is not just about writing code; it’s also about making that code understandable and accessible to everyone involved.

More posts