Update Javadoc for libcobj/file

[tsh-hashimoto]

#787 についてのPR

概要

libcobj の file パッケージ（jp.osscons.opensourcecobol.libcobj.file）配下のクラスについて、Javadoc を整備しました。従来 TODO: 準備中 となっていたフィールドやメソッドのコメントを、実際の役割を説明する内容に置き換え、ソースコードの可読性・保守性を向上させます。

本 PR は Javadoc（コメント）の追記・修正のみで、動作に関わるロジックの変更は含みません。

変更点

• file パッケージ配下の以下 12 クラスについて Javadoc を整備しました。
  • CobolFile.java
  • CobolFileFactory.java
  • CobolFileSort.java
  • CobolItem.java
  • CobolLineSequentialFile.java
  • CobolRelativeFile.java
  • CobolSequentialFile.java
  • CobolSort.java
  • FileIO.java
  • FileStruct.java
  • Linage.java
  • MemoryStruct.java
• TODO: 準備中 となっていたコメントを、フィールド・メソッドの実際の役割を説明する内容に置き換えました。
• ファイル編成・アクセス方式・I/O 操作種別などの定数について、意味が分かるように説明を追加しました。

その他

• 本 PR ではコメントのみを変更しており、ロジックの変更はありません。
• 索引編成（INDEXED）関連のクラス（CobolFileKey / CobolIndexedFile / IndexedCursor / IndexedFile / KeyComponent）は、別 PR（doc: add Javadoc to INDEXED file related classes #843）で対応するため本 PR の対象外としています。

[tsh-hashimoto]

コードレビュー: Javadoc for libcobj/file

結論: 非常に品質の高いドキュメントPRです。 変更は全て /** TODO: 準備中 */ などのプレースホルダを日本語Javadocに置き換えるもので、動作コードの変更はありません（12ファイル、全てコメント）。そのため「ドキュメントが実装と食い違っていないか」を観点に検証しました。主要な数値・意味的記述を実コードと突き合わせた結果、明確な誤りは見つかりませんでした。 ドラフトのままオープンで問題ないと思います。

検証して正しかった主な項目

• ファイル状態コード（00〜92） — 括弧内の数値（(0),(2),(4),(10),(35),(47) 等）が全て定数値・定数名と一致（CobolFile.java:199-292）。
• ビットフラグ定数 — COB_WRITE_*、COB_READ_*、COB_LOCK_MASK = 0x7、COB_WRITE_MASK = 0x0000ffff の説明が値と整合。
• FileIO.read/getc/putc の戻り値記述 — 「fc未設定→0、失敗→-1、成功→バイト値」等が実装通り（FileIO.java:141-347）。
• indexed_start_internal の戻り値 — 「成功→00、該当なし→23、カーソル生成失敗→30」が実装と一致（CobolIndexedFile.java:610-641）。
• readItem の「失敗1/成功・終端0」、sortInit int版が常にnull（モジュール照合順序） も実装通り。
• 全コンストラクタの @param 名と並び が実シグネチャと完全一致（Javadoc警告も出ない）。

軽微な指摘（任意対応・重大度: 低）

1. indexed_start_internal の @param readOpts / @param testLock（CobolIndexedFile.java）
この2つの引数はメソッド本体で一切参照されていません（未使用）。しかしJavadocは readOpts＝「READ文のオプション」、testLock＝「レコードロックを確認するかどうか」と、あたかも効果があるかのように記述しています。(現在の実装では未使用) の一言を添えると誤解を防げます。

2. read(int key, ...) オーバーロードの @param key（CobolFile.java:1509 付近）
@param key 読み込みに用いるキー番号 とありますが、実装は key を無視して read(null, fnstatus, readOpts) を呼ぶだけです。メソッド概要では「内部的には順次読み込みを行う」と補足済みなので実害は小さいですが、@param 側にも「（この多重定義では使用されない）」を付けると一貫します。

参考（本PRの対象外・既存コードの潜在バグ）

FileIO.getc()（FileIO.java:311）は readBuffer[readBufferIndex++]（byte）を int として返すため、データバイトが 0xFF の場合に符号拡張で -1 となり、EOF（-1）と区別できません。本PRが追加したJavadocは現状の（バグを含む）挙動を正しく説明していますが、この既存の取り違えは別途修正候補です。本PRの責務ではないため指摘に留めます。

[tsh-hashimoto]

Javadoc の追記のみで、大半の記述は実装（戻り値の意味・定数値・フィールドの役割・C 実装との対応）と正確に一致していました。実装を確認して確証が取れた「記述と実装の乖離」が 3 点あります。いずれも軽微ですが、Javadoc 追加が成果物そのものであるため共有します。

1. CobolFile.unlock_() の説明が「ロックを解放する」だが、実装はフラッシュのみ

/** ファイルのロックを解除する下位処理. 開いている場合はバッファをフラッシュしてロックを解放する. */
public void unlock_() {
    if (this.open_mode != COB_OPEN_CLOSED && this.open_mode != COB_OPEN_LOCKED) {
        this.file.flush();
    }
}

FileIO.flush() は outputWriteBuffer() とディスク同期（fc.force()）のみで、ロック解放（releaseLock()）は行いません。「ロックを解放する」は実装と食い違うため、「バッファをフラッシュする」に留めるのが正確です。

2. errorFile の説明が「入出力エラーが発生したファイル」だが、成功時にも設定される

/** 直近に入出力エラーが発生したファイルを保持する静的フィールド. */
public static CobolFile errorFile;

saveStatus() は CobolFile.errorFile = this; を status==0（成功）を含め毎回無条件に設定します。実態は「直近に入出力操作を行ったファイル」であり、「エラーが発生した」に限定した記述は不正確です。

3. read(int key, ...) オーバーロードの @param key が「読み込みに用いるキー番号」だが、引数は無視される

public void read(int key, AbstractCobolField fnstatus, int readOpts) {
    this.read(null, fnstatus, readOpts);
}

本文で「内部的には順次読み込みを行う」と書かれている一方、@param key 読み込みに用いるキー番号 は引数が実際には使用されない点と矛盾します。「（この多重定義では使用されない）」等の補足があると誤解を防げます。

---

補足（指摘外）: COB_STATUS_07_SUCCESS_NO_UNIT の「ユニットに関係しない操作が正常終了」は、標準 COBOL では「リール/ユニットでないファイルに対する REEL/UNIT・NO REWIND 付き操作の正常終了」を指すため厳密には少しズレますが、大意は許容範囲です。

全体として品質の高い Javadoc PR で、上記 3 点を直せば記述と実装が完全に整合します。