api-doc-checker

Quick Start

Basic steps for checking API documentation quality:

1. Determine document type - Determine whether it is API documentation or a development guide
2. Load rules - From references/index.json load the rule module
3. Parse document - Extract document structure information (code blocks, tables, links, headings, method signatures, etc.)
4. Execute checks - Execute the corresponding check items according to the document type
5. Generate report - Generate an Excel report and an optional Markdown summary

For detailed implementation, see:references/workflow-details.md

Document type determination

API documentation characteristics

• Filename matching patterns:js-apis-*.md、js-apis-app-ability-*.md、js-apis-inner-*.md、capi-*.md
• Contains API method signatures, interface definitions, parameter descriptions
• Example:js-apis-geolocation.md、js-apis-app-ability-wantAgent.md

Development guide characteristics

• Filename contains:guide、tutorial、overview、getting-startedand other keywords
• Mainly contains concept explanations, usage scenarios, best practices
• Example:application-dev-guide.md、getting-started.md

Check item selection

API documentation (all required)

• All 10 rule modules are executed
• Includes SDK source code consistency check (if the SDK is available)

Development guide (selective execution)

• Required modules：spelling、syntax、path-consistency、clarity、semantics、project-structure、findability、correctness
• Optional modules：completeness、capability
• Not executed: SDK source code consistency check (not applicable)

Core features

7 major quality dimension checks

By loading references/ the rule files in the directory, checks are executed according to the following dimensions:

Dimension	Rule file	Core focus	Detailed issues
Resource discoverability	findability-rules.json	Information discoverability	Inaccurate description keywords; official website materials missing and scattered across other channels
Resource richness/completeness	completeness-rules.json	Content completeness	Sample code/solutions missing; key explanations missing; specification constraint explanations missing; default effect explanations missing; related information explanations missing
Material correctness	correctness-rules.json	Content accuracy	Changes not updated in a timely manner; sample code incomplete/unusable; JSDOC description errors
Resources clear and easy to understand	clarity-rules.json	Clarity of expression	Title does not match content; function description inaccurate; related document links missing; mechanism principle explanations missing
Capability effectiveness	capability-rules.json	API effectiveness	Constraint conditions missing; system bugs; materials outdated and not updated
Capability ease of use	capability-rules.json	API ease of use	Ambiguous naming; sample code impractical
Capability richness	capability-rules.json	API richness	Alternative solutions missing; system capabilities missing; stability localization methods missing

Rule modules

This Skill executes checks by loading references/index.json the rule modules defined in:

Rule module	Rule file	Dimension	Check content
spelling	spelling-rules.json	Material correctness	Spelling errors, HarmonyOS proper noun verification
syntax	syntax-rules.json	Material correctness	Code syntax errors (template string spaces, bracket matching, etc.)
path-consistency	path-consistency-rules.json	Material correctness	Internal document path consistency, consistency with Sample code
semantics	semantics-rules.json	Capability usability	Example code semantic clarity (bundleName placeholders, etc.)
project-structure	project-structure.json	Material correctness	Compliance with official project structure specifications
findability	findability-rules.json	Resource findability	Keyword accuracy, external reference completeness, document discoverability
completeness	completeness-rules.json	Resource richness/completeness	Example completeness, key explanations, constraints, default behavior, related information
correctness	correctness-rules.json	Material correctness	Version synchronization, code executability, JSDOC accuracy, path consistency
clarity	clarity-rules.json	Resources clear and easy to understand	Title-content matching, description accuracy, link completeness, mechanism explanation
capability	capability-rules.json	Capability effectiveness/usability/richness	Constraints, known issues, naming conventions, practicality, alternatives

Rule management instructions: The specific check rules of this SKILL are stored in the references/ directory in JSON files. When adding or modifying check rules, you only need to edit the corresponding rule file, without modifying SKILL.md.

Report format

Excel spreadsheet output

Check results are output as Excel spreadsheet file (.xlsx), containing the following columns:

Column name	Description
File name	Path of the checked file (keep only the characters after the last /)
Designer	Designer of the checked file
Issue type	Quality dimension to which the issue belongs
Issue line number	Specific line number where the issue is located
Issue cause	Detailed description of the issue
Suggested fix	Specific repair suggestion
Issue severity level	Priority classification (Critical/High/Medium/Low)

Excel report support:

• Filtering - filter by issue type, severity level, etc.
• Sorting - sort by any column
• Conditional formatting - display different colors according to severity level (red/yellow/green/blue)

For detailed format descriptions and usage guide, see:references/excel-format.md

Markdown summary report (optional)

Also generate a brief Markdown summary report, including:

• Statistical overview (number of files, number of issues, severity level distribution)
• Issue distribution (statistics by dimension)
• Excel file link

Confidence and priority description

For definitions of confidence and priority and handling suggestions, see:references/scoring-guide.md

SDK source code consistency check (API documentation only)

Function description

The SDK source code consistency check is a core function of the correctness dimension, used to ensure that the documentation remains consistent with the .d.ts definition files in the interface_sdk-js repository.

File mapping rules

The mapping between documentation files and SDK files follows these rules:

Documentation file pattern	SDK file path	Example
js-apis-app-ability-{name}.md	api/@ohos.app.ability.{name}.d.ts	js-apis-app-ability-wantAgent.md → @ohos.app.ability.wantAgent.d.ts
js-apis-{name}.md	api/@ohos.{name}.d.ts	js-apis-geolocation.md → @ohos.geolocation.d.ts
js-apis-inner-{module}-{name}.md	api/{module}/{name}.d.ts	js-apis-inner-wantAgent-wantAgentInfo.md → wantAgent/wantAgentInfo.d.ts
js-apis-inner-{module}-{name}-sys.md	api/{module}/{name}.d.ts	js-apis-inner-wantAgent-wantAgentInfo-sys.md → wantAgent/wantAgentInfo.d.ts
capi-{name}.md	api/{name}.h	capi-native-bundle.md → native_bundle.h

Check items

The SDK source code consistency check includes the following 10 checkpoints:

Checkpoint	Description	Priority
api-since-version-match	API starting version (documentation X+ vs SDK @since)	Critical
param-count-match	Input parameter count consistency	High
param-name-match	Input parameter name spelling accuracy	High
param-type-match	Input parameter type consistency	High
return-type-match	Return value type consistency	High
systemapi-mark-match	System API marker consistency (-sys vs @systemapi)	High
stagemodelonly-mark-match	Stage model constraint marker consistency	Medium
error-code-match	Error code completeness	Medium
enum-values-complete	Enum value enumeration completeness	Medium
interface-fields-complete	API field enumeration completeness	Medium

Usage

The check tool automatically attempts to load the SDK source code from the following locations:

1. Environment variable INTERFACE_SDK_JS_PATH specified local path
2. Via git clone temporarily cloned repository (automatically cleaned up)

Configure environment variables (recommended)：

export INTERFACE_SDK_JS_PATH=/path/to/interface_sdk-js

Rule extension

Add new rules

1. Determine the dimension to which the rule belongs (see the table above)
2. Add the rule configuration in the corresponding rule file
3. No need to modify SKILL.md, takes effect immediately

Rule configuration template

{
  "id": "{dimension}-XXX",
  "name": "rule-name",
  "description": "规则描述",
  "type": "{dimension}",
  "subType": "{subCategory}",
  "priority": "high|medium|low",
  "confidence": 90,
  "enabled": true,
  "checkPoints": [...],
  "message": "错误消息模板",
  "explanation": "详细说明",
  "suggestedFix": "修复建议"
}

For detailed extension guide and examples, see:references/rule-extensions.md