docs-check-zh-cn

ドキュメントチェック

テンプレートへの準拠、ドキュメントの一貫性、エラーコードの網羅性、実装との整合性を重視して、OpenHarmony API ドキュメントの品質をチェックします。出力には問題のみを記載してください。すでに準拠している内容は繰り返さないでください。

入力の収集

可能な限り、ユーザーのコンテキスト、現在の作業ディレクトリ、リポジトリの構成からパスを推測してください。必要なファイルが見つからない場合に限り、ユーザーに確認してください。

次の入力を収集または推測してください。

• public API ドキュメントのパス。任意。通常は /docs 配下
• system API ドキュメントのパス。任意。通常は /docs 配下
• エラーコードドキュメントのパス。任意。通常は /docs 配下
• API 定義のパス。通常は /interface 配下
• リポジトリルートのパス。現在のワークスペースからインターフェースの実装を見つけられない場合に限る

デフォルトでは、まずワークスペースルートの /docs を検索し、次に /interface を検索してください。

ユーザーが /docs/... または /interface/... で始まるパスを指定した場合は、現在のモジュールディレクトリからの相対パスではなく、まずリポジトリルートからのパスとして解釈してください。

ユーザーがパスの一部のみを指定した場合は、既知の入力を起点として、ワークスペースルートの /docs および /interface 配下で自動検出を続けてください。レポートでは、チェックしていない範囲を明記してください。

ワークフロー

次の順序で進めてください。

1. ドキュメント、インターフェース宣言、実装コードを特定します。
2. 安定して自動化できるチェックのため、最初に scripts/check_api_doc_consistency.py を実行します。
3. 該当するテンプレートを読み、実際の記述要件を抽出します。
4. スクリプトで確実にチェックできない問題について、手動レビューを行います。
5. 必要に応じて、ドキュメントと実装の動作を照合します。
6. 問題、影響、修正方法のみを記載した Markdown レポートを出力します。

デフォルトでは、次の順序で検索してください。

1. ユーザー指定のパス
2. 現在の作業ディレクトリから上位へたどり、docs と interface を含むワークスペースルートを特定
3. ワークスペースルートの /docs
4. ワークスペースルートの /interface
5. 関連する実装を含む可能性があるその他のソースディレクトリ

現在のディレクトリがサブモジュールの場合、現在のディレクトリ配下に /docs または /interface があると想定しないでください。まずワークスペースルートを特定してください。

テンプレートの選択

次の優先順位でテンプレートを使用します。

1. リポジトリ内のテンプレート
2. 外部ドキュメントへのリンク
3. このスキルに同梱されているデフォルトのテンプレート

リポジトリ内のテンプレートのパス：

• JS API テンプレート：/docs/blob/master/zh-cn/contribute/template/native-template.md
• ArkTS コンポーネント API テンプレート：/docs/blob/master/zh-cn/contribute/template/ts-template.md
• エラーコードテンプレート：/docs/blob/master/zh-cn/contribute/template/errorcodes-template.md

外部リンク：

• JS API テンプレート：https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/template/native-template.md
• ArkTS コンポーネント API テンプレート：https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/template/ts-template.md
• エラーコードテンプレート：https://gitcode.com/openharmony/docs/blob/master/zh-cn/contribute/template/errorcodes-template.md

同梱されているフォールバックテンプレート：

• references/js-template.md
• references/ts-template.md
• references/errorcodes-template.md

まずリポジトリ内のテンプレートを試します。存在しない場合は、外部リンクを試します。それも利用できない場合は、references/ 配下の同梱テンプレートを使用します。最終レポートには、実際に使用したテンプレートの入手元を記載してください。

インターフェースのカテゴリに基づいてテンプレートを選択します。

• 通常の JS API、C API、またはモジュール指向の API ドキュメント：JS API テンプレートを使用します
• ArkTS コンポーネントのインターフェースドキュメント：ArkTS コンポーネントテンプレートを使用します
• エラーコードのドキュメント：エラーコードテンプレートを使用します

ArkTS コンポーネントかどうかを判断する際は、所属する Kit を優先してください。

• インターフェースが ArkUI に属する場合、ArkTS コンポーネントのインターフェースとして扱い、ts-template を使用します
• インターフェースが component、property、event、Builder、Modifier などの ArkUI コンポーネントの概念を明確に使用している場合も、ArkTS コンポーネントのインターフェースとして扱います
• ArkUI 以外の Kit では、既存のドキュメント構造が ArkTS コンポーネントテンプレートに明確に沿っている場合を除き、通常の API ドキュメントをデフォルトとします

ファイル名だけでテンプレートを選択しないでください。Kit、インターフェースの種類、現在のドキュメント構造、d.ts の内容を合わせて考慮してください。

手動レビューの重点項目

スクリプトの実行後、自動化の信頼性が低い以下の項目を重点的に手動でレビューしてください。

• 説明文の明確さ、曖昧さ、用語の一貫性、誤記レベルの言語品質
• 例が実際に役立ち、実行可能で、十分に説明されているか
• ドキュメントの構造が表面的な目印だけでなく、内容としてテンプレートの趣旨に沿っているか
• シナリオ、制約、前提条件、失敗時の挙動が、開発者にとって十分に説明されているか
• 各エラーコードについて記載された原因が、実際に発生するシナリオをすべて網羅しているか
• ドキュメントが実装の挙動、機能の境界、製品の変更と一致しているか
• ArkTS コンポーネントのドキュメントで、パラメーター、デフォルト値、範囲、境界動作について十分な説明があるか

