Generating TypeScript documentation generation

There’s a great little tool called TypeDoc that allows us to generate html documentation based in our comments inside our TypeScript files similar to what JavaDoc does. To use this tool follow these steps:

  1. Install nodejs: http://nodejs.org/dist/v0.10.35/node-v0.10.35-x86.msi
  2. Open command line and run nodejs by typing: node
  3. In the nodejs prompt install typedoc by typing: npm install –global typedoc
  4. Type: typedoc -t ES5 –out doc/ references.ts

This will compile all the documentation (classes, namespaces, functions, etc.) that can be referenced by the file references.ts and it will be put under the doc folder in the current directory where that command is ran.

It’s preferred to update your project’s documentation from time to time and TypeDoc has integration with tools like Grunt but if you want this to run after you create a build you can add this command to the post build events list of commands the way I’ve shown in the previous post. For example:

<Exec Command="typedoc -t ES5 --out &quot;$(ProjectDir)/doc/&quot; &quot;$(ProjectDir)/tsDec/references.ts&quot;" />

TypeDoc follows JavaDoc comment tags:

@param <param name> <description>
@returns <description>

Examples:

/**
* This is a function.
* @param arg This is the argument.
* @returns Returns a value.
**/
function func(arg: text): string;

/**
* This is a name.
**/
var name:string = "a name";

You can also use the @preferred tag if you have different comments for the same thing (e.g. a module that is declared in different files and has different comments in both files or an interface and its class implementation) and you want to use a specific comment over the other as TypeDoc will use the first comment that it finds.

Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *