|
@@ -0,0 +1,299 @@
|
|
|
+# 注释
|
|
|
+::: details 目录
|
|
|
+[[toc]]
|
|
|
+:::
|
|
|
+
|
|
|
+多行注释规则:
|
|
|
+* 注释以“/**”开始,以“*/”结尾。
|
|
|
+* "/**"与“*/”各占一行;
|
|
|
+* 每一行注释都以“*”打头,在“*”与注释内容之间间隔一个空格;
|
|
|
+
|
|
|
+## 文件头
|
|
|
+文件头注释是标识、是旗帜、是团魂。代表了开发团队对所写代码的负责精神。文件头统一使用如下注释:
|
|
|
+
|
|
|
+```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*
|
|
|
+
|
|
|
+   简要说明。
|
|
|
+
|
|
|
+* *author-text*
|
|
|
+
|
|
|
+   作者描述。描述要包含作者的姓名与邮箱地址。
|
|
|
+
|
|
|
+**风格:**
|
|
|
+* 作者与简要说明隔一空行;
|
|
|
+* @author 标识与作者间用 tab 键完成定位;
|
|
|
+* 多个作者,使用多个 @author 标记,每个作者占一行;
|
|
|
+* 姓名与㞨箱地址间隔一个空格;
|
|
|
+* 邮箱地址使用”<>“括起来。
|
|
|
+* 多个作者间不能有空行;
|
|
|
+
|
|
|
+**示例:**
|
|
|
+
|
|
|
+* 类注释
|
|
|
+```typescript
|
|
|
+/**
|
|
|
+ * 对象
|
|
|
+ *
|
|
|
+ * @author 庞利祥 <sybotan@126.com>
|
|
|
+ * @author 庞凌峰 <sandy@126.com>
|
|
|
+ */
|
|
|
+export class SObject {}
|
|
|
+```
|
|
|
+
|
|
|
+* 接口注释
|
|
|
+```typescript
|
|
|
+/**
|
|
|
+ * 命令日志接口
|
|
|
+ *
|
|
|
+ * @author 庞利祥 <sybotan@126.com>
|
|
|
+ * */
|
|
|
+export interface SCommandLog {}
|
|
|
+```
|
|
|
+
|
|
|
+## 函数
|
|
|
+**格式:**
|
|
|
+```typescript
|
|
|
+/**
|
|
|
+ * summary
|
|
|
+ *
|
|
|
+ * @param parameter-name description
|
|
|
+ * @return return-description
|
|
|
+ */
|
|
|
+```
|
|
|
+**说明:**
|
|
|
+* *summary*
|
|
|
+
|
|
|
+   简要说明。
|
|
|
+
|
|
|
+* *parameter-name*
|
|
|
+
|
|
|
+   参数名
|
|
|
+
|
|
|
+* *description*
|
|
|
+
|
|
|
+   参数描述
|
|
|
+
|
|
|
+* *return-description*
|
|
|
+
|
|
|
+   返回值描述
|
|
|
+
|
|
|
+**风格:**
|
|
|
+* 入参与出参与简要说明隔一空行;
|
|
|
+* 入参的顺序要与函数的定义保持一致;
|
|
|
+* 入参以有多个,每个入参单独占一行;
|
|
|
+* @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*
|
|
|
+
|
|
|
+   简要说明。
|
|
|
+
|
|
|
+**风格:**
|
|
|
+* “/**”、简要说明与“*/”在同一行;
|
|
|
+* "/**"、简要说明与“*/”之间隔一个空格;
|
|
|
+* 域属性的注释写在域;
|
|
|
+* 没有域的属性,写在 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*
|
|
|
+
|
|
|
+   简要说明。
|
|
|
+
|
|
|
+* *author-text*
|
|
|
+
|
|
|
+   作者描述。描述要包含作者的姓名与邮箱地址。
|
|
|
+
|
|
|
+* *value-summary*
|
|
|
+
|
|
|
+   枚举值的简要说明。
|
|
|
+
|
|
|
+**风格:**
|
|
|
+* 枚举类注释见[类与接口注释](#类与接口注释);
|
|
|
+* “/**”、枚举值简要说明与“*/”在同一行;
|
|
|
+* "/**"、枚举值简要说明与“*/”之间隔一个空格;
|
|
|
+* 枚举值注释写在枚举值上;
|
|
|
+
|
|
|
+**示例:**
|
|
|
+```typescript{1-5,7,9,11}
|
|
|
+/**
|
|
|
+ * 手势状态
|
|
|
+ *
|
|
|
+ * @author 庞利祥 <sybotan@126.com>
|
|
|
+ */
|
|
|
+export enum STouchState {
|
|
|
+ /** 标准状态 */
|
|
|
+ None,
|
|
|
+ /** 移动状态 */
|
|
|
+ Move,
|
|
|
+ /** 缩放状态 */
|
|
|
+ Zoom,
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## 内部注释
|
|
|
+待定
|
|
|
+```typescript
|
|
|
+
|
|
|
+```
|