你会了吗 HarmonyOS Next 项目级别的注释规范

简介: 你会了吗 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文档
目录
相关文章
|
2月前
|
移动开发 前端开发 JavaScript
鸿蒙NEXT时代你所不知道的全平台跨端框架:CMP、Kuikly、Lynx、uni-app x等
本篇基于当前各大活跃的跨端框架的现状,对比当前它们的情况和未来的可能,帮助你在选择框架时更好理解它们的特点和差异。
294 0
|
12天前
|
存储 缓存 5G
鸿蒙 HarmonyOS NEXT端云一体化开发-云存储篇
本文介绍用户登录后获取昵称、头像的方法,包括通过云端API和AppStorage两种方式,并实现上传头像至云存储及更新用户信息。同时解决图片缓存问题,添加上传进度提示,支持自动登录判断,提升用户体验。
73 0
|
12天前
|
存储 负载均衡 数据库
鸿蒙 HarmonyOS NEXT端云一体化开发-云函数篇
本文介绍基于华为AGC的端云一体化开发流程,涵盖项目创建、云函数开通、应用配置及DevEco集成。重点讲解云函数的编写、部署、调用与传参,并涉及环境变量设置、负载均衡、重试机制与熔断策略等高阶特性,助力开发者高效构建稳定云端服务。
106 0
鸿蒙 HarmonyOS NEXT端云一体化开发-云函数篇
|
12天前
|
存储 JSON 数据建模
鸿蒙 HarmonyOS NEXT端云一体化开发-云数据库篇
云数据库采用存储区、对象类型、对象三级结构,支持灵活的数据建模与权限管理,可通过AGC平台或本地项目初始化,实现数据的增删改查及端侧高效调用。
42 0
|
12天前
|
存储 开发者 容器
鸿蒙 HarmonyOS NEXT星河版APP应用开发-ArkTS面向对象及组件化UI开发使用实例
本文介绍了ArkTS语言中的Class类、泛型、接口、模块化、自定义组件及状态管理等核心概念,并结合代码示例讲解了对象属性、构造方法、继承、静态成员、访问修饰符等内容,同时涵盖了路由管理、生命周期和Stage模型等应用开发关键知识点。
128 0
鸿蒙 HarmonyOS NEXT星河版APP应用开发-ArkTS面向对象及组件化UI开发使用实例
|
12天前
鸿蒙 HarmonyOS NEXT星河版APP应用开发-阶段三
本文介绍了UI开发中的样式复用与组件构建技术,涵盖@Extend、@Styles和@Builder的使用方法,并通过Swiper轮播、Scroll滚动、Tabs导航等常用组件实现典型界面效果,结合生肖抽卡、小米轮播、回顶按钮等案例,展示实际应用技巧。
56 0
|
12天前
鸿蒙 HarmonyOS NEXT星河版APP应用开发-阶段二
本文介绍鸿蒙应用界面开发中的弹性布局(Flex)、绝对定位、层叠布局及ArkTS语法进阶,涵盖字符串拼接、类型转换、数组操作、条件与循环语句,并结合B站视频卡、支付宝首页等案例,深入讲解点击事件、状态管理与界面交互功能。
63 0
鸿蒙 HarmonyOS NEXT星河版APP应用开发-阶段二
|
1月前
|
移动开发 网络协议 小程序
鸿蒙NEXT即时通讯/IM系统RinbowTalk v2.4版发布,基于MobileIMSDK框架、ArkTS编写
RainbowTalk是一套基于开源即时通讯讯IM框架 MobileIMSDK 的产品级鸿蒙NEXT端IM系统。纯ArkTS编写、全新开发,没有套壳、也没走捷径,每一行代码都够“纯血”。与姊妹产品RainbowChat和RainbowChat-Web 技术同源,历经考验。
83 1
|
2月前
|
缓存 移动开发 网络协议
纯血鸿蒙NEXT即时通讯/IM系统:RinbowTalk正式发布,全源码、纯ArkTS编写
RainbowTalk是一套基于MobileIMSDK的产品级鸿蒙NEXT端IM系统,目前已正式发布。纯ArkTS、从零编写,无套壳、没走捷径,每一行代码都够“纯”(详见:《RainbowTalk详细介绍》)。 MobileIMSDK是一整套开源IM即时通讯框架,历经10年,超轻量级、高度提炼,一套API优雅支持 UDP 、TCP 、WebSocket 三种协议,支持 iOS、Android、H5、标准Java、小程序、Uniapp、鸿蒙NEXT,服务端基于Netty编写。
201 1
|
编译器
鸿蒙NEXT-鸿蒙三层架构搭建,嵌入HMRouter,实现便捷跳转,新手攻略。(2/3)
本文介绍在三层架构中实现模块依赖的步骤。首先在产品定制层(features)的oh-package.json5文件中导入共享包依赖,如"basic":"file:../../commons/basic"。然后在产品层(products)的配置文件中同时导入公共能力层和产品定制层的依赖,示例展示了如何添加"basic"和"my"两个依赖项。通过这些配置,三层架构的各模块之间建立了完整的依赖关系。
139 0
鸿蒙NEXT-鸿蒙三层架构搭建,嵌入HMRouter,实现便捷跳转,新手攻略。(2/3)