Update Javadoc for libcobj/user_util

[tsh-hashimoto]

概要

libcobj/app/src/main/java/jp/osscons/opensourcecobol/libcobj/user_util 配下の Javadoc を整備する。
TODO: 準備中 のままになっていた箇所や、簡素な英語コメントのみだった箇所を対象に、クラス・メソッド・フィールドの役割と引数・戻り値の意味を日本語で記述した。動作に影響する変更は含まない。

直前の PR #825 (libcobj/ui の Javadoc 更新) と同様の方針で、libcobj 以下の Javadoc 整備を進めるものである。

変更点

user_util/cobj_api

• ApiFiles.java
  • javaCreate / writeController / writeRecord / argPrint の Javadoc を書き直し、生成される <PROGRAM-ID>Controller.java および <PROGRAM-ID>Record.java の役割と、入力となる JSON ファイル(cobj -info-json-dir の出力)の関係を明記した。
  • argPrint については isType / isRecord の組み合わせによる出力形式の違いを箇条書きで説明した。
  • 実在しないパラメータ programId の @param を削除し、実際のシグネチャに合わせて記述を修正した。
• ApiFilesOptions.java
  • filePath フィールドに Javadoc を追加した。

user_util/indexed_file

• IndexedFileUtilMain.java
  • main / printHelpMessage / parseKeyOptions / processInfoCommand / processLoadCommand / processUnloadCommand / createCobolFile の Javadoc を整理し、サブコマンド (info / create / load / unload / migrate / unlock) との対応関係や戻り値の意味を明記した。
  • parseKeyOptions では -k オプションの書式(offset,size のコロン区切り、先頭 d で重複キー)と具体例を追記した。
  • Javadoc が未記述だった migrateIndexedFile / unlockIndexedFile に Javadoc を追加した。
  • createCobolFile の @return について、戻り値の型が Optional<CobolFile> であることと、実装上は常に値を含む Optional を返すことを明記した。
• CobolFileKeyInfo.java — クラス・フィールド・コンストラクタに Javadoc を追加した。
• ErrorLib.java — 各エラー出力メソッドの Javadoc を日本語化し、引数と戻り値(終了コード 1)の意味を明記した。
• RecordReader.java / RecordWriter.java — インタフェースと各メソッドの Javadoc を追加し、cobj-idx load / unload との対応を記述した。RecordReader.getInstance の実装選択ロジックについては、filePath の実在チェックではなく Optional の presence を見ているという実装に合わせ「指定されている / 指定されていない」という表現で記述した。
• FileSeqRecordReader.java / FileLineSeqRecordReader.java — 対応する入力データ形式 (SEQUENTIAL / LINE SEQUENTIAL) と、コンストラクタ時点ではファイルを開かず open() で開く挙動を明記した。
• StdinRecordReader.java — 基底クラスと内部クラス (StdinLineSeqReader / StdinSeqReader) の関係、StdinSeqReader で入力長が recordSize の倍数でない場合の戻り値を追記した。StdinSeqReader については、実装が Scanner#next() で空白区切りトークンを String として取得する形になっていることを踏まえ、バイナリストリームではなくトークンベースの読み込みである旨を明記した。

その他

• コメント以外の変更は行っていないため、ビルド成果物および実行時挙動に影響はない。
• StdinRecordReader の基底クラスで read が null を返している件(Copilot から指摘あり)については、RecordReader の契約との不整合があり NPE の原因になり得るが、本 PR のスコープ(Javadoc 整備のみ)を外れるため別 PR で対応する。本 PR では現状の挙動をそのまま Javadoc に記すにとどめる。

[Copilot]

Pull request overview

This PR replaces placeholder TODO Javadocs in libcobj/user_util with more complete Japanese documentation, mainly around the cobj-idx indexed-file utility (record I/O, CLI behaviors) and the cobj-api Java-file generator.

Changes:

