Typedoc: a tool for typescript documentation

Time:2021-4-8

Typedoc

Introduction:

Typedoc is a document generation tool of typescript language, similar to JSDoc.

Example of project API webpage constructed:http://typedoc.org/api/global…

Typedoc reference link:
http://typedoc.org/
https://github.com/Microsoft/…
http://www.xdnote.com/typedoc/#

Name function remarks
@Param parameter description is only used for class, interface and method annotation. Multiple param descriptions can appear in the same comment block at the same time.
@Return return description is only used for method comments. All methods except void must have a return description.
@The throws exception describes zero to multiple.
@Exception describes zero to multiple exceptions.
@Must be in the author class and interface annotation. There can be zero or more.
@Version is required in the version description class and interface comments. Zero or one.
@There can be zero or more see reference descriptions.
@There is only one initial version of since.
@Serial serialization description, or @ serialfield or @ serialdata, can have more than one
@There is no more than one cancelled flag.

Project usage

This can be attributed to
https://segmentfault.com/a/11…

1. Install the module

npm i -D gulp typedoc gulp-typedoc

2. Create gulp configuration file

Create a gulp configuration file in the project root directory gulpfile.js

var gulp = require('gulp');
var typedoc = require("gulp-typedoc");
 
gulp.task("typedoc", function() {
    return gulp
        .src(["src/**/*.ts"])
        .pipe(typedoc({
            exclude:["node_modules",
                    "**/*+(index|.worker|.e2e).ts"],
            // TypeScript options (see typescript docs)
            module: "commonjs",
            target: "es5",
            includeDeclarations: false,
 
            // Output options (see typedoc docs)
            out: "./doc",
 
            // TypeDoc options (see typedoc docs)
            name: "my-project",
            ignoreCompilerErrors: false,
            version: true,
        }))
    ;
});

SRC: the target file can fill in multiple
Exclude: exclude some files
Out: the location of the output doc file
Ignorecompilererrors: ignore errors

3. Generate doc

Write test code Src / math/ color.ts

export class color
{
    /**
     *R channel
     */
    r:number;
    /**
     *G channel
     */
    g:number;
    /**
     *Channel B
     */
    b:number;
    /**
     *Channel a
     */
    a:number;
    /**
     *Red
     */
    static readonly Red:color=new color(1,0,0,1);

    constructor(r:number=1,g:number,b:number=1,a:number=1)
    {
        this.r=r;
        this.g=g;
        this.b=b;
        this.a=a;
    }
    /**
     *Copy color
     * @param from clone from
     *@ returns returns the new instanced color
     */
    public static clone(from: color): color
    {
        let item=new color(from[0],from[1],from[2],from[3]);
        return item;
    }

    /**
     * Copy the values from one color to another
     *
     * @param out the receiving vector
     * @param a the source vector
     * @returns out
     */
    public static copy(a: color,out: color): color{
        out[0] = a[0];
        out[1] = a[1];
        out[2] = a[2];
        out[3] = a[3];
        return out;
    }
}

Execute instructionsgulp typedocThe doc file can be generated in the target directory.

Expanding the use of typedoc

1. Typescript uses decorator

implementgulp typedocAn error will be reported and the doc file generation will fail

 Experimental support for decorators is a feature that is subject to change in a future release. Set the 'experimentalDecorators' option to remove this warning.

stay tsconfig.json In, experiential decorators has been set to true

{
    "compilerOptions": {
        "module": "es6",
        "target": "es5",
        "sourceMap": true,
        "declaration": true,
        "declarationDir": "./dist/typing",
        "experimentalDecorators": true,
        "lib": [
            "webworker",
            "es6",
            "es5",
            "dom"
          ]
    },
    
    "exclude": [
        "node_moudles",
        "dist"
    ]
}

modify gulpfile.js If the ignorecompilererrors in the file is true, the doc file will be generated successfully.
Note: Although the doc file is generated successfully, the above error still exists. If someone knows how to solve it, please leave a message.

var gulp = require('gulp');
var typedoc = require("gulp-typedoc");
 
gulp.task("typedoc", function() {
    return gulp
        .src(["src/**/*.ts"])
        .pipe(typedoc({
            exclude:["node_modules",
                    "**/*+(index|.worker|.e2e).ts"],
            // TypeScript options (see typescript docs)
            module: "commonjs",
            target: "es5",
            includeDeclarations: false,
 
            // Output options (see typedoc docs)
            out: "./doc",
 
            // TypeDoc options (see typedoc docs)
            name: "my-project",
            ignoreCompilerErrors: true,
            version: true,
        }))
    ;
});

2. Write instruction code for function

Refer to the following writing

/**
 *Copy color
 * @param from clone from
 *@ returns returns the new instanced color
* ```
* let a:color=color.clone(color.Red);
* ```
 */
public static clone(from: color): color
{
    let item=new color(from[0],from[1],from[2],from[3]);
    return item;
}