FT546-WCS/docs/superpowers/plans/2026-08-04-javaTest-method-commentation-plan.md

JavaTest Method Commentation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add Chinese documentation to every Java constructor and method under javaTest, with detailed explanations for the WCS dispatch simulation's core control flow.

Architecture: Use a temporary Java compiler-API scanner to find every MethodTree reliably, including nested types and multi-line declarations. Use the same scanner after editing to prove that each method has an immediately preceding Javadoc block. Add concise comments to simple value objects and tests, then enrich scheduler, map, resource, simulation, report, and fault-handling methods manually where behavior cannot be inferred from a name alone.

Tech Stack: Java 8 source, JDK compiler tree API, Maven, JUnit 5.

Global Constraints

• Modify only Java comments under javaTest/src/main/java and javaTest/src/test/java; no executable Java behavior may change.
• Cover every constructor and method, including getters, helpers, nested types, and JUnit test methods.
• Use Chinese Javadoc. Add @param, @return, or @throws where the signature's contract needs explanation.
• Keep line comments restricted to complex algorithmic blocks.
• Do not modify ruoyi-* modules, test resources, Maven configuration, or generated evidence.
• Final verification requires a complete method-Javadoc scan, git diff --check, and cd javaTest && mvn clean test.

---

Task 1: Establish method coverage inventory

Files:

• Read: javaTest/src/main/java/**/*.java
• Read: javaTest/src/test/java/**/*.java
• Create temporarily outside the repository: compiler-API scanner source and compiled class.

Interfaces:

• Consumes: Java source roots.

• Produces: a deterministic list of methods lacking a Javadoc block directly before the declaration.

• Step 1: Run a baseline scan

Compile and run a temporary Java program that uses JavacTask.parse() and TreePathScanner.visitMethod() to print <relative-file>:<line>:<method> when the declaration's preceding non-whitespace source text does not end in */.

Expected: every current Java method is reported because the baseline contains no Javadocs.

• Step 2: Preserve the scanner command for final verification

Use the same temporary scanner source and source roots without modifying any repository file. The final run must emit no missing methods.

Task 2: Cover non-simulation production support code

Files:

• Modify: javaTest/src/main/java/com/ft546/wcs/demo/**/*.java
• Modify: javaTest/src/main/java/com/ft546/wcs/shadow/{decision,map,replay,resource,snapshot}/**/*.java

Interfaces:

• Consumes: method names, signatures, and class responsibilities.

• Produces: a Javadoc block for every method in the listed packages.

• Step 1: Add type and method Javadocs

Document domain values, queue admission, vehicle assignment, path and traffic helpers, decision models, replay adapters, resource ledgers, and snapshots. For setters and lifecycle methods, state which state changes. For predicates, state the condition evaluated. For value-object accessors, state the exposed field meaning.

• Step 2: Add algorithm block comments

Explain only non-obvious loops and ordering rules, such as candidate scoring, resource capacity evaluation, canonical edge keys, and snapshot version checks.

• Step 3: Run the coverage scan for the listed roots

Expected: no method from these packages appears in the scanner output.

Task 3: Cover history ingestion and complete dispatch simulation

Files:

• Modify: javaTest/src/main/java/com/ft546/wcs/shadow/history/**/*.java
• Modify: javaTest/src/main/java/com/ft546/wcs/shadow/history/simulation/**/*.java

Interfaces:

• Consumes: historical queue/map records and the in-memory simulation workflow.

• Produces: method-level explanations of data normalization, full-grid compilation, endpoint resolution, scheduling, path planning, arbitration, clearance, PLC acknowledgement, movement, release, archive, WMS callback, fault recovery, reporting, and metrics.

• Step 1: Add comments to history loading and data objects

Explain manifest/hash validation, historical-field boundaries, normalized path quality issues, and immutable result/data object accessors.

• Step 2: Add detailed comments to simulation orchestration

For HistoricalDispatchSimulator and related managers, describe the tick order, eligible vehicle selection, independent path planning, corridor ownership, HOLD/redispatch conditions, clearance move lifecycle, resource release timing, watchdog rules, terminalization, and invariants.

• Step 3: Add detailed comments to report and adapter code

Explain duration scaling, historical-vs-simulated comparison fields, CSV escaping, deterministic manifest construction, and the distinction between WMS deliveries and idempotent business effects.

• Step 4: Run the coverage scan for main sources

Expected: no production Java method appears in the scanner output.

Task 4: Cover test code and fixtures

Files:

• Modify: javaTest/src/test/java/**/*.java

Interfaces:

• Consumes: existing JUnit scenarios and fixture helpers.

• Produces: a Javadoc block for every test, lifecycle helper, and fixture/data builder explaining scenario setup and assertion intent.

• Step 1: Document unit and integration tests

Describe the expected business property for every test. Document parameter sources, fixture constructors, synthetic maps, deterministic fault plans, and test data builders so a reader can understand why the scenario exists.

• Step 2: Run the coverage scan for test sources

Expected: no test method or fixture helper appears in the scanner output.

Task 5: Verify comment-only delivery

Files:

• Verify: all Java files under javaTest/src/main/java and javaTest/src/test/java.

• Step 1: Run the full source coverage scan

Expected: zero missing Javadocs across all constructors and methods.

• Step 2: Inspect the diff for accidental behavior changes

Run git diff --check and inspect changed Java lines. Expected: only comments and unavoidable line-ending metadata warnings; no executable statements, imports, signatures, or literals change.

• Step 3: Run full verification

Run cd javaTest && mvn clean test.

Expected: the existing complete suite passes without test failures, errors, or skips.

• Step 4: Commit the documentation change

Run git add javaTest/src/main/java javaTest/src/test/java docs/superpowers/plans/2026-08-04-javaTest-method-commentation-plan.md followed by git commit -m "docs(javaTest): document every Java method".