代码拉取完成,页面将自动刷新
同步操作将从 openharmony_docs/standards_template 强制同步,此操作会覆盖自 Fork 仓库以来所做的任何修改,且无法恢复!!!
确定后同步将在后台操作,完成时将刷新页面,请耐心等待。
要求项 | 内容要求 | 可选/必选 | 作者自检 | 资料人员 | 测试人员 |
---|---|---|---|---|---|
A.1 | 通用标准 | ||||
A.1.1 | 【法务合规】接口设计和描述要合规,不能产生抄袭或者合规性性风险。比如描述和友商高度一致,或使用友商特有的概念。 | 必选 | A:满足 | 关注 | 关注 |
A.1.2 | 【内容合规】需要针对开发者可感知和使用的能力进行描述,不能对内部实现进行介绍。 | 必选 | A:满足 | 关注 | 关注 |
A.1.3 | 【描述一致-1】描述和实现需要保持一致,不能有误、前后矛盾或有歧义。 | 必选 | A:满足 | 非关注要素 | 重点关注 |
A.1.4 | 【描述一致-2】定义的名称(模块名、文件名、常量、函数等)和描述内容需要匹配。 | 必选 | A:满足 | 非关注要素 | 重点关注 |
A.1.5 | 【术语统一】描述如果涉及专业术语或概念,需要给出术语全称或简要说明、特定的上下文信息(可建立到对应说明的链接)。 | 必选 | A:满足 | 关注 | 关注 |
A.1.6 | 【版本格式】 @since后接引入软件的版本号。 @version后接该头文件自身版本号。 | 必选 | A:满足 | 关注 | 关注 |
A.1.7 | 【分段格式】详细描述中,如果有多个段落,每段必须以“\n”结束。 | 条件必选 | A:满足 | 关注 | 关注 |
A.1.8 | 【参考详尽】如果存在必要参考信息,如模块依赖、复杂参数返回值等,则需要进行说明或建立到对应信息的链接。 | 条件必选 | A:满足 | 关注 | 关注 |
A.2 | Module的说明 | ||||
A.2.1 | 【写作格式】 @addtogroup后接模块名。如果需要将头文件中具体的函数划分到该模块中,则在具体函数前使@addtogroup标记,并使用“@{”、“@}”将该函数包起来。 | 必选 | A:满足 | 关注 | 关注 |
A.2.2 | 【描述清晰-1】简要描述需要通过一句话明确模块的具体功能,描述不能宽泛或模糊。 | 必选 | A:满足 | 关注 | 关注 |
A.2.3 | 【描述清晰-2】详细描述需要展开说明该模块的主要功能,以及所含接口的主要开发场景。 | 必选 | A:满足 | 关注 | 关注 |
A.2.4 | 【约束清晰】如果存在环境要求、依赖条件或约束限制,则需要申明。 | 条件必选 | A:满足 | 关注 | 关注 |
A.3 | 头文件的说明 | ||||
A.3.1 | 【写作格式】 @file 文件名,以空格隔开,文件名需要和实际文件命名保持一致。 | 必选 | A:满足 | 关注 | 关注 |
A.3.2 | 【描述清晰-1】简要描述需要通过一句话明确该头文件的具体作用,描述不能宽泛或模糊。可以提供示例,让描述更加具体。 | 必选 | A:满足 | 关注 | 关注 |
A.3.3 | 【描述清晰-2】详细描述需要展开说明整个文件的用途和使用场景:能做什么、什么情况下使用或在什么时候使用。 | 条件必选 | A:满足 | 关注 | 关注 |
A.3.4 | 【约束清晰】如果针对此文件有使用建议、约束限制或者其他关键信息(比如线程安全、权限等),则需要向开发者申明。 | 条件必选 | A:满足 | 关注 | 关注 |
A.4 | 宏定义/变量/常量的说明 | ||||
A.4.1 | 【描述清晰】需要明确宏定义/变量/常量的含义、使用场景或使用建议、约束限制等信息。如果为变量,还需要说明变量的取值范围,以及取到边界值、非法值的后果。 | 必选 | A:满足 | 关注 | 关注 |
A.4.2 | 【描述一致】宏定义/变量/常量名和描述需要匹配。 | 必选 | A:满足 | 关注 | 关注 |
A.5 | 枚举的说明 | ||||
A.5.1 | 【枚举描述清晰】需要明确枚举的作用、使用场景和使用建议。 | 必选 | A:满足 | 关注 | 关注 |
A.5.2 | 【枚举值描述清晰】需要明确每个枚举值的含义、使用场景或使用建议、约束限制等信息。 | 必选 | A:满足 | 关注 | 关注 |
A.6 | 结构体、联合体的说明 | ||||
A.6.1 | 【描述清晰-1】一句话描述该结构体或联合体的作用。 | 必选 | A:满足 | 关注 | 关注 |
A.6.2 | 【描述清晰-2】详细描述该结构体或联合体的作用、使用场景和建议等。 | 条件必选 | A:满足 | 关注 | 关注 |
A.6.2 | 【成员定义清晰】需要明确各个成员的含义。 | 必选 | A:满足 | 关注 | 关注 |
A.7 | 函数的说明 | ||||
A.7.1 | 【描述清晰-1】简要描述需要通过一句话明确体现函数的具体作用,描述不能宽泛或模糊。可以提供示例,让描述更加具体。 | 必选 | A:满足 | 关注 | 关注 |
A.7.2 | 【描述清晰-2】详细描述需要展开说明函数的作用、使用场景和使用建议,不限于:性能约束、用法、内存约定、算法实现、可重入的要求等等。 | 必选 | A:满足 | 关注 | 关注 |
A.7.3 | 【函数区分差别】如果存在类似或相关的函数,一定要能明确体现出函数之间作用和场景的差别和联系,为开发者提供选择调用接口的依据。 | 条件必选 | A:满足 | 关注 | 重点关注 |
A.7.4 | 【提供代码示例】对于关键重要的函数,应该结合实际场景提供代码示例,方便开发者快速上手。 | 条件必选 | A:满足 | 关注 | 重点关注 |
A.7.5 | 【示例代码可运行】示例代码准确,且能够在工程中运行。 | 条件必选 | A:满足 | 非关注要素 | 重点关注 |
A.7.6 | 【调用明确条件】如果涉及内存释放/状态迁移等重要操作的函数,需要明确在何种状态下可以调用。 | 条件必选 | A:满足 | 关注 | 重点关注 |
A.7.7 | 【写作格式】 当存在与该函数相关联的函数时(功能相近或者存在关系),可以通过@see建立到参考函数的链接。 格式:@see 函数名,以空格隔开,一个函数使用一个@see标记。 | 条件必选 | A:满足 | 关注 | 关注 |
A.8 | 参数的说明 | ||||
A.8.1 | 【写作格式】 @param 参数名 参数描述,以空格隔开,一个参数使用一个@param标记。 | 必选 | A:满足 | 关注 | 关注 |
A.8.2 | 【入参合规】 入参设计要合理,规避仿冒等风险。 | 必选 | A:满足 | 关注 | 关注 |
A.8.3 | 【参数正确】 参数名和函数实现一致,不允许写作有误,且不能有遗漏。 | 必选 | A:满足 | 关注 | 关注 |
A.8.4 | 【参数含义清晰-1】 需要明确参数的含义、在此函数中的作用,使开发者清楚该如何入参。 | 必选 | A:满足 | 关注 | 关注 |
A.8.5 | 【参数含义清晰-2】 参数说明需要明确、直白、具体。 | 必选 | A:满足 | 关注 | 关注 |
A.8.6 | 【参数取值说明-1】如果存在参数设置方面的建议值,请描述。 | 条件必选 | A:满足 | 关注 | 关注 |
A.8.7 | 【参数取值说明-2】如果为整型、浮点型、字符型参数,需要说明参数的取值范围、取值建议、边界值、非法取值后果等信息。如果涉及单位,还需要明确取值单位。 | 条件必选 | A:满足 | 关注 | 关注 |
A.8.8 | 【参数取值说明-3】如果为布尔型参数,需要对两种取值进行说明,并声明默认值。 | 条件必选 | A:满足 | 关注 | 关注 |
A.9 | 返回值的说明 | ||||
A.9.1 | 【写作格式】 @return 函数的返回描述。 | 必选 | A:满足 | 关注 | 关注 |
A.9.3 | 【单位明确】如果涉及单位,则需要明确返回值单位。 | 条件必选 | A:满足 | 关注 | 关注 |
A.9.4 | 【含义解释清晰】如果存在特定含义的返回值,则需明确具体的含义。 | 条件必选 | A:满足 | 关注 | 关注 |
A.10 | 类的说明(C++) | ||||
A.10.1 | 【描述清晰-1】需要明确类的作用、使用场景和使用建议。 | 必选 | A:满足 | 关注 | 关注 |
A.10.2 | 【描述清晰-2】详细描述该类的主要功能、使用场景和使用建议 | 条件必选 | A:满足 | 关注 | 关注 |
A.10.3 | 【写作格式】 当存在与该类或接口相关联的类时,可以通过@see建立到参考类的链接。 格式:@see 函数名,以空格隔开,一个函数使用一个@see标记。 | 条件必选 | A:满足 | 关注 | 关注 |
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。