HarmonyOS Next 如何优雅的编写注释

程序员箴言

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

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

前言

随着 HarmonyOS NEXT 的发展加快，不少的公司已经陆续加大了资源来开发软件项目。那么伴随项目的发展，项目团队也需要按照一定

的规范来编写项目注释或者代码的说明文档。

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

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

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

Person.ets

/**
 * 一个工具人类
 *
 * @since 11
 */
export class Person {
  /**
   * 年龄
   */
  age: number = 18;

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

DevEco Studio 自带的语法提示

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

@constant @class @function @interface @enmu 等

类

枚举

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

常见代码提示修饰符

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

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

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
2. 生成 ArkTSDoc 文档