oh-doc-knowledge-verifier

Documentation knowledge correctness verification

Task and Boundaries

Verify whether theknowledge-based descriptionsin the OpenHarmony API documentation are correct. Such issues are mainly unrelated to the code implementation; instead, the documentation itself contains errors in its descriptions of standards and specifications, mathematical definitions, or technical concepts.

Core workflow: knowledge verification (against authoritative standards) → discover issues → secondary verification of the code implementation(against the business code) → determine the root cause.

Scope of application:

• Descriptions in the documentation of standard specification attributes/parameters (such as SVG transform, CSS properties, etc.)
• Descriptions in the documentation of mathematical definitions (such as transformation matrices, color spaces, interpolation formulas, etc.)
• Descriptions in the documentation of technical concepts (such as rendering pipelines, animation principles, etc.)
• When knowledge verification finds that the documentation is inconsistent with the standard, further compare it against the business code to determine the actual behavior and distinguish the root cause type

Not applicable:

• "Code and documentation inconsistency" issues at the pure code logic level
• Format issues such as documentation structure, templates, and tags
• Consistency between SDK d.ts type definitions and the documentation

Trigger Signals

• "Is the documentation description accurate"
• "Is this parameter description correct"
• "The documentation says X, but the standard says Y"
• "Help me check whether this description is written backwards"
• "Documentation error correction", "description verification"
• "Documentation and code comparison", "check whether the code is implemented this way"
• "The standard says X, the documentation says Y, what does the code actually do"

Initial Checks

1. Obtain the verification target: the user provides a documentation fragment or attribute name + specific description
2. Locate the documentation file: search under the documentation repository
3. Extract verifiable claims: identify all verifiable knowledge-based statements from the documentation

Execution Strategy

Step 1: Claim classification

For each documentation claim, determine the type of its knowledge source; different types use different verification sources:

Type	Characteristics	Verification source
Standard specification type	Behavior is defined by external standards (W3C, CSS, IEEE, etc.)	Original standard specification text
Mathematical fact type	Determined by mathematical definitions, with no ambiguity	Mathematical formulas/definitions
Competitor benchmarking type	Common behavior of similar platforms, consistent across multiple implementations	Cross-verification with Android/iOS/Chrome and other documentation

Classification judgment rules:

• If the attribute/parameter comes from a W3C standard (SVG, CSS, DOM, etc.) → standard specification type
• If the description involves mathematical formulas, matrix operations, or geometric transformations → mathematical fact type
• If it describes common platform behavior and is not constrained by a standard → competitor benchmarking type
• When uncertain, default to treating it as a standard specification type and try to find the corresponding standard

Step 2: Find authoritative verification sources

Find verification sources by claim type:

Standard specification type:

• W3C SVG specification:https://www.w3.org/TR/SVG/
• CSS specification:https://www.w3.org/Style/CSS/
• Web API specification:https://developer.mozilla.org/(MDN as a standard reference)
• Use WebSearch to search {属性名} W3C specification

Mathematical fact type:

• Use WebSearch to search {概念} mathematical definition
• Compare multiple sources to confirm the consistency of the mathematical definition

Competitor benchmarking type:

• Android：https://developer.android.com/
• iOS：https://developer.apple.com/
• Web：https://developer.mozilla.org/
• Flutter：https://api.flutter.dev/

Step 3: Compare item by item

Compare and verify each claim:

文档描述 → 权威验证源描述 → 是否一致

High-frequency error patterns to focus on:

1. Parameter roles reversed: the descriptions of two parameters are swapped (e.g., b/c of SVG matrix)
2. Direction description error: x/y direction reversed, clockwise/counterclockwise reversed
3. Type description error: integer written as floating point, percentage written as pixels, etc.
4. Default value error: the default value does not match the standard
5. Enumeration value omitted or wrong: omitting standard enumeration values or writing the value name incorrectly
6. Scope description too broad or too narrow: the described applicable scope does not match the standard

Step 4: Secondary verification via code implementation (conditionally triggered)

Trigger condition: When Step 3 finds that the documentation is inconsistent with the authoritative standard,mustfurther compare against the business code implementation to distinguish the root cause type.

Core purpose: Standard comparison alone cannot determine whether it is "the documentation that is wrong" or "the code implementation that is wrong"—only by looking at the actual behavior of the code can a conclusion be reached. The same document may have three root causes:

Root cause type	Documentation	Standard	Code	Handling
A. Documentation error	✗	✓	✓	Fix documentation
B. Code error	✓	✗	✗	Fix code
C. Three-way inconsistency	✗	✓	✗	Fix documentation + fix code, and clarify whether the documentation aligns with the code or the standard
D. Intentional platform extension	✗	✓	✗(intentional)	Add an "extension note" to the documentation

