From 738f93fd5a6e18bb21977c5a52ff675b4fd08b92 Mon Sep 17 00:00:00 2001
From: Thomas Darimont <thomas.darimont@googlemail.com>
Date: Tue, 6 Oct 2026 10:55:13 +0200
Subject: [PATCH] Fail the build on dangling javadoc comments

javac's dangling-doc-comments lint, with -Werror, in a profile that
activates on a build JDK of 23 or newer: the jdk job of the CI catches
a javadoc comment that an edit separated from its declaration, which
Java 21 cannot check.

Closes #48

Signed-off-by: Thomas Darimont <thomas.darimont@googlemail.com>
---
 AGENTS.md       |  4 ++++
 CONTRIBUTING.md |  5 +++++
 pom.xml         | 23 +++++++++++++++++++++++
 3 files changed, 32 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c51e9f9..8a2d387 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -82,6 +82,10 @@ pins a released version. Consequences for a change here:
   constructor through `SsfCollections.copyOf` and nulls normalised to empty. Arguments are checked
   with `SsfAssert`. Factories are static `from(...)` (lenient, returns `null` or an empty value for
   input that does not fit) and `of(...)`.
+- **A javadoc comment belongs to a declaration.** One that an edit left between a method and its
+  own javadoc, or above a blank line, fails the `jdk` job of the CI (javac's `dangling-doc-comments`
+  lint, JDK 23 or newer, profile `dangling-doc-comments`); Java 21 builds do not notice. When you
+  insert a method, anchor on the javadoc above the neighbour, not on its signature.
 - **Protocol facts carry their source.** Javadoc and comments cite the specification and section
   (`SSF 1.0 8.1.4.1`, `RFC 9967, section 2.4`) and name the real-world deviation they tolerate
   (`// CAEP defines seconds since epoch, some transmitters send milliseconds`). Keep that habit;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4659d1a..22d259c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -91,6 +91,11 @@ GitHub Actions, see [`.github/workflows`](.github/workflows):
      and on the newest JDK as a job that does not fail the build; it passes
      `-Dbytebuddy.experimental=true` in case Mockito's Byte Buddy does not know the class file
      version yet), and `database` (the stores of `easyssf-receiver-jdbc` on PostgreSQL and MySQL).
+     The `jdk` job is also where a javadoc comment attached to nothing fails the build: the profile
+     `dangling-doc-comments` of the root POM turns on javac's lint of that name with `-Werror`
+     wherever the build JDK is 23 or newer, which knows the lint; Java 21 does not. To run the check
+     locally, build with such a JDK, for example `JAVA_HOME=~/.sdkman/candidates/java/25.0.2-tem
+     ./mvnw -o -DskipTests test-compile`.
   4. `status` is green when every job that had to run succeeded; skipped jobs count as green. It is
      the one check to require in the branch protection of `main`, the others come and go with the
      change.
diff --git a/pom.xml b/pom.xml
index 782f2bb..2e5b135 100644
--- a/pom.xml
+++ b/pom.xml
@@ -427,6 +427,29 @@
                 </plugins>
             </build>
         </profile>
+        <profile>
+            <!-- A javadoc comment that is attached to nothing, typically one that a later edit separated from
+                 its method, is an error. javac knows the lint from JDK 23 on, so the check runs where the build
+                 JDK is new enough: the "jdk" job of the CI, not the Java 21 jobs. See CONTRIBUTING.md. -->
+            <id>dangling-doc-comments</id>
+            <activation>
+                <jdk>[23,)</jdk>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-compiler-plugin</artifactId>
+                        <configuration>
+                            <compilerArgs>
+                                <arg>-Xlint:dangling-doc-comments</arg>
+                                <arg>-Werror</arg>
+                            </compilerArgs>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
         <profile>
             <!-- Builds the artifacts the way Maven Central requires them: sources and javadoc jars,
                  GPG signatures, and "deploy" publishes to the Central portal. See CONTRIBUTING.md. -->