Documentation Knowledge Correctness Validation

Task and Boundaries

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

Core workflow: Knowledge validation (comparison against authoritative standards) → Identify the issue → Secondary code implementation validation (comparison against implementation code) → Determine the root cause.

Applicable scope:

Descriptions of attributes or parameters defined by standards and specifications, such as SVG transform and CSS properties
Descriptions of mathematical definitions, such as transformation matrices, color spaces, and interpolation formulas
Descriptions of technical concepts, such as rendering pipelines and animation principles
When knowledge validation finds an inconsistency between the documentation and a standard, further compare it with the implementation code to determine the actual behavior and identify the root-cause type

Not applicable:

Pure code-logic issues involving a "code and documentation inconsistency"
Documentation structure, template, tag, or other formatting issues
Consistency between SDK d.ts type definitions and documentation

Trigger Signals

"Is this description in the documentation accurate?"
"Is this parameter description correct?"
"The documentation says X, but the standard says Y"
"Check whether this description has the two meanings reversed"
"Documentation correction" or "description validation"
"Documentation-to-code comparison" or "Check whether the code implements it this way"
"The standard says X, the documentation says Y, and what does the code actually do?"

Initial Checks

Obtain the validation target: The user provides a documentation excerpt or an attribute name together with the specific description
Locate the documentation file: Search the documentation repository
Extract verifiable claims: Identify all verifiable knowledge-based statements in the documentation

Execution Strategy

Step 1: Claim Classification

For each documentation claim, determine the type of its knowledge source and use the corresponding validation source:

Type	Characteristics	Validation Source
Standard-specification type	The behavior is defined by an external standard or specification (W3C, CSS, IEEE, etc.)	The original standard or specification
Mathematical-fact type	The claim is determined by a mathematical definition and is unambiguous	Mathematical formulas or definitions
Competitive-benchmark type	The claim describes behavior common across similar platforms and consistently implemented by multiple vendors	Cross-validation against Android, iOS, Chrome, and other documentation

Classification rules:

If an attribute or parameter comes from a W3C standard, such as SVG, CSS, or DOM, classify it as standard-specification type
If the description involves mathematical formulas, matrix operations, or geometric transformations, classify it as mathematical-fact type
If the description concerns common platform behavior that is not governed by a standard, classify it as competitive-benchmark type
When uncertain, default to standard-specification type and attempt to locate the corresponding standard

Step 2: Locate Authoritative Validation Sources

Locate validation sources according to the claim type:

Standard-specification type:

W3C SVG specification:
```
https://www.w3.org/TR/SVG/
```
CSS specifications:
```
https://www.w3.org/Style/CSS/
```
Web API specifications:
```
https://developer.mozilla.org/
```
(use MDN as a standards reference)
Use WebSearch to search for
```
{property name} W3C specification
```

Mathematical-fact type:

Use WebSearch to search for
```
{concept} mathematical definition
```
Compare multiple sources to confirm that the mathematical definition is consistent

Competitive-benchmark type:

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

Step 3: Compare Claim by Claim

Compare each claim against its validation source:

Documentation description → Authoritative validation source description → Consistent?

Common high-frequency error patterns:

Parameter roles written in reverse: The descriptions of two parameters are swapped, such as the b/c values of an SVG matrix
Incorrect direction: The x/y direction or clockwise/counterclockwise direction is reversed
Incorrect type description: An integer is described as a floating-point value, a percentage as pixels, and so on
Incorrect default value: The default value differs from the standard
Missing or incorrect enumeration value: A standard enumeration value is omitted or assigned the wrong name
Scope described too broadly or too narrowly: The stated applicability differs from the standard

Step 4: Secondary Code Implementation Validation (Conditionally Triggered)

Trigger condition: When Step 3 finds an inconsistency between the documentation and an authoritative standard, it is mandatory to compare the implementation code to distinguish the root-cause type.

Core purpose: A comparison against the standard alone cannot determine whether the documentation or the implementation is incorrect. The code's actual behavior must be examined before drawing a conclusion. A single document may have one of four root causes:

Root-Cause Type	Documentation	Standard	Code	Resolution
A. Documentation error	✗	✓	✓	Update the documentation
B. Code error	✓	✗	✗	Update the code
C. Three-way inconsistency	✗	✓	✗	Update both the documentation and code, and explicitly state whether the documentation should align with the code or the standard
D. Intentional platform extension	✗	✓	✗ (intentional)	Add an "extension note" to the documentation

Validation workflow:

Locate the code repository

Trace through four layers:

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/