Verification process:

1. Locate the code repository
2. Four-layer tracing：
   • Entry layer (frontend bridge):frameworks/bridge/declarative_frontend/jsview/
   • Data layer (property storage):frameworks/core/components_ng/property/、frameworks/core/components/common/properties/
   • Processing layer (validation/clamping):frameworks/core/components_ng/render/、frameworks/core/components/common/painter/
   • Rendering layer (drawing correction):frameworks/core/components_ng/render/adapter/
3. Compare actual code values: find default value initialization, clamping logic, fallback branches
4. Determine the root cause: classify according to the table above

Code tracing must provide:

• Specific file paths and line numbers (e.g., js_view_abstract.cpp:2198）
• Key code snippets (default value assignment, conditional branches, clamping logic)
• Actual output values (combined result of data layer + rendering layer)

Prohibited practices:

• It is prohibited to determine a "documentation error" based solely on the standard conclusion—you must confirm whether the code is consistent with the standard
• It is prohibited to ignore API version conditional branches—PlatformVersion::VERSION_TEN and other judgments may lead to different default values for different API versions

Step 5: Generate report

## 文档知识验证报告

### 验证目标
- 文档：{文件名}
- 章节：{章节名}

### 声明验证

| # | 文档描述 | 声明类型 | 验证源 | 验证源内容 | 判定 |
|---|---------|---------|-------|-----------|------|
| 1 | {原文}  | {类型}  | {来源} | {正确描述} | {一致/不一致} |

### 代码二次验证（仅不一致项）

| # | 文档描述 | 标准规定 | 代码实际 | 根因类型 |
|---|---------|---------|---------|---------|
| 1 | {原文}  | {标准}  | {代码值} | {A/B/C/D} |

**代码追踪证据：**

| 层级 | 文件:行号 | 关键逻辑 | 输出值 |
|------|----------|---------|-------|
| 入口层 | {path}:{line} | {代码片段} | — |
| 数据层 | {path}:{line} | {代码片段} | {值} |
| 处理层 | {path}:{line} | {代码片段} | {值} |

### 错误详情（如有）

**错误 #1：{根因类型}**
- 文档位置：{文件:行号}
- 文档描述：{原文}
- 标准描述：{标准内容}
- 代码实际：{代码行为}
- 验证依据：{标准链接 + 代码文件:行号}

### 修正建议

{根据根因类型给出针对性建议：
- A 类：改文档对齐标准
- B 类：建议提单改代码
- C 类：分别说明文档/代码的修正方向
- D 类：文档补充"OpenHarmony 相对标准的扩展说明"}

Quick reference for high-frequency error patterns

When you need to quickly determine common error types, read references/common-errors.md

Error pattern	Typical manifestation	Inspection method
Swapped parameter roles	Descriptions of two parameters are written in reverse	Compare the mathematical meaning of each parameter in the standard definition
Incorrect direction description	x/y, horizontal/vertical, clockwise/counterclockwise reversed	Check the standard definition; mathematical formulas are unambiguous
Order/index error	Parameter positions are inconsistent with the standard	Compare the parameter order in the standard function signature
Type and value range error	Incorrect description of value range or data type	Check the type definitions and constraints in the standard

Prohibited Practices

1. It is prohibited to use code implementation as the sole verification source for standard normative declarations: Code may have bugs or deviations; the standard is authoritative
2. It is prohibited to determine a "documentation error" based solely on the standard's conclusion: When knowledge inconsistencies are found, you must first look at the code to confirm the actual behavior, distinguish the root cause type (A/B/C/D), and then decide whether to change the documentation or the code
3. It is prohibited to judge parameter meanings from memory: Especially for mathematical concepts such as matrices and transformations, definitions must be checked
4. It is prohibited to ignore standard version differences: SVG 1.1 and SVG 2 may differ; the version referenced by the documentation must be confirmed
5. It is prohibited to equate competitor documentation with the standard: Competitor documentation may also contain errors; use it only for cross-reference

Exceptions and Fallbacks

1. Cannot find the corresponding standard: Expand the search scope, or use competitor documentation + mathematical definitions for cross-validation, and note the verification confidence in the report
2. Standard description is ambiguous: List multiple possible interpretations and verify each separately
3. Standard version conflict: Use the latest official standard as authoritative
4. Code path cannot be traced: Clearly inform the user that verification is impossible, and list the paths searched; do not draw conclusions based on speculation
5. Code deliberately extends the standard (Type D): The documentation should add an "OpenHarmony extension description relative to the standard" rather than forcing alignment with the standard

References

• references/common-errors.md — High-frequency documentation error pattern library; read when common error types need to be quickly identified