HarmonyOS Next 如何优雅的编写注释

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 规范的修饰符总览

修饰符	含义
@abstract	表示一个抽象的成员，不能被直接实例化。
@access	用于指定成员的访问级别。
@alias	定义一个别名。
@async	表示一个异步函数。
@augments	指示一个类继承自另一个类。
@author	作者信息。
@borrows	表示从另一个模块借用的函数或属性。
@callback	表示一个回调函数。
@class	用于定义一个类。
@classdesc	类的描述。
@constant	表示一个常量。
@constructs	指示一个函数是构造函数。
@copyright	版权信息。
@default	默认值。
@deprecated	表示已弃用的成员。
@description	描述信息。
@enum	定义一个枚举。
@event	表示一个事件。
@example	示例代码。
@exports	用于指定要导出的成员。
@external	表示外部模块的成员。
@file	文件信息。
@fires	表示触发的事件。
@function	定义一个函数。
@generator	表示一个生成器函数。
@global	表示全局成员。
@hideconstructor	隐藏构造函数。
@ignore	表示忽略的部分。
@implements	表示实现的接口。
@inheritdoc	继承文档说明。
@inner	内部成员。
@instance	实例成员。
@interface	定义一个接口。
@kind	类型种类。
@lends	将属性借给另一个对象。
@license	许可证信息。
@listens	表示监听的事件。
@member	成员。
@memberof	属于某个对象的成员。
@mixes	混合多个类的特性。
@mixin	定义一个混入。
@module	定义一个模块。
@name	名称。
@namespace	命名空间。
@override	表示重写的成员。
@package	包信息。
@param	函数参数说明。
@private	私有成员。
@property	属性。
@protected	受保护的成员。
@public	公共成员。
@readonly	只读属性。
@requires	表示依赖的模块。
@returns	函数返回值说明。
@see	参考信息。
@since	从某个版本开始。
@static	静态成员。
@summary	摘要信息。
@this	当前对象。
@throws	抛出的异常说明。
@todo	待办事项。
@tutorial	教程信息。
@type	类型说明。
@typedef	类型定义。
@variation	变化情况。
@version	版本信息。
@yields	生成的值说明。

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 文档