Compare actual values in the code: Locate default-value initialization, clamping logic, and fallback branches
Determine the root cause: Classify it according to the table above

Code tracing must provide:

Specific file paths and line numbers, such as
```
js_view_abstract.cpp:2198
```
Key code snippets, including default-value assignments, conditional branches, and clamping logic
Actual output values, including the combined result of the data and rendering layers

Prohibited practices:

Do not use the code implementation as the sole validation source for standard-specification claims. The code may contain bugs or deviations, while the standard is authoritative
Do not classify an issue as a "documentation error" solely from the standard comparison. When a knowledge inconsistency is found, inspect the code to confirm the actual behavior, distinguish the root-cause type (A/B/C/D), and then decide whether to update the documentation or the code
Do not determine parameter meanings from memory. In particular, mathematical concepts such as matrices and transformations must be checked against their definitions
Do not ignore differences between standard versions. SVG 1.1 and SVG 2, for example, may differ, so the version referenced by the documentation must be confirmed

Step 5: Generate the Report

markdown

## Documentation Knowledge Validation Report

### Validation Target
- Documentation: {file name}
- Section: {section name}

### Claim Validation

| # | Documentation Description | Claim Type | Validation Source | Validation Source Content | Verdict |
|---|---------|---------|-------|-----------|------|
| 1 | {original text} | {type} | {source} | {correct description} | {consistent/inconsistent} |

### Secondary Code Validation (inconsistent claims only)

| # | Documentation Description | Standard Specification | Actual Code Behavior | Root-Cause Type |
|---|---------|---------|---------|---------|
| 1 | {original text} | {standard} | {code value} | {A/B/C/D} |

**Code tracing evidence:**

| Layer | File:Line | Key Logic | Output Value |
|------|----------|---------|-------|
| Entry layer | {path}:{line} | {code snippet} | — |
| Data layer | {path}:{line} | {code snippet} | {value} |
| Processing layer | {path}:{line} | {code snippet} | {value} |

### Error Details (if any)

**Error #1: {root-cause type}**
- Documentation location: {file:line}
- Documentation description: {original text}
- Standard description: {standard content}
- Actual code behavior: {code behavior}
- Verification basis: {standard link + code file:line}

### Correction Recommendations

{Provide targeted recommendations based on the root-cause type:
- Type A: Update the documentation to align with the standard
- Type B: File a ticket to update the code
- Type C: Explain the documentation and code correction directions separately
- Type D: Add an "OpenHarmony extension relative to the standard" note to the documentation}

High-Frequency Error Pattern Quick Reference

To quickly identify common error types, read references/common-errors.md.

Error Pattern	Typical Manifestation	Inspection Method
Swapped parameter roles	The descriptions of two parameters are reversed	Compare the mathematical meaning of each parameter with the standard definition
Incorrect direction description	The x/y, horizontal/vertical, or clockwise/counterclockwise direction is reversed	Check the standard definition; mathematical formulas are unambiguous
Incorrect order or index	The parameter position differs from the standard	Compare the parameter order in the standard function signature
Incorrect type or value range	The data type or allowed value range is described incorrectly	Check the type definitions and constraints in the standard

Prohibited Practices

Do not use the code implementation as the sole validation source for standard-specification claims: The code may contain bugs or deviations, while the standard is authoritative
Do not classify an issue as a "documentation error" solely from the standard comparison: When a knowledge inconsistency is found, inspect the code to confirm the actual behavior, distinguish the root-cause type (A/B/C/D), and then decide whether to update the documentation or the code
Do not determine parameter meanings from memory: In particular, mathematical concepts such as matrices and transformations must be checked against their definitions
Do not ignore differences between standard versions: SVG 1.1 and SVG 2 may differ, so the version referenced by the documentation must be confirmed
Do not treat competitor documentation as equivalent to a standard: Competitor documentation may also contain errors and should be used only as a cross-reference

Exceptions and Fallbacks

No corresponding standard can be found: Expand the search scope or cross-validate against competitor documentation and mathematical definitions, and report the validation confidence level
The standard description is ambiguous: List the possible interpretations and validate each one
Standard versions conflict: Use the latest official version of the standard
The code path cannot be traced: Clearly inform the user that validation was not possible and list the paths that were searched; do not draw conclusions based on speculation
The code intentionally extends the standard (Type D): Add an "OpenHarmony extension relative to the standard" note to the documentation instead of requiring alignment with the standard

References

references/common-errors.md — A library of common documentation error patterns; read it when you need to quickly identify common error types

oh-doc-knowledge-verifier

NPX Install

Tags

SKILL.md Content (Chinese)