Typedoc

简介：

Typedoc 是一个 TypeScript 语言的文档生成工具，类比 jsdoc。

构建出来的项目api网页样例：

Typedoc 参考链接:

名称    作用    备注@param    参数描述    仅供类、接口、方法注释时使用。同一个注释块可同时出现多个param描述。@return    返回描述    仅供方法注释时使用。除void方法外其它所有方法必须有一个return描述。@throws    异常描述    零到多个。@exception    异常描述    零到多个。@author    作者    类和接口注释中必须有。可有零到多个。@version    版本描述    类和接口注释中必须有。零或一个。@see    参考描述    可有零到多个。@since    起始版本    只有一个。@serial    序列化描述    或@serialField或@serialData，可有多个@deprecated    废除标志    最多一个。

项目使用

这个可归属到

1.安装模块

npm i -D gulp typedoc gulp-typedoc

2.创建 gulp配置文件

在项目根目录下创建 gulp配置文件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 ：目标文件可以填写多个

exclude ：排除一些文件out：输出的doc文件存放位置ignoreCompilerErrors：是否忽略错误

3.生成doc

写测试代码src/math/color.ts

export class color{    /**     * r通道     */    r:number;    /**     * g通道     */    g:number;    /**     * b通道     */    b:number;    /**     * a通道     */    a:number;    /**     * 红色     */    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;    }    /**     * 复制 color     * @param from clone from     * @returns 返回 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;    }}

执行指令 gulp typedoc即可在目标目录生成doc文件。

typedoc使用拓展

1.typescript使用装饰器

执行gulp typedoc会报错，并导致生成doc文件失败

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

在tsconfig.json中,experimentalDecorators已经设置为true

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

修改gulpfile.js文件中ignoreCompilerErrors 为true，即可成功生成doc文件。

备注：虽然成功生成doc文件，但是上面的报错依旧存在，有人知道怎么解决，请可以留言。

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.给function写 指导代码

参考下面的写法

/** * 复制 color * @param from clone from * @returns 返回 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;}