実装との整合性チェック

実装コードを使って、次のようなドキュメントの不足や誤りを特定してください。

• 機能のシナリオ、サブシナリオ、または機能範囲の記載漏れ
• 開発者が十分な背景情報を得られない、概念、原理、使用シナリオの説明不足
• ドキュメントに反映されていない製品、インターフェース、または挙動の変更
• 環境要件、仕様上の制限、前提条件、または失敗シナリオの記載漏れ

現在のリポジトリから実装を特定できない場合は、この作業を中断し、正しいリポジトリのパスをユーザーに確認してください。

出力要件

次のルールに従って Markdown レポートを作成してください。

• すでに要件を満たしている内容は記載しないでください
• 問題ごとに、行番号または場所、問題の説明、理由または影響、修正案を記載し、可能であれば具体的な文案も示してください
• 直接修正したテキストを提示できる場合は、そのテキストを示してください
• 確認していない範囲、不足している入力、確認できない事項は別途記載してください

推奨する問題フィールド：

• Location
• Issue
• Suggestion
• Proposed Fix

リソースの使用

必要な場合にのみ、references/ 配下のファイルを読み込んでください。デフォルトではすべてを読み込まないでください。テンプレートが長い場合は、まず該当するセクションを検索し、必要な部分だけを読んでください。

ユーザーが d.ts ファイルと public／system／error の Markdown パスを一緒に提示した場合は、scripts/check_api_doc_consistency.py を必ず使用してください。このスクリプトでは、繰り返し発生する信頼性の高いチェックをすでに実行できます。対象には以下が含まれます。

• d.ts のタグ抽出と @throws の解析
• public／system の配置とリンク方向のチェック
• @syscap、@permission、@atomicservice、@systemapi、モデル専用タグ、@deprecated、@useinstead の構造化フィールドチェック
• セクション単位およびドキュメント単位のエラーコード網羅性
• -sys.md の命名、タイトル、Readme-CN.md のエントリーのチェック
• system ドキュメントの混在モジュールに関する注記のチェック
• エラーコードドキュメント内の必須ブロックのチェック
• モジュールの since 注記や <sup>x+</sup> の有無など、基本的なバージョンマーカーのチェック
• ページ内リンクと相対 Markdown リンクの解決

フィールド形式のチェックでは、手動でキーワードを検索するよりも、スクリプトの結果を優先してください。現在のスクリプトは、系统接口、模型约束、需要权限 などのラベル付きドキュメントフィールドを解析するため、関係のない文章によるノイズを減らせます。

@since の扱いについては、動的 API のドキュメントという観点のみで解釈してください。

• @since x は、動的 API がバージョン x から利用可能であることを意味します
• @since x dynamic は、動的 API がバージョン x から利用可能であることを意味します
• @since x dynamic&static は、動的形式と静的形式の両方がバージョン x から利用可能であることを意味します。現在のチェッカーでは、x を動的バージョンとして使用してください
• @since x static は、現在のドキュメントチェッカーでは無視されます
• @since x dynamiconly は、API が動的形式のみで、バージョン x から利用可能であることを意味します
• @since x staticonly は、現在のドキュメントチェッカーでは無視されます

現在のチェックでは、静的形式のみを対象とするバージョンタグを、ドキュメントのバージョン要件として扱わないでください。

変更される可能性のあるテンプレートの文言を SKILL.md にハードコードしないでください。スクリプトは、変更されやすいリテラルを scripts/doc_check_rules.json から読み込みます。

リポジトリ内のテンプレートまたは外部テンプレートが変更された場合：

1. 新しいテンプレートの文言と scripts/doc_check_rules.json を比較します。
2. 期待される文言または必須ブロックのみが変更された場合は、まず scripts/doc_check_rules.json を更新します。
3. ルールのロジック自体が有効でなくなった場合に限り、scripts/check_api_doc_consistency.py を更新します。
4. テンプレートファイルがローカルで利用できる場合は、--js-template、--ts-template、--error-template を指定してスクリプトを実行し、設定済みのルールが現在のテンプレートの文言と一致しなくなった場合に警告が出るようにします。

次のように実行します。

python3 scripts/check_api_doc_consistency.py \
  --api /path/to/file.d.ts \
  --public-doc /path/to/public.md \
  --system-doc /path/to/system.md \
  --error-doc /path/to/error.md \
  --readme-doc /path/to/Readme-CN.md \
  --js-template /path/to/native-template.md \
  --ts-template /path/to/ts-template.md \
  --error-template /path/to/errorcodes-template.md

--readme-doc は省略可能です。省略すると、スクリプトは public／system ドキュメントのディレクトリから Readme-CN.md を推測しようとします。 テンプレート引数も省略可能ですが、指定すると、ルールファイルが現在のテンプレートの文言と一致しなくなった場合に警告を出す追加の保護機能として使えます。

スクリプトの出力を最初の確認結果として扱ってください。スクリプトの指摘を明確化または確認する場合を除き、レポート内でこれらの低レベルのルールを手作業で重複して列挙しないでください。手動レビューは、意味上の抜け、説明の質、実装との整合性の確認に重点を置いてください。