Fix Javadoc warning#860
Draft
tsh-hashimoto wants to merge 7 commits into
Draft
Conversation
The workflow ran `./gradlew javadoc` twice: the first run marked the task up-to-date, so the second (tee'd to javadoc.log) was skipped and produced no output. The warning grep then matched nothing and the job always passed. Run javadoc only once, capturing its output to the log. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Javadoc writes its warnings (including the "N warnings" summary) to stderr, but the pipeline only tee'd stdout to javadoc.log, so the warning grep never matched and the job always passed. Redirect stderr into the log with 2>&1. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
These classes expose only static members and are never instantiated. Adding a documented private constructor silences the "use of default constructor, which does not provide a comment" javadoc warning and also prevents accidental instantiation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CobolCallResult, CobolFileKey, KeyComponent and Linage are instantiated data classes with no explicit constructor. Declare an explicit, documented public no-arg constructor to silence the "use of default constructor, which does not provide a comment" javadoc warning while keeping the existing behavior. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Restore the workflow to its original form. Making the check actually fail on warnings surfaces a pre-existing "source/target value 8 is obsolete" compiler warning whose fix (bumping the Java source/target level) needs team approval. Revert for now; the javadoc doclint warnings themselves have been fixed separately. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The javadoc doclint fixes introduced PMD violations in static-analysis: - Static utility classes now have only a private constructor, so PMD's ClassWithOnlyPrivateConstructorsShouldBeFinal fired. Mark them final. - The documented no-arg constructors on the data classes (CobolFileKey, KeyComponent, Linage, CobolCallResult) trip UnnecessaryConstructor, which the repo enables while disabling UncommentedEmptyConstructor. Keep the documented constructors and suppress the rule locally. - Making CobolFileSort final surfaced protected fields (AvoidProtectedFieldInFinalClass); they are only used internally, so reduce them to private. That in turn revealed COB_DESCENDING as an unused private field, so remove the dead constant. Verified locally: spotlessCheck, pmdMain, spotbugsMain pass and javadoc emits no doclint warnings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
./gradlew javadoc実行時に出力されていた Javadoc の警告（22 件）を解消する。いずれも
libcobj/app/build.gradle.ktsの-Xdoclint:missingによって検出されるドキュメント不足の警告であり、内訳は次の通りである。intを返すC$SLEEPメソッドに@returnが無い（1 件）パッケージを横断して発生していた警告をすべて解消し、
./gradlew javadocが警告なしで完了する状態にした。あわせて、修正に伴って発生する静的解析（PMD）の指摘も解消している。変更点
Javadoc 警告の解消
privateコンストラクタを追加し、インスタンス化を禁止した。対象はConst/CobolResolve/CobolSystemRoutine/CobolCallParams/CobolCheck/CobolConstant/CobolInspect/CobolIntrinsic/CobolString/CobolUtil/CobolFieldFactory/CobolFileFactory/CobolFileSort/CobolTerminal/CobolExceptionId/CobolExceptionInfo/CobolExceptionTabCode。publicデフォルトコンストラクタを明示した。対象はCobolFileKey/KeyComponent/Linage/CobolCallResult。C$SLEEPメソッド: 常に0を返す旨の@returnタグを追加した。静的解析（PMD）対応
上記の変更によって新たに検出された PMD 指摘を、以下の通り解消した。
privateコンストラクタのみを持つため、ClassWithOnlyPrivateConstructorsShouldBeFinalに従いfinalを付与した。UnnecessaryConstructorに該当するため、Javadoc 用のコメントを維持したまま@SuppressWarnings("PMD.UnnecessaryConstructor")で抑制した。CobolFileSortをfinal化したことで顕在化したprotectedフィールド（AvoidProtectedFieldInFinalClass）を、内部でのみ使用しているためprivateに変更した。COB_DESCENDING（UnusedPrivateField）を削除した。その他
spotlessCheck/pmdMain/spotbugsMain/javadocを実行し、フォーマット・静的解析ともにパスすること、および Javadoc の警告が 0 件になることを確認済みである。.github/workflows/javadoc.yml）の変更は含まない。調査の過程で「Javadoc の警告が出ても CI が失敗しない」というワークフローの不具合（警告は標準エラー出力に出るが標準出力のみを検査していた）を発見したが、これを修正して警告検査を有効化すると、別要因であるcompileJavaの警告（source/target value 8 is obsolete）が併せて検出され CI が失敗する。この解消には Java の source/target レベル引き上げというチームの合意が必要な変更を伴うため、ワークフローの修正は本 PR のスコープから除外している。