typescript文档化工具——Typedoc

Typedoc

简介：

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

构建出来的项目api网页样例：http://typedoc.org/api/global...

Typedoc 参考链接:
http://typedoc.org/
https://github.com/Microsoft/...
http://www.xdnote.com/typedoc/#

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

项目使用

这个可归属到
https://segmentfault.com/a/11...

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;
}