# 注释
::: details 目录
[[toc]]
:::

注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码。

多行注释规则：
* 注释以“/**”开始，以“*/”结尾。
* "/**"与“*/”各占一行;
* 每一行注释都以“\*”打头，在“\*”与注释内容之间间隔一个空格；

## 写注释注意事项
### 什么时候编写注释
修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要及时删除。

### 内容要求
注释格式尽量统一，使用“/** …… */”形式的注释。

注释语言不统一，影响程序易读性和外观排版。建议多使用中文，不是参与项目的所有人员都能流利的使用英语，出于对维护人员的考虑，建议使用中文。

注释的内容要清楚、明了，含义准确，防止注释二义性。错误的注释不但无益反而有害。

尽量不要使用长句子描述，长句的句法结构过于复杂，不利于维护人员理解。要将长句子分解成多个短句来描述。

避免在注释中使用缩写，特别是非常用缩写。在使用缩写时或之前，应对缩写进行必要的说明。

### 注释的合理位置
注释应与其描述的代码相近，对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置，不可放在下面。

除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。

类型的声明(包括类、接口、枚举等)，必须加以注释。对类型的注释应放在其上方相邻位置，不可放在下面；对枚举的每个枚举值的注释放在此枚举的右方。

注释与所描述内容进行同样的缩排，让程序排版整齐，并方便注释的阅读与理解。

### 注释颗料度要求
所有的类、接口、枚举必须编写注释。

类的函数、属性、变量必须写注释。

函数的所有入参、返回值都必须写注释。

所有的分支语句(```if```、```else```、```switch``` 等)、循环语句（```for```、```while```、```do...while``` 等）必须编写注释。

```switch``` 的每个 ```case``` 分枝都必须写注释。注释写在 ```case``` 语句右端。

对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

在顺序执行的程序中，每隔3—5行语句，应当加一个注释，注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。

注释与其上面的代码用空行隔开。

## 注释分类
### 文件头
文件头注释是标识、是旗帜、是团魂。代表了开发团队对所写代码的负责精神。文件头统一使用如下注释：

```typescript
/*
 * *********************************************************************************************************************
 *
 *          !!
 *        .F88X
 *        X8888Y
 *      .}888888N;
 *        i888888N;        .:!              .I$WI:
 *          R888888I      .'N88~            i8}+8Y&8"l8i$8>8W~'>W8}8]KW+8IIN"8&
 *          .R888888I    .;N8888~          .X8'  "8I.!,/8"  !%NY8`"8I8~~8>,88I
 *            +888888N;  .8888888Y                                  "&&8Y.}8,
 *            ./888888N;  .R888888Y        .'}~    .>}'.`+>  i}!    "i'  +/'  .'i~  !11,.:">,  .~]!  .i}i
 *              ~888888%:  .I888888l      .]88~`1/iY88Ii+1'.R$8$8]"888888888>  Y8$  W8E  X8E  W8888'188Il}Y88$*
 *              18888888    E8888881    .]W%8$`R8X'&8%++N8i,8N%N8+l8%`  .}8N:.R$RE%N88N%N$K$R  188,FE$8%~Y88I
 *            .E888888I  .i8888888'      .:$8I;88+`E8R:/8N,.>881.`$8E/1/]N8X.Y8N`"KF&&FK!'88*."88K./$88%RN888+~
 *            8888888I  .,N888888~        ~88i"8W,!N8*.I88.}888%F,i$88"F88"  888:E8X.>88!i88>`888*.}Fl1]*}1YKi'
 *          i888888N'      I888Y          ]88;/EX*IFKFK88X  K8R  .l8W  88Y  ~88}'88E&%8W.X8N``]88!.$8K  .:W8I
 *        .i888888N;        I8Y          .&8$  .X88!  i881.:%888>I88  ;88]  +88+.';;;;:.Y88X  18N.,88l  .+88/
 *      .:R888888I
 *      .&888888I                                          Copyright (c) 2016-2020.  博锐尚格科技股份有限公司
 *        ~8888'
 *        .!88~                                                                     All rights reserved.
 *
 * *********************************************************************************************************************
 */
```

### 类与接口注释
**格式：**
```typescript
/**
 * summary
 *
 * @author author-text
 */
```

**说明：**
* *summary*

&emsp;&emsp;    简要说明。

* *author-text*

&emsp;&emsp;    作者描述。描述要包含作者的姓名与邮箱地址。

**风格：**
* 作者与简要说明隔一空行；
* @author 标识与作者间用 ```tab``` 键完成定位；
* 多个作者，使用多个 @author 标记，每个作者占一行；
* 姓名与㞨箱地址间隔一个空格；
* 邮箱地址使用”<>“括起来。
* 多个作者间不能有空行；

**示例：**

* 类注释
```typescript
/**
 * 对象
 *
 * @author 郝洁 <haojie@persagy.com>
 * @author 韩耀龙 <han_yao_long@163.com>
 */
