doc: add Javadoc to INDEXED file related classes

[ytr-sakamoto]

概要

INDEXEDファイル関連のJavaクラスに、これまでプレースホルダ（TODO: 準備中）のままだったJavadocコメントを記述しました。

対象クラス

• CobolIndexedFile — INDEXEDファイルの具象実装（SQLiteをストレージとして利用）
• CobolFileKey — 1つのキー（主キー／副キー）を表すクラス
• KeyComponent — SPLIT KEYの構成要素を表すクラス
• IndexedFile — オープン中の1ファイルの実行時状態を保持するクラス
• IndexedCursor 内の FetchResult — フェッチ結果を表すクラス

補足

• コメントを付与する対象は、publicなクラス・メソッド・変数を中心としています。
• Javadocはすべて日本語で記述しています。
• ロジックの変更は一切なく、ドキュメントのみの変更です。

---

Summary

This PR fills in the Javadoc comments for the INDEXED-file related Java classes, which were previously left as TODO: 準備中 placeholders.

Target classes

• CobolIndexedFile — concrete implementation of INDEXED files (backed by SQLite)
• CobolFileKey — represents a single key (primary / alternate)
• KeyComponent — represents a component of a SPLIT KEY
• IndexedFile — holds the runtime state of one opened file
• FetchResult in IndexedCursor — represents a fetch result

Notes

• The comments mainly cover public classes, methods, and fields.
• All Javadoc is written in Japanese.
• This is a documentation-only change with no logic changes.

[tsh-hashimoto]

レビュー（ドキュメントのみの PR）

ロジック変更のない Javadoc 付与 PR です。SQLite のテーブル構成（file_lock / locked_by 列 / metadata_*）、トランザクション設定（setAutoCommit(false) + TRANSACTION_SERIALIZABLE）、IndexedFile の「予約済み・未使用」フィールド群、last_key の順序チェック用途など、実装と照合して正確な記述が大半でした。丁寧な作業に感謝します。

一方で、実装挙動と食い違う記述が数点あります。ドキュメントのみの PR では「記述の正確さ」が唯一の品質軸なので、以下を修正いただけると助かります。

---

1. 🔴 indexed_start_internal の @param cond / @return が実挙動と不一致

CobolIndexedFile.java (@param cond / @return)

• Javadoc:「COB_NE はサポートされておらず、カーソルの生成に失敗する」「カーソル生成に失敗した場合は COB_STATUS_30_PERMANENT_ERROR」
• 実装: IndexedCursor.createCursor() は常に Optional.of(...) を返し、カーソル生成は決して失敗しません。よって indexed_start_internal 内の if (!this.cursor.isPresent()) → COB_STATUS_30 分岐は到達不能なデッドコードです。
• COB_NE を渡した場合の実挙動は「生成失敗」ではなく、getCompOperator() が null を返し、SQL 文に null が埋め込まれて SQLException → 例外を握って Optional.empty() → 結果として COB_STATUS_23_KEY_NOT_EXISTS を返す経路です。
• → 「カーソル生成失敗」「COB_STATUS_30」という記述は誤りです。COB_NE の扱いと @return の条件を実挙動に合わせて修正が必要です。

2. 🟡 コンストラクタ @param fileStatus の「4バイトのバッファ」が根拠なし

• Javadoc:「COBOL の FILE STATUS 用ストレージ（4バイトのバッファ）」
• 実装は file_status[0] と file_status[1] の2バイトのみを読み書きします（CobolFile.java）。COBOL の FILE STATUS も 2 桁です。「4バイト」という具体的サイズはコード上の根拠がなく、誤りの可能性が高いです。サイズ記述の削除、または「2バイト」への修正を推奨します。

3. 🟡 IndexedFile.record_locked の記述が実態より強い

• Javadoc:「このプロセスが現在レコードロックを保持している間は true」
• 実装では p.record_locked = false; で false 代入されるのみで、true を設定する箇所も、条件として読む箇所もありません。兄弟フィールド（last_readkey / lock_id / record_lock 等）は「予約されているが未使用」と正直に書かれているので、このフィールドも同様に「予約済み／現状未使用」と揃えるのが正確です。

4. 🟢 indexed_start_internal の @param readOpts — 未使用注記の欠落（軽微）

• testLock には「現状このメソッドでは未使用」と明記されていますが、readOpts も本メソッド本体では一切参照されていません。整合性のため readOpts にも同様の注記を付けると親切です。

---

いずれもドキュメント文言の修正で対応可能です。とくに 1 が唯一の実挙動との明確な矛盾なので優先的に直すのがよいと思います。

[tsh-hashimoto]

@yutaro-sakamoto @ytr-sakamoto
Claudeにレビューしてもらいました。
コメントを確認の上、修正が必要なものについては対応をお願いします。

[yutaro-sakamoto]

@tsh-hashimoto

4件すべて指摘通り修正しました。
指摘事項1.については以下のサンプルプログラムを検証しました。

       IDENTIFICATION                   DIVISION.
       PROGRAM-ID.                      prog.
      ******************************************************************
       ENVIRONMENT                      DIVISION.
       INPUT-OUTPUT                     SECTION.
       FILE-CONTROL.
           SELECT MYFILE        ASSIGN  TO  EXTERNAL  OUTPUT_FILE
                  ORGANIZATION          IS  INDEXED
                  ACCESS  MODE          IS  SEQUENTIAL
                  RECORD  KEY           IS  R-KEY.
      ******************************************************************
       DATA                             DIVISION.
       FILE                             SECTION.
       FD  MYFILE.
       01  R-REC.
         03  R-KEY                      PIC  X(03).
         03  R-DATA                      PIC  X(03).
      ******************************************************************
       working-storage section.

       PROCEDURE                        DIVISION.
       MAIN                             SECTION.
           OPEN OUTPUT MYFILE.
           MOVE "AAABBB" TO R-REC.
           WRITE R-REC.
           CLOSE MYFILE.

           INITIALIZE R-REC.

           OPEN INPUT MYFILE.
           MOVE "XXX" TO R-KEY.
      *    MOVE "AAA" TO R-KEY.
           START MYFILE KEY IS NOT EQUAL TO R-KEY.
           READ MYFILE.
           DISPLAY R-REC.
           CLOSE MYFILE.

MOVE "XXX" TO R-KEYとMOVE "AAA" TO R-KEY.を交互にコメントアウトして、どちらの場合でもSTART文実行後のファイルステータスが23になることを確認しました。