persagy-web-doc/docs/standard/typedoc.md

TypeScript 文档注释规范

::: details 目录 [[toc]] :::

介绍

Typedoc 是一个 TypeScript 语言的文档生成工具。可以根据我们写的 TypeScript 代码，直接生成 API 帮助文档。

参考地址：https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB

安装

可安装有全局安装与配置 package.json 文件两种方式。

全局安装

D:\Project\ts> npm install --global typedoc

package.json

配置项目的 package.json, 增加 typedoc 的依赖。

{
    ......
    "devDependencies": {
        ......
        "typedoc": "^0.17.7",
        ......
    },
    ......
}

在项目文件夹执行如下命令安装 typedoc。

D:\Project\ts> npm install

使用

D:\Project\ts> typedoc --out docs src

typedoc 参数

参数	类型	说明
out	string	输出目录
module	string	模块引入方式，可以是 commonjs, amd, system, umd
target	string	ES3(默认), ES5, ES6
name	string	项目标题
theme	string	皮肤可以是 default or minimal or 一个路径
readme	string	readme 文件，markdown 文件的相对地址
includeDeclarations	boolean	是否包含 .d.ts 文件，如果你的项目是 javascript 写的，可以使用声明文件的方式来支持 TypeScript 并生成文档
excludeExternals	boolean	是否排除外部引入的模块
excludePrivate	boolean	是否排除 private 修饰的相关字段方法
excludeProtected	boolean	是否排除 protected 修饰的相关字段方法
hideGenerator	boolean	隐藏页底的全局链接
version	boolean	显示 typedoc 版本
help	boolean	显示帮助信息
gaID	string	如果有 Google Analytics 的跟踪ID，可以设置
exclude	string	排除文件
includes	string	包含文件，应该是一个文件夹的名字，会将下面所有的md文件包含进来（需要使用 [[include:document.md]] 引入）
media	string	包含媒体，应该是一个文件夹的名字，会包含文件夹下的图片等各种媒体文件（需要使用  引入）

标签

标签	说明	备注
@author	作者	用于类和接口注释。可有零到多个。
@deprecated	废除标志	标识过期API（为了保证兼容性，仍可用，但不推荐用）。最多一个。
@exception @throws	异常描述	构造函数与函数注释使用，指示函数会抛出异常。可有零到多个。
@param	方法的参数	仅供类、接口、方法注释时使用。同一个注释块可同时出现多个param描述。
@return	返回描述	仅供函数注释时使用。除 void 方法外其它所有方法必须有一个 return 描述。
@see	参考描述	引用，查看相关的内容，如类，方法，变量等。可有零到多个。
@serial @serialField @serialData	序列化描述	可有多个。
@since	起始版本	只有一个。
@version	版本号	用于类和接口注释。零或一个。

@author

---

可以有多个作者。

语法：

@author name-text

参数：

• name-text

   作者。

示例：

一个作者 ```typescript {4} /**

• 点数据类型定义 *
• @author 庞利祥 sybotan@126.com */ export class SPoint { // } ```

多个作者 ```typescript {4,5} /**

• 点数据类型定义 *
• @author 庞利祥 sybotan@126.com
• @author 庞凌峰 sandy@126.com */ export class SPoint { // } ```

@deprecated

---

废除标志

语法：

@deprecated deprecated-text

参数：

• deprecated-text

   废除的原因。

示例：

/**
 * 点数据类型定义
 *
 * @author 庞利祥 <sybotan@126.com>
 * @deprecated  使用 SPoint 类代替。
 */
export class SPointF {

    /**
     * 平移点
     *
     * @param dx    X 轴位移
     * @param dy    Y 轴位移
     * @deprecated  不在支持
     */
    translate(dx: number, dy: number): void {
        this.x += dx;
        this.y += dy;
    }
}

@exception 或 @throws

---

标识函数会抛出异常。

语法：

@exception  class-name  description

或

@throws  class-name  description

参数：

• class-name

   抛出的异常类。

• description

   异常描述。

示例：

@param

---

函数入参。

语法：

@param  parameter-name description

参数：

• parameter-name

   参数名。

• description

   参数描述。

示例：

函数入参

```typescript {5,6} export class S {

/**
 * 平移矩形
 *
 * @param   dx      x 轴位移
 * @param   dy      y 轴位移
 */
translate(dx: number, dy: number): void {
    this.x += dx;
    this.y += dy;
}

}

构造函数入参

```typescript {5-8}
export class SRect {
    /**
     * 构造函数
     *
     * @param   x           x 轴坐标
     * @param   y           y 轴坐标
     * @param   width       宽度
     * @param   height      高度
     */
    constructor(x: number, y: number, width: number, height: number) {
    }
}

带泛型的函数 ```typescript {4,5} /**

• 返回对象的标识符 *
• @param 泛型类型
• @param arg 入参 */ function identity(arg: T): T { return arg; } ```

@return

---

函数返回值描述。

语法：

@return  description

参数：

• description

   返回值描述。

示例：

/**
 * 旋转变形
 *
 * @param   angle       绕 z 轴旋转角度（单位角度）
 * @return  返回自身
 */
rotate(angle: number): SMatrix {
    ......
    return matirx;
}

@see

---

语法：

@see  reference

参数：

• reference

   参考对象。

示例：

@serial 或 @serialField 或 @serialData

---

语法：

@serial  field-description | include | exclude

参数：

示例：

@serialField

---

语法：

@serialField  field-name  field-type  field-description

参数：

示例：

@serialData

---

语法：

@serialData  data-description

参数：

示例：

@since

---

语法：

@since  since-text

参数：

• since-text

   起始版本。

示例：

/**
 * @since   1.0.0
 */
export class SObject {
    //
}

@version

---

版本号。

语法：

@version  version-text

参数：

• version-text

   版本号。

示例：

/**
 * @version 2.2.56
 */
export class SObject {
    //
}