persagy-web-doc/docs/standard/typescript/comment.md

注释

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

多行注释规则：

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

文件头

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

/*
 * *********************************************************************************************************************
 *
 *          !!
 *        .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.
 *
 * *********************************************************************************************************************
 */

类与接口注释

格式：

/**
 * 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 {} ```

函数

格式：

/**
  * 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 ); } } ```

属性

格式：

/** summary */

说明：

• summary

   简要说明。

风格：

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

示例：

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

   枚举值的简要说明。

风格：

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

示例：

/**
 * 手势状态
 *
 * @author  庞利祥 <sybotan@126.com>
 */
export enum STouchState {
    /** 标准状态 */
    None,
    /** 移动状态 */
    Move,
    /** 缩放状态 */
    Zoom,
}

内部注释

待定