export class SObject {}
```

* 接口注释
```typescript
/**
 *  命令日志接口
 *
 * @author 韩耀龙 <han_yao_long@163.com>
 * */
export interface SICommandLog {}
```

### 函数
**格式：**
```typescript
/**
  * summary
  *
  * @param parameter-name   description
  * @return return-description
  */
```
**说明：**
* *summary*

&emsp;&emsp;    简要说明。

* *parameter-name*

&emsp;&emsp;    参数名

* *description*

&emsp;&emsp;    参数描述

* *return-description*

&emsp;&emsp;    返回值描述

**风格：**
* 入参与出参与简要说明隔一空行；
* 入参的顺序要与函数的定义保持一致；
* 入参以有多个，每个入参单独占一行；
* ```@param``` 标识与参数名间用 ```tab``` 键完成定位；
* 多个参数数描述使用 ```tab``` 键完成对齐排版；
* 一个入参有多种类型时，每种类型的描述使用 “|” 分开。注意描述与“|”留至少一个空格。
* 入参与返回值描述与简要描述之间隔一空行；
* 函数最多只能有一个 ```@return``` 标识。如果函数类的返回类型为 ```void``` ，则没有 @return 标识；
* ```@return``` 标识不能排在 @param 标识前边；
* `@return` 标识与返回值描述间用 ```tab``` 键完成定位；

**示例：**

* 有入参与返回值
```typescript{5-7}
export class SRect {
    /**
     * 生成平移矩形
     *
     * @param dx    x 轴位移
     * @param dy    y 轴位移
     * @return 移动后的矩形
     */
    translated(dx: number, dy: number): SRect {
        return new SRect(this.x + dx, this.y + dy, this.width, this.height);
    }
}
```

* 多类型入参
```typescript{5-8}
export class SRect {
    /**
     * 构造函数
     *
     * @param x         x 轴坐标 | 左上角坐标
     * @param y         y 轴坐标 | 右下角坐标 | 大小
     * @param width     宽度
     * @param height    高度
     */
    constructor(
        x?: number | SPoint,
        y?: number | SPoint | SSize,
        width?: number,
        height?: number
    ) {}
}
```

* 无返回值
```typescript{5,6}
export class SRect {
   /**
     * 平移矩形
     *
     * @param dx    x 轴位移
     * @param dy    y 轴位移
     */
    translate(dx: number, dy: number): void {
        this.x += dx;
        this.y += dy;
    }
}
```

* 只有返回值
```typescript{5}
export class SRect {
    /**
     * 计算中心点
     *
     * @return 中心点坐标
     */
    center(): SPoint {
        return new SPoint(
            this.x + this.width / 2.0,
            this.y + this.height / 2.0
        );
    }
}
```

### 属性
**格式：**
```typescript
/** summary */
```
**说明：**
* *summary*

&emsp;&emsp;    简要说明。

**风格：**
* “/**”、简要说明与“*/”在同一行；
* "/**"、简要说明与“*/”之间隔一个空格；
* 域属性的注释写在域；
* 没有域的属性，写在 ```get``` 操作上；
* 没有 ```get``` 操作，写在 ```set``` 操作上；

**示例：**
```typescript{2,5,13}
export class SRect {
    /** 左上角坐标 */
    leftTop: SPoint;

    /** 矩形的 x 轴坐标 */
    get x(): number {
        return this.leftTop.x;
    }
    set x(value: number) {
        this.leftTop.x = value;
    }

    /** 旋转中心点 */
    private _org = new SPoint():
    get org(): number {
        return this._org;
    }
    set org(value: number) {
        this._org = value;
    }
}
```

### 枚举
**格式：**
* 枚举类注释
```typescript
/**
 * class-summary
 *
 * @author  author-text
 */
```
* 枚举值注释
```typescript
/** value-summary */
```

**说明：**
* *summary*

&emsp;&emsp;    简要说明。

* *author-text*

&emsp;&emsp;    作者描述。描述要包含作者的姓名与邮箱地址。

* *value-summary*

&emsp;&emsp;    枚举值的简要说明。

**风格：**
* 枚举类注释见[类与接口注释](#类与接口注释);
* “/**”、枚举值简要说明与“*/”在同一行；
* "/**"、枚举值简要说明与“*/”之间隔一个空格；
* 枚举值注释写在枚举值上；

**示例：**
```typescript{1-5,7,9,11}
/**
 * 手势状态
 *
 * @author 韩耀龙 <han_yao_long@163.com>
 */
export enum STouchState {
    None,       /** 标准状态 */
    Move,       /** 移动状态 */
    Zoom,       /** 缩放状态 */
}
```

### 内部注释
待定
```typescript

```
