SAP OpenUI5项目中的JSDoc注释规范指南

SAP OpenUI5项目中的JSDoc注释规范指南

openui5 OpenUI5 lets you build enterprise-ready web applications, responsive to all devices, running on almost any browser of your choice. 项目地址: https://gitcode.com/gh_mirrors/op/openui5

前言

在SAP OpenUI5项目中，良好的代码注释是保证代码可维护性和可读性的关键因素。JSDoc作为一种标准的JavaScript文档注释规范，能够帮助开发者生成清晰、规范的API文档。本文将详细介绍在OpenUI5项目中如何使用JSDoc进行代码注释。

JSDoc基础概念

JSDoc是一种基于注释的文档生成工具，它通过解析JavaScript代码中的特殊注释块来生成API文档。在OpenUI5项目中，JSDoc注释会被转换为Demo Kit中的API参考文档。

基本注释原则

1. 类构造器注释：使用@class标记类，并添加@author、@since等基本信息
2. 继承关系：子类中使用@extends标记继承关系
3. 可见性标记：至少为public和protected方法添加@public或@protected标记
4. 参数文档：使用{类型} [可选参数名]格式
5. 静态工具类：使用@namespace标记

注释内容规范

注释内容结构

1. 摘要语句：首句作为摘要，会用于工具提示和API参考中的概要
2. 背景信息：理解对象所需的背景知识
3. 特殊考虑：适用的特殊注意事项
4. 详细描述：不重复API名称或摘要的额外信息

写作建议

1. 摘要语句：

   • 以句号结尾（JSDoc以此识别首句）
   • 避免使用"e.g."等缩写，使用完整表达
   • 避免使用"这个类"、"这个方法"等冗余表达

2. 对象描述：

   • 使用名词短语（如："导航的基础类"）
   • 避免感叹号
   • 正确拼写缩写（如ID、JSON、URL）

3. 方法描述：

   • 直接以第三人称动词开头：
     • 构造器：Constructs
     • 布尔值方法：Indicates (whether)
     • Getter方法：Gets
     • Setter方法：Sets
     • 其他方法：Adds/Removes/Creates等

标签使用指南

内联标签和HTML标签

1. 内联标签：使用{@tagname comment}格式

   • {@link}：创建API参考内部链接
   • 示例：{@link sap.ui.generic.app.navigation.service.NavError Error}

2. HTML标签：

   • <code>：标记技术实体
   • <pre>：代码示例
   • <ul>/<ol>：列表
   • <strong>/<b>：加粗
   • <i>：斜体

块级标签

块级标签必须放在描述后的标签区域，常见标签包括：

| 标签 | 用途 | 示例 | |------|------|------| | @param | 参数说明 | @param {string} statement SQL语句 | | @returns | 返回值 | @returns {string} 处理后的字符串 | | @throws | 异常说明 | @throws {Error} 参数无效时抛出 | | @author | 作者 | @author 张三 | | @since | 引入版本 | @since 1.30 | | @deprecated | 弃用说明 | @deprecated 自1.28版本起，由{@link NewClass}替代 | | @experimental | 实验性API | @experimental 自1.56版本起 | | @example | 代码示例 | @example var id = myjob.schedules.add(...) |

可见性级别

OpenUI5中定义了API的可见性级别，影响API的使用范围和兼容性承诺：

| 标签 | 描述 | 兼容性要求 | 应用可用 | |------|------|-----------|----------| | @public | 公开API，供应用开发者使用 | 是 | 是 | | @protected | 受限API，仅限框架开发 | 是 | 否 | | @private | 私有API，不显示在文档中 | 否 | 否 | | @ui5-restricted | 特定框架开发者可用 | 否 | 否 |

注意：

1. @ui5-restricted前必须加@private
2. 可指定允许使用的包：@ui5-restricted sap.ui.core, sap.m
3. 多个可见性标签时，最后一个生效

最佳实践

1. 参数顺序：保持参数文档的顺序一致
2. 链接使用：
   • 内部链接使用{@link}
   • 外部链接需符合法律要求
3. 版本说明：
   • 新功能使用@since
   • 弃用功能使用@deprecated
   • 实验性功能使用@experimental
4. 代码示例：
   • 使用@example或<pre>标签
   • 可添加<caption>作为标题

通过遵循这些JSDoc规范，可以确保OpenUI5项目的代码文档保持一致性、清晰性和实用性，为开发者提供良好的API参考体验。

openui5 OpenUI5 lets you build enterprise-ready web applications, responsive to all devices, running on almost any browser of your choice. 项目地址: https://gitcode.com/gh_mirrors/op/openui5