HarmonyOS 鸿蒙Next 项目级别的注释规范

HarmonyOS Next 项目级别的注释规范

程序员箴言

我最讨厌世界上的两种人：

1. 第一种是不写注释的人
2. 第二种是让我写注释的人

前言

随着HarmonyOS NEXT的发展加快，不少的公司已经陆续加大了资源来开发软件项目。那么伴随项目的发展，项目团队也需要按照一定的规范来编写项目注释或者代码的说明文档。

我认为编写项目注释或者代码的说明文档最小的代价就是 直接通过编写注释的方式来实现代码的使用文档。

目前主流的IDE都会支持 jsDoc 或者 TypeDoc。 我们按照规定的格式编写代码注释，便能获得以下好处：

当我们想要调用 全局函数 px2vp时，提示工具会很清晰的给我展现出相关的使用说明。另外，如果是编写一个工具类库，还能基于相关工具生成好看的说明文档。

/**
 * 一个工具人类
 *
 * [@since](/user/since) 11
 */
export class Person {
  /**
   * 年龄
   */
  age: number = 18

  /**
   *
   * 计算两个年龄相加的和
   * [@param](/user/param) {number} n1 年龄1
   * [@param](/user/param) {number} n2 年龄2
   * [@returns](/user/returns) {number} 总年龄
   */
  calcAge(n1: number, n2: number) {
    return n1 + n2
  }
}

DevEco Studio 自带的语法提示

jsDoc提供了对 常量、类、函数、接口、枚举等的修饰符，一般情况下不需要主动添加，因为 DevEco Studio 可以自动识别

类

枚举

并且，在你引入代码提示的时候，也可以直观的观察这里来判断它是什么类型

常见代码提示修饰符

如图，如果我们想要实现上图右侧的一些语法提示功能，那么就需要自己编写合适的代码提示修饰符了

通过编写一个类来演示，首先我们提供以下基本结构

export class Person {
  age: number = 18

  protected static async calcAge4(n1: number, n2: number) {
    return n1 + n2
  }

  calcAge1(n1: number, n2: number) {
    return n1 + n2
  }

  async calcAge2(n1: number, n2: number) {
    return n1 + n2
  }

  protected async calcAge3(n1: number, n2: number) {
    return n1 + n2
  }
}

快速生成特定的注释

如我们想要给 Person添加一些备注说明，那么我们不能使用以下这种注释

// 这个单行注释不行

/* 这个普通的多行注释也不行 */

我们只能使用这种

/**
*  这个是OK的
*/

你可以在想要修饰的代码上方 输入 /** + tab 开快速生成

在带有参数的函数上方，它会自动添加参数的修饰符，包括返回值

@param 和 @returns

@param 修饰函数的形参

@returns 修饰返回值

@async

@async 修饰 异步函数

@public

@public 公开

@protected 受保护

@private 私有

@static

其他的jsDoc规范的修饰符总览

DevEco Studio 支持自定义修饰符

DevEco Studio 是支持自定义修饰符的，比如

虽然是可以随便自己设定，但是为了团队开发保持一致，还是建议按照一定的规范来编写。如 遵循 上述jsDoc的一些规范

DevEco Studio 快速生成说明文档

DevEco Studio NEXT Beta1(5.0.3.814)

• 当前支持对工程或目录下.ets/.ts/.js/.md格式文件生成ArkTSDoc文档。
• 文件中export的变量、方法、接口、类等将生成相应的ArkTSDoc文档，未export的对象不支持生成。
• 若选择对工程/目录整体导出ArkTSDoc文档，生成后的ArkTSDoc文档目录和原目录结构一致。

参考链接

1. [@use JSDoc](https://jsdoc.app/)
2. 生成ArkTSDoc文档