From 3c5873dfe260a31cb6802423a5c8d49556977fc1 Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Thu, 10 Sep 2026 18:05:07 +0700 Subject: [PATCH] fleetd #453: point the new javadoc at the right javadoc #456's first paragraph said "HerdrPeerLauncher's own {@link #spawn(SpawnRequest, PlacementDecision)} javadoc". That link resolves to this interface's own abstract declaration, not to HerdrPeerLauncher's override, so a reader who follows it lands on the wrong text. The second paragraph already used the plain {@code HerdrPeerLauncher.spawn(...)} form; both now match. Also says who is actually forced to read the paragraph, because #456's reasoning rests on it and the two cases differ. A class that implements this interface directly must write a body for spawn(SpawnRequest, PlacementDecision) - it is abstract here - so it reads this javadoc. A subclass of HerdrPeerLauncher does not: HerdrPeerLauncher already implements that method (member/HerdrPeerLauncher.java:611) and the subclass inherits the body. For a subclass the paragraph is advice, not a gate. javadoc -Ddoclint=reference: 5 "reference not found", the same 5 in the same 5 untouched files as origin/main at 2af13ab, and none in PeerLauncher.java. Those 5 are ticket #459. mvn compile rc=0. --- .../main/java/dev/ltms/fleet/peer/PeerLauncher.java | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/fleetd/src/main/java/dev/ltms/fleet/peer/PeerLauncher.java b/fleetd/src/main/java/dev/ltms/fleet/peer/PeerLauncher.java index 20c8b7c..18f42ca 100644 --- a/fleetd/src/main/java/dev/ltms/fleet/peer/PeerLauncher.java +++ b/fleetd/src/main/java/dev/ltms/fleet/peer/PeerLauncher.java @@ -175,9 +175,16 @@ public interface PeerLauncher { * correct to do so. But it stays correct only as long as that holds: if a launcher ever * routes more than one profile per role, it MUST override this method, or every role * silently resolves to {@link #defaultProfile()} with no error and no log line. {@code - * HerdrPeerLauncher}'s own {@link #spawn(SpawnRequest, PlacementDecision)} javadoc names this - * method and {@link #place} explicitly as "unoverridden here" for exactly this reason — read - * that javadoc before adding role-pool routing to any {@code HerdrPeerLauncher} subclass. + * HerdrPeerLauncher.spawn(SpawnRequest, PlacementDecision)} — the override in {@code + * dev.ltms.fleet.member}, not the declaration below — names this method and {@link #place} + * explicitly as "unoverridden here" for exactly this reason. Read it before adding role-pool + * routing to any {@code HerdrPeerLauncher} subclass. + * + *

Who is forced to read which paragraph, because it is not symmetric. A new class that + * implements this interface directly must write a body for {@link #spawn(SpawnRequest, + * PlacementDecision)}, which is abstract here, so it lands on this javadoc. A subclass of + * {@code HerdrPeerLauncher} does not: that class already implements the method, and the + * subclass inherits the body. So for a subclass this paragraph is advice, not a gate. */ default String defaultProfileFor(MemberRole role) { return defaultProfile();