# TypeScript 文档注释规范
::: details 目录
[[toc]]
:::

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

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

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

### 全局安装
```shell
D:\Project\ts> npm install --global typedoc
```

### package.json
配置项目的 package.json, 增加 typedoc 的依赖。
```json{5}
{
    ......
    "devDependencies": {
        ......
        "typedoc": "^0.17.7",
        ......
    },
    ......
}
```

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

```shell
D:\Project\ts> npm install
```

## 使用

```shell
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 | 包含媒体，应该是一个文件夹的名字，会包含文件夹下的图片等各种媒体文件（需要使用 !\[logo](media://logo.png) 引入） |

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

### @author
----

可以有多个作者。

**语法：**
```
@author name-text
```

**参数：**

* *name-text*

&emsp;&emsp;    作者。

**示例：**

一个作者
```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*

&emsp;&emsp;    废除的原因。

**示例：**
```typescript{5,14}
/**
 * 点数据类型定义
 *
 * @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*

&emsp;&emsp;    抛出的异常类。

* *description*

&emsp;&emsp;    异常描述。

**示例：**
```typescript

```


### @param
----
函数入参。

**语法：**
```
@param  parameter-name description
```

**参数：**

* *parameter-name*

&emsp;&emsp;    参数名。

* *description*

&emsp;&emsp;    参数描述。

**示例：**

函数入参

```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   <T>     泛型类型
 * @param   arg     入参
 */
function identity<T>(arg: T): T {
    return arg;
}
```

### @return
----
函数返回值描述。

**语法：**
```
@return  description
```

**参数：**

* *description*

&emsp;&emsp;    返回值描述。

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

### @see
----

**语法：**
```
@see  reference
```

**参数：**

* *reference*

&emsp;&emsp;    参考对象。

**示例：**
```typescript

```

### @serial 或 @serialField 或 @serialData
----

**语法：**
```
@serial  field-description | include | exclude
```

**参数：**

**示例：**
```typescript

```

### @serialField
----

**语法：**
```
@serialField  field-name  field-type  field-description
```

**参数：**

**示例：**
```typescript

```

### @serialData
----

**语法：**
```
@serialData  data-description
```

**参数：**

**示例：**
```typescript

```

### @since
----

**语法：**
```
@since  since-text
```

**参数：**

* *since-text*

&emsp;&emsp;    起始版本。

**示例：**
```typescript
/**
 * @since   1.0.0
 */
export class SObject {
    //
}
```

### @version
----
版本号。

**语法：**
```typescript
@version  version-text
```

**参数：**

* *version-text*

&emsp;&emsp;    版本号。

**示例：**
```typescript{2}
/**
 * @version 2.2.56
 */
export class SObject {
    //
}
```