Test Evidence: Task public API documentation retrofit

Test type: Unit
Requirement IDs: TST-009
Scenario IDs: Iteration 1 Task Javadoc retrofit
Test class/method: Maven compiler and Javadoc doclint (no synthetic test)
Implementation commit: fb0ed7f12c9d89235c102b67f2b13f786011c9ee

Protected behavior

Every Task-owned production type and declared public or protected API carries meaningful Javadoc for its business contract. The documented contracts include authorization and lifecycle scope, Project-first/Task-row lock order, non-disclosing HTTP behavior, fixed status transitions, empty progress, actor/history/version invariants, repository filtering and locks, DTO identifier domains and capability flags, the cross-feature activation guard, and dashboard scope/order/limit.

Test method

This is prose and API documentation, so TST-009 forbids an artificial unit test. Java 25 compilation checks source validity. The Maven Javadoc plugin runs standard doclint against only com.lab.labtimesheet.feature.task, making missing or malformed Task API documentation directly observable without treating unrelated feature retrofit work as Task-owned.

Hand-derived expected result

The Task package contains 21 production Java types. Each type has a main description. Every declared public/protected constructor and method has a contract comment; record components document their identifier domains, null/empty meanings, and capability semantics. Task-scoped Javadoc generation completes with no warnings.

RED

Command

export JAVA_HOME=/opt/homebrew/opt/openjdk@25
export PATH="$JAVA_HOME/bin:$PATH"
./mvnw -DskipTests -Ddoclint=all -Dsubpackages=com.lab.labtimesheet.feature.task javadoc:javadoc

Observed result

[WARNING] Javadoc Warnings
[WARNING] Task.java: warning: no main description (12 accessors)
[WARNING] TaskComment.java: warning: no main description (5 accessors)
[WARNING] TaskStatus.java: warning: no comment (4 enum constants)
[WARNING] 21 warnings
[INFO] BUILD SUCCESS

This was a diagnostic documentation baseline rather than a failing behavioral test. The parent instruction explicitly required doclint/compile instead of a fake test.

GREEN

Command

export JAVA_HOME=/opt/homebrew/opt/openjdk@25
export PATH="$JAVA_HOME/bin:$PATH"
./mvnw -DskipTests -Ddoclint=all -Dsubpackages=com.lab.labtimesheet.feature.task javadoc:javadoc

Observed result

[INFO] --- javadoc:3.12.0:javadoc (default-cli) @ labtimesheet ---
[INFO] BUILD SUCCESS

No Task-scoped Javadoc warning was emitted.

Affected suite

Command and result

export JAVA_HOME=/opt/homebrew/opt/openjdk@25
export PATH="$JAVA_HOME/bin:$PATH"
./mvnw -DskipTests compile

[INFO] Compiling 112 source files with javac [debug parameters release 25] to target/classes
[INFO] BUILD SUCCESS

export DOCKER_HOST=unix:///Users/sechmachine/.orbstack/run/docker.sock
./mvnw clean test

[INFO] Tests run: 113, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

External-test boundaries

Doclint validates Javadoc structure and references, not whether prose perfectly models runtime behavior. Contract accuracy was checked by a scoped adversarial diff review against the numbered Task, authorization, Project-lifecycle, UI, and database requirements. Other feature owners retain responsibility for their own Iteration 1 Javadoc retrofits.

3.4 KiB Raw Blame History