HarmonyOS Next 如何优雅的编写注释

2024-11-09 08:07:40

118次阅读

0个评论

HarmonyOS Next 如何优雅的编写注释

程序员箴言

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

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

前言

随着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 开快速生成

PixPin_2024-09-29_01-31-34

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

PixPin_2024-09-29_01-33-28

@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	生成的值说明。