Documentation Automation

Documentation can be generated usingTypeDoc. It is tool for TypeScript project's.

TypeDoc Installation

Global installation

npm install --global typedoc

Local installation (in your project's directory as usual)

npm install --save-dev typedoc

After installation you can run command:

typedoc

to see available TypeDoc and TypeScript options for generation documents .

Next create filetypedoc.jsonin project's root folder with some basic options:

{
  "mode": "modules",
  "out": "docs",
  "theme": "default",
  "ignoreCompilerErrors": "true",
  "experimentalDecorators": "true",
  "emitDecoratorMetadata": "true",
  "target": "ES5",
  "moduleResolution": "node",
  "preserveConstEnums": "true",
  "stripInternal": "true",
  "suppressExcessPropertyErrors": "true",
  "suppressImplicitAnyIndexErrors": "true",
  "module": "commonjs"
}

Here property"out"means that we want to create documentation folder with namedocs.

Next is to add this lines into project'spackage.jsonscriptssection:

"docs": "npm run typedoc -- --options typedoc.json --exclude '**/*.spec.ts' ./src/app/",
"typedoc": "typedoc"

Here:

• "docs"

  • it is name of command to build documents

• our TypeDoc options are in

  typedoc.json

  file

• we are excluding testing

  **/*.spec.ts

  files

• source files form which documentation must be generated are in project's folder

  /src/app/

The command to build documentation is:

npm run docs

After successful command execution there will be message in console:

Documentation generated at /.../docs

where...is absolute path to documents folder and folder structure is:

|_docs
  |_assets
  |_classes
  |_modules
  |_globals.html
  |_index.html

Now you can open documents index.html file in browser.

Describing Models/Components/Services

Example of Model description:

/**
 * Description of class Contact.
 */

export class Contact {
  id: number;
  name: string;  
}

Example of Component description:

import { Component, OnInit } from '@angular/core';

/**
 * Description of component 'HomeComponent'.
 */

@Component({
    moduleId: module.id,
    selector: 'app-home',
    templateUrl: './home.component.html',
    styleUrls: ['./home.component.css']
})

export class HomeComponent implements OnInit {    
    constructor() { }
    ngOnInit() { }
}

Example of Service description:

import { Injectable } from '@angular/core';
import { Headers, Http } from '@angular/http';
import 'rxjs/add/operator/toPromise';
import { Contact } from '../classes/contact';

/**
 * Description for service 'ContactService'.
 */

@Injectable()
export class ContactService {
    constructor(private http: Http) { }    
}

Code comments

The documentation generator currently understands these javadoc tags:

@param <param name>
@return(s)

All other tags will be rendered as definition lists, so they are not lost.

Comment to some variable:

/**
* This is a doc comment for "someVar".
 */
var someVar:string = "value";

Function comments:

/**
 * Comment for method ´doSomething´.
 * @param target  Comment for parameter ´target´.
 * @param arg     Comment for parameter ´arg´.
 * @returns       Comment for return value.
 */

function doSomething(target:any, arg:number):number {
    return 0;
}

Modules comments

Modules can be commented like any other elements in TypeScript. As modules can be defined in multiple files, TypeDoc selects the longest comment by default. One may override this behaviour with the special@preferredcomment tag.

/**
 * Actual module comment.
 * @preferred
 */
module MyModule { }

/**
 * Dismissed module comment.
 * This is the longer comment but will be dismissed in favor of the preferred comment.
 */
module MyModule { }

HTML tags in comments

It is possible to use HTML tags in comments. For example:

/**
 * Description with HTML tags.
 *
 * <pre>{
 *    'firstName': 'John',
 *    'lastName': 'Doe'
 * }</pre>
 *
 * Link to: <a target="_blank" href="https://www.google.com/">Google</a>
 */