• Document RecordReader/RecordWriter responsibilities and the stdin/file reader implementations for SEQUENTIAL / LINE SEQUENTIAL formats.
• Expand IndexedFileUtilMain method Javadocs for key parsing and subcommands (info, load, unload, migrate, unlock, create).
• Add/clarify Javadocs in cobj_api (input JSON path, generated files, and helper method behavior).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
.../indexed_file/StdinRecordReader.java	Adds class/inner-class Javadocs for stdin-based readers and the factory method.
.../indexed_file/RecordWriter.java	Documents the record output interface used by cobj-idx unload.
.../indexed_file/RecordReader.java	Documents the record input interface and its factory method for file vs stdin.
.../indexed_file/IndexedFileUtilMain.java	Subcommand and helper method Javadocs (key parsing, migrate/unlock, load/unload, create).
.../indexed_file/FileSeqRecordReader.java	Documents SEQUENTIAL file reading semantics (incl. trailing newline handling).
.../indexed_file/FileLineSeqRecordReader.java	Documents LINE SEQUENTIAL file reading semantics.
.../indexed_file/ErrorLib.java	Updates class/method descriptions for error reporting/exit codes.
.../indexed_file/CobolFileKeyInfo.java	Adds class/field/ctor documentation for key metadata.
.../cobj_api/ApiFilesOptions.java	Adds doc for the JSON input path field.
.../cobj_api/ApiFiles.java	Expands docs for generated files and helper output formatting behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tsh-hashimoto]

コードレビュー

結論: ブロッキングな指摘事項はありません。

対象は libcobj/app/src/main/java/jp/osscons/opensourcecobol/libcobj/user_util/ 配下 10 ファイルの Javadoc 整備のみで、実行挙動への影響はありません。Javadoc と実コードの整合性、git 履歴、既存コメントとの整合性を並列で確認しましたが、以下の主要クレームはすべて実装と一致しています。

• argPrint の 3 ケース分岐説明 (ApiFiles.java)
• createCobolFile が常に値を含む Optional を返すという記述
• parseKeyOptions の 2,2:5,4:d15,5 の例 (プライマリキー = 先頭、d 接頭で重複可)
• FileSeqRecordReader の末尾 \n / \r\n を終端として扱う記述
• RecordReader.getInstance の「指定されている場合」(Optional の presence で判定) という表現
• StdinSeqReader の Scanner#next() ベース読み込みと recordSize の倍数でない場合の LoadResultDataSizeMismatch 返却
• ErrorLib 各メソッドの終了コード 1 の記述
• <PROGRAM-ID> はすべて {@code ...} で囲まれており HTML タグとして解釈されるリスクなし
• processUnloadCommand の @param userDataFormat 説明は、旧コメントの 0x20 (スペース) という既存バグが日本語化と同時に「改行文字」に暗黙修正されている改善あり (実装 IndexedFileUtilMain.java#L665-L671 で `'\n'` を書き込んでおり新 Javadoc と一致)

検討したが採用しなかった指摘 (参考)

1. `argPrint` Javadoc の 3 ケース記述 — `isType=true, isRecord=true` が同時 `true` の場合、コードは `if/else if` なので `isType` が優先されますが、Javadoc はこの同時 true ケースに触れていません。ただし呼び出し側は `(false,false)` / `(false,true)` / `(true,false)` の 3 通りのみ (全 6 箇所の呼び出しを確認) で、`(true,true)` は発生しないため実害なし。スタイル上の改善余地はあるものの指摘としては過剰と判断しました。`ApiFiles.java#L283-L306`

2. `StdinRecordReader.read()` が `null` を返す件 / `StdinSeqReader` の `hasNextLine()` と `next()` の齟齬 — いずれもコードの既存挙動に関する指摘です。PR 本文で作者が明示的にスコープ外としており、新 Javadoc でも `null` 返却を明示しています (`StdinRecordReader.java#L1-L15`)。別 PR として追跡用 issue/PR を作成しておくとフォローアップが明確になります。

3. `processLoadCommand` の `LoadResultOther` が重複キー以外の I/O エラーでも `errorDuplicateKeys()` を呼ぶ件 — 既存コードの挙動で本 PR では未変更、かつ新 Javadoc はエラー分岐を列挙していないため矛盾なし。

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}