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

Written by

learnmodernjavascript

in

In the world of software development, clear and accessible documentation is as crucial as the code itself. Imagine trying to navigate a complex codebase without any guides or explanations. It’s a recipe for frustration and wasted time. This is where a well-structured code documentation tool comes into play. It helps developers understand, maintain, and collaborate on projects more efficiently. In this tutorial, we will build a simple web-based code documentation tool using TypeScript, designed to help you generate and manage documentation for your projects. This tool will allow you to write documentation directly within your code and then generate a web page to display it.

Why TypeScript?

TypeScript, a superset of JavaScript, brings static typing to the language. This means you can catch errors during development, before your code runs. TypeScript also offers better code completion, refactoring, and overall code maintainability, making it an excellent choice for this project.

Project Overview

Our web-based code documentation tool will have the following features:

  • A text editor to write code and documentation.
  • The ability to parse special comments in the code to extract documentation.
  • A display area to render the extracted documentation in a readable format.
  • The ability to save and load documentation.

Setting Up the Project

Let’s get started by setting up our project. First, make sure you have Node.js and npm (Node Package Manager) installed on your system. If not, download and install them from the official Node.js website.

Create a new project directory:

mkdir code-documentation-tool
cd code-documentation-tool

Initialize a new npm project:

npm init -y

Install TypeScript and a bundler (like Parcel or Webpack). For simplicity, we’ll use Parcel in this tutorial:

npm install typescript parcel --save-dev

Create a tsconfig.json file in the root of your project:

{
  "compilerOptions": {
    "outDir": "dist",
    "module": "esnext",
    "target": "es5",
    "lib": ["es6", "dom"],
    "sourceMap": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

This configuration tells TypeScript how to compile your code. Important options include:

  • outDir: Specifies the output directory for compiled JavaScript files.
  • module: Sets the module system (esnext is modern).
  • target: Sets the ECMAScript target version (es5 for broad compatibility).
  • lib: Includes the necessary library files (es6 and dom for browser support).
  • sourceMap: Generates source maps for debugging.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • strict: Enables strict type checking.

Creating the HTML Structure

Create an index.html file in your project directory:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Code Documentation Tool</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div id="app">
    <div class="editor-container">
      <textarea id="codeEditor" placeholder="Write your code and documentation here"></textarea>
    </div>
    <div class="documentation-container">
      <div id="documentationOutput"></div>
    </div>
  </div>
  <script src="index.ts"></script>
</body>
</html>

This HTML file provides the basic structure for our tool, including a text area for the code editor and a div to display the generated documentation. It also links to a stylesheet (style.css) which we will create shortly, and the main TypeScript file (index.ts).

Create a basic style.css file in the same directory:

body {
  font-family: sans-serif;
  margin: 0;
  padding: 0;
  display: flex;
  flex-direction: column;
  align-items: center;
  background-color: #f0f0f0;
}

#app {
  display: flex;
  width: 80%;
  margin-top: 20px;
}

.editor-container {
  width: 50%;
  padding: 10px;
  box-sizing: border-box;
}

.documentation-container {
  width: 50%;
  padding: 10px;
  box-sizing: border-box;
  border-left: 1px solid #ccc;
}

#codeEditor {
  width: 100%;
  height: 500px;
  padding: 10px;
  box-sizing: border-box;
  font-family: monospace;
  font-size: 14px;
  resize: vertical;
}

#documentationOutput {
  padding: 10px;
  font-size: 14px;
  line-height: 1.5;
}

Writing the TypeScript Code

Now, let’s write the TypeScript code. Create a src directory and inside it, create an index.ts file.

First, let’s define a simple interface to represent our documentation:

interface Documentation {
  description: string;
  params?: { [key: string]: string };
  returns?: string;
}

Next, we will add the code to parse the documentation from the code comments:


function parseDocumentation(code: string): { [key: string]: Documentation } {
  const documentation: { [key: string]: Documentation } = {};
  const regex = //**s*@(w+)s*([^*]*)*/|//s*@(w+)s*([^*]*)/g;
  let match;
  let currentFunction: string | null = null;

  while ((match = regex.exec(code)) !== null) {
    const fullMatch = match[0];
    const tag = match[1] || match[3];
    const value = (match[2] || match[4]).trim();

    if (tag === 'function') {
      currentFunction = value;
      documentation[currentFunction] = { description: '' }; // Initialize with an empty description
    } else if (currentFunction) {
      if (tag === 'description') {
        if (documentation[currentFunction]) {
          documentation[currentFunction].description = value;
        }
      } else if (tag === 'param') {
        const [paramName, paramDescription] = value.split(' ').filter(Boolean);
        if (documentation[currentFunction]) {
          documentation[currentFunction].params = { ...documentation[currentFunction].params, [paramName]: paramDescription };
        }
      } else if (tag === 'returns') {
        if (documentation[currentFunction]) {
          documentation[currentFunction].returns = value;
        }
      }
    }
  }
  return documentation;
}

Now, let’s add the code to render the documentation to the screen:


function renderDocumentation(documentation: { [key: string]: Documentation }): string {
  let html = '';

  for (const funcName in documentation) {
    if (documentation.hasOwnProperty(funcName)) {
      const doc = documentation[funcName];
      html += `<h3>${funcName}</h3>`;
      html += `<p>${doc.description}</p>`;

      if (doc.params) {
        html += '<h4>Parameters:</h4>';
        html += '<ul>';
        for (const paramName in doc.params) {
          if (doc.params.hasOwnProperty(paramName)) {
            html += `<li>${paramName}: ${doc.params[paramName]}</li>`;
          }
        }
        html += '</ul>';
      }

      if (doc.returns) {
        html += '<h4>Returns:</h4>';
        html += `<p>${doc.returns}</p>`;
      }
    }
  }

  return html;
}

Finally, let’s add the main logic to tie everything together. Add the following code to your index.ts:


const codeEditor = document.getElementById('codeEditor') as HTMLTextAreaElement;
const documentationOutput = document.getElementById('documentationOutput') as HTMLDivElement;

if (codeEditor && documentationOutput) {
  codeEditor.addEventListener('input', () => {
    const code = codeEditor.value;
    const parsedDocumentation = parseDocumentation(code);
    const renderedDocumentation = renderDocumentation(parsedDocumentation);
    documentationOutput.innerHTML = renderedDocumentation;
  });
}

This code gets the text area and output div, and adds an event listener to the text area. Whenever the text in the text area changes, the code parses the documentation, renders it, and updates the output div.

Writing Documentation Comments

To use our tool, you’ll need to write documentation comments within your code. Here’s how to structure your comments:


/**
 * @function myFunction
 * @description This function performs a specific task.
 * @param {string} input - The input string.
 * @returns {number} The length of the input string.
 */
function myFunction(input: string): number {
  return input.length;
}

Here’s a breakdown of the comment tags:

  • @function: Marks the start of a function’s documentation. The value is the function’s name.
  • @description: Provides a description of the function.
  • @param: Describes a function parameter, including its name and a description.
  • @returns: Describes the return value of the function.

Running the Application

To run your application, add a script to your package.json file to build and run the project:


  "scripts": {
    "start": "parcel index.html",
    "build": "parcel build index.html"
  },

Now, run the application using the following command:

npm start

This will start a development server and open your documentation tool in your browser. As you type code and documentation comments in the left-hand text area, the rendered documentation will appear in the right-hand area.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

  • Incorrect Comment Syntax: Make sure you use the correct comment syntax (/** ... */ or //) and that your tags (@function, @description, etc.) are correctly formatted. Misspelled tags won’t be parsed.
  • Missing Function Name: The @function tag requires the function’s name to work correctly.
  • Incorrect Parameter Descriptions: Ensure your parameter descriptions are in the correct format (@param {type} parameterName - description).
  • Typographical Errors: Typos in your code or comments can prevent the tool from working correctly. Double-check for errors.
  • Bundler Configuration: Ensure your bundler (Parcel in this case) is correctly configured to handle TypeScript files. Check your tsconfig.json and make sure the output directory is correctly set.

Key Takeaways

  • TypeScript enhances code maintainability and helps catch errors early.
  • Understanding how to write documentation comments is essential for creating a good documentation tool.
  • Parsing and rendering documentation involves extracting information from comments and displaying it in a user-friendly format.
  • This tool can be expanded to include features like saving and loading documentation, and supporting more complex documentation structures.

FAQ

  1. Can I use this tool with other languages?
    • This tool is specifically designed for TypeScript. However, the core concepts of parsing and rendering documentation can be adapted to other languages. You would need to modify the parsing logic (the regular expressions) to match the documentation comment syntax of the target language.
  2. How can I add more features?
    • You can extend the tool by adding features like:
      • Support for different documentation styles (e.g., JSDoc).
      • Integration with a code editor (e.g., Monaco Editor) for syntax highlighting and auto-completion.
      • Saving and loading documentation to local storage or a server.
      • Generating documentation in different formats (e.g., Markdown, HTML).
  3. How can I improve the parsing logic?
    • The parsing logic can be improved by:
      • Using a dedicated parser library for more robust parsing of comments and code.
      • Adding support for more complex documentation structures (e.g., nested documentation).
      • Handling edge cases and error conditions more effectively.
  4. How do I deploy this tool?
    • You can deploy this tool by:
      • Using a static site hosting service (e.g., Netlify, Vercel) to host the generated HTML and JavaScript files.
      • Using a server-side framework (e.g., Node.js with Express) to host the tool and provide additional features like saving and loading documentation to a database.

By following these steps, you’ve created a functional web-based code documentation tool. This is a foundational project; you can build upon it to create more sophisticated documentation systems. Remember, the key to good documentation is consistency and clarity. With this tool, you’re well on your way to writing better, more maintainable code, and helping others understand your work. The ability to generate and view documentation directly within a web browser makes it easy to share and collaborate on projects, fostering a more efficient development workflow. The project also highlights the benefits of using TypeScript for improved code quality and maintainability, and provides a solid foundation for further exploration into more advanced documentation generation techniques and tools.

More posts