use markdown javadoc

Converts every documentation comment to the /// form of JEP 467: 54 javadoc
comments plus two block comments that already sat in documentation positions.
Markdown idiom throughout - `code` for {@code}, [Type#member] for {@link}, blank
/// lines for <p>, and backticked annotation names for the &#64; entities.

The five comments inside method bodies stay /* */, since /// is a documentation
comment form and those document statements rather than declarations.

No behaviour change. Verified with javadoc -Xdoclint:all: no warnings, the
[#member] references resolve, and the generated HTML shows code spans, paragraphs
and links rather than literal markdown.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: SirCotare

src/main/java/it/aboutbits/archunit/toolbox/config/ArchRuleConfig.java

@@ -10,12 +10,10 @@ public final class ArchRuleConfig {
     private ArchRuleConfig() {
     }
 
-    /**
-     * List of supported test class name suffixes.
-     * <p>
-     * When introducing a new test type (e.g. IntegrationTest), add its suffix here
-     * instead of directly modifying the regex pattern.
-     **/
+    /// List of supported test class name suffixes.
+    ///
+    /// When introducing a new test type (e.g. IntegrationTest), add its suffix here
+    /// instead of directly modifying the regex pattern.
     public static final Set<String> TEST_CLASS_SUFFIXES = new HashSet<>(
             Set.of(
                     "Test",

src/main/java/it/aboutbits/archunit/toolbox/rule/base/AnalyzedPackagesMustContainClassesArchRule.java

@@ -4,16 +4,13 @@
 import com.tngtech.archunit.junit.ArchTest;
 import org.jspecify.annotations.NullMarked;
 
-/**
- * Checks that the analyzed packages contain any classes at all.
- * <p>
- * Every other rule tolerates an empty selection, because whether a project has records, controllers
- * or @Nested test classes is the project's business and not something this library gets to require.
- * That leaves exactly one dangerous case: a mistyped or moved package in @AnalyzeClasses imports
- * nothing, and every rule then passes without looking at a single class. This rule is what turns that
- * into a failure, once, with a message that names the actual problem.
- * </p>
- */
+/// Checks that the analyzed packages contain any classes at all.
+///
+/// Every other rule tolerates an empty selection, because whether a project has records, controllers
+/// or `@Nested` test classes is the project's business and not something this library gets to require.
+/// That leaves exactly one dangerous case: a mistyped or moved package in `@AnalyzeClasses` imports
+/// nothing, and every rule then passes without looking at a single class. This rule is what turns that
+/// into a failure, once, with a message that names the actual problem.
 @SuppressWarnings({"checkstyle:InterfaceIsType", "java:S1214"})
 @NullMarked
 public interface AnalyzedPackagesMustContainClassesArchRule {

src/main/java/it/aboutbits/archunit/toolbox/rule/common/ControllerRequestMappingsMustBeSecurityTested.java

@@ -109,11 +109,9 @@ public void check(JavaMethod method, ConditionEvents events) {
             }
         }
 
-        /*
-         * The @Nested class named after the controller method, or a @Nested class grouped inside it
-         * (GetAll$WhenAdmin). Matching on a bare prefix would also accept an unrelated longer
-         * sibling, so getAll() would count as covered by a @Nested class named GetAllArchived.
-         */
+        /// The `@Nested` class named after the controller method, or a `@Nested` class grouped inside it
+        /// (GetAll$WhenAdmin). Matching on a bare prefix would also accept an unrelated longer
+        /// sibling, so getAll() would count as covered by a `@Nested` class named GetAllArchived.
         private static boolean isExpectedNestedClass(String candidateName, String expectedName) {
             return candidateName.equals(expectedName)
                     || candidateName.startsWith(expectedName + "$");

src/main/java/it/aboutbits/archunit/toolbox/rule/common/SortMappingsExhaustiveArchRule.java

@@ -35,14 +35,11 @@ default void sort_mappings_cover_all_sort_enum_values(JavaClasses classes) {
                 .check(classes);
     }
 
-    /**
-     * Checks that every value of a Sort enum has a mapping.
-     * <p>
-     * Every case this cannot verify is reported as a violation rather than skipped. Reading a
-     * mapping requires reflection, and a mapping that cannot be read is indistinguishable from one
-     * that is exhaustive - so silence here means the rule quietly stops covering that field.
-     * </p>
-     */
+    /// Checks that every value of a Sort enum has a mapping.
+    ///
+    /// Every case this cannot verify is reported as a violation rather than skipped. Reading a
+    /// mapping requires reflection, and a mapping that cannot be read is indistinguishable from one
+    /// that is exhaustive - so silence here means the rule quietly stops covering that field.
     class HaveExhaustiveSortMappingsIfPresent extends ArchCondition<JavaClass> {
         public HaveExhaustiveSortMappingsIfPresent() {
             super("have SortMappings that map all values of the associated Sort enum");

src/main/java/it/aboutbits/archunit/toolbox/support/ArchIgnoreGroupName.java

@@ -5,15 +5,12 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/**
- * Marks a @Nested test class that only groups tests logically and therefore has no matching
- * nested class in the production code.
- * <p>
- * Must not be meta-annotated with ArchUnit's &#64;ArchIgnore: the ArchUnit JUnit engine resolves
- * meta-annotations, so that would skip every &#64;ArchTest on the annotated class instead of
- * exempting it from a single rule. The rules read this annotation by its own type.
- * </p>
- */
+/// Marks a `@Nested` test class that only groups tests logically and therefore has no matching
+/// nested class in the production code.
+///
+/// Must not be meta-annotated with ArchUnit's `@ArchIgnore`: the ArchUnit JUnit engine resolves
+/// meta-annotations, so that would skip every `@ArchTest` on the annotated class instead of
+/// exempting it from a single rule. The rules read this annotation by its own type.
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ArchIgnoreGroupName {

src/main/java/it/aboutbits/archunit/toolbox/support/ArchIgnoreNoProductionCounterpart.java

@@ -5,15 +5,12 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-/**
- * Marks a test class that has no matching counterpart in the production code, for example a
- * scenario test named after the behaviour it describes.
- * <p>
- * Must not be meta-annotated with ArchUnit's &#64;ArchIgnore: the ArchUnit JUnit engine resolves
- * meta-annotations, so that would skip every &#64;ArchTest on the annotated class instead of
- * exempting it from a single rule. The rules read this annotation by its own type.
- * </p>
- */
+/// Marks a test class that has no matching counterpart in the production code, for example a
+/// scenario test named after the behaviour it describes.
+///
+/// Must not be meta-annotated with ArchUnit's `@ArchIgnore`: the ArchUnit JUnit engine resolves
+/// meta-annotations, so that would skip every `@ArchTest` on the annotated class instead of
+/// exempting it from a single rule. The rules read this annotation by its own type.
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ArchIgnoreNoProductionCounterpart {

src/main/java/it/aboutbits/archunit/toolbox/util/CodeUnitUtil.java

@@ -11,14 +11,11 @@ public final class CodeUnitUtil {
     private CodeUnitUtil() {
     }
 
-    /**
-     * Human readable kind of a code unit, for violation messages.
-     * <p>
-     * Rules that inspect bodies must iterate {@code getCodeUnits()} rather than {@code getMethods()}:
-     * the latter excludes constructors, and an instance field initializer is compiled into the
-     * constructor, so both are invisible to a rule that only looks at methods.
-     * </p>
-     */
+    /// Human readable kind of a code unit, for violation messages.
+    ///
+    /// Rules that inspect bodies must iterate `getCodeUnits()` rather than `getMethods()`:
+    /// the latter excludes constructors, and an instance field initializer is compiled into the
+    /// constructor, so both are invisible to a rule that only looks at methods.
     public static String describeKind(JavaCodeUnit codeUnit) {
         return switch (codeUnit) {
             case JavaMethod _ -> "Method";

src/main/java/it/aboutbits/archunit/toolbox/util/TestClassNames.java

@@ -9,69 +9,54 @@
 
 import static it.aboutbits.archunit.toolbox.config.ArchRuleConfig.TEST_CLASS_SUFFIXES;
 
-/**
- * Single source of truth for recognising a test class by its name suffix.
- * <p>
- * Every rule that selects test classes must go through {@link #testClasses()}, and every rule that
- * derives a production class name must go through {@link #productionClassSimpleName(String)}.
- * Hand-building the suffix regex per rule is what allowed a condition to be anchored differently
- * from the selection that fed it, silently disabling the rule.
- * </p>
- */
+/// Single source of truth for recognising a test class by its name suffix.
+///
+/// Every rule that selects test classes must go through [#testClasses()], and every rule that
+/// derives a production class name must go through [#productionClassSimpleName(String)].
+/// Hand-building the suffix regex per rule is what allowed a condition to be anchored differently
+/// from the selection that fed it, silently disabling the rule.
 @NullMarked
 public final class TestClassNames {
     private TestClassNames() {
     }
 
-    /**
-     * Matches the name of a test class: at least one character, then one of the configured suffixes.
-     * <p>
-     * The leading {@code .+} is load-bearing. {@link String#matches(String)} and ArchUnit's
-     * {@code haveNameMatching} both anchor at each end, so without it the pattern only matches a
-     * class named exactly {@code Test}. It is also what keeps such a class out of the selection,
-     * since it has no name left once the suffix is stripped.
-     * </p>
-     */
+    /// Matches the name of a test class: at least one character, then one of the configured suffixes.
+    ///
+    /// The leading `.+` is load-bearing. [String#matches(String)] and ArchUnit's
+    /// `haveNameMatching` both anchor at each end, so without it the pattern only matches a
+    /// class named exactly `Test`. It is also what keeps such a class out of the selection,
+    /// since it has no name left once the suffix is stripped.
     public static String testClassNameRegex() {
         return ".+(" + suffixAlternation() + ")$";
     }
 
-    /**
-     * Matches only the trailing suffix, for stripping it off a test class name. Deliberately not
-     * anchored at the start - this is used with {@link String#replaceAll(String, String)}, never
-     * with {@link String#matches(String)}.
-     */
+    /// Matches only the trailing suffix, for stripping it off a test class name. Deliberately not
+    /// anchored at the start - this is used with [String#replaceAll(String, String)], never
+    /// with [String#matches(String)].
     public static String suffixRegex() {
         return "(" + suffixAlternation() + ")$";
     }
 
-    /**
-     * Whether a simple name is the name of a test class.
-     * <p>
-     * Requires a production class name to be left over once the suffix is stripped, so that the
-     * selection cannot disagree with {@link #productionClassSimpleName(String)}. "CacheTest" matches
-     * the pattern with "Cache" as the leading {@code .+}, yet stripping removes "CacheTest" whole and
-     * leaves nothing to look for.
-     * </p>
-     */
+    /// Whether a simple name is the name of a test class.
+    ///
+    /// Requires a production class name to be left over once the suffix is stripped, so that the
+    /// selection cannot disagree with [#productionClassSimpleName(String)]. "CacheTest" matches
+    /// the pattern with "Cache" as the leading `.+`, yet stripping removes "CacheTest" whole and
+    /// leaves nothing to look for.
     public static boolean isTestClassName(String simpleName) {
         return simpleName.matches(testClassNameRegex())
                 && !productionClassSimpleName(simpleName).isEmpty();
     }
 
-    /**
-     * The simple name of the production class a test class belongs to, e.g. {@code WidgetCacheTest}
-     * to {@code Widget}.
-     */
+    /// The simple name of the production class a test class belongs to, e.g. `WidgetCacheTest`
+    /// to `Widget`.
     public static String productionClassSimpleName(String testClassSimpleName) {
         return testClassSimpleName.replaceAll(suffixRegex(), "");
     }
 
-    /**
-     * Selects test classes by their <em>simple</em> name. Matching the simple name rather than the
-     * fully qualified name keeps the selection and the conditions that follow it in agreement:
-     * {@code some.pkg.Test} matches the fully qualified name but is not a test class.
-     */
+    /// Selects test classes by their *simple* name. Matching the simple name rather than the
+    /// fully qualified name keeps the selection and the conditions that follow it in agreement:
+    /// `some.pkg.Test` matches the fully qualified name but is not a test class.
     public static DescribedPredicate<JavaClass> testClasses() {
         return new DescribedPredicate<>("have a simple name matching '%s'".formatted(testClassNameRegex())) {
             @Override
@@ -81,11 +66,9 @@ public boolean test(JavaClass javaClass) {
         };
     }
 
-    /*
-     * Longest suffix first, then alphabetically. TEST_CLASS_SUFFIXES is a mutable HashSet, so
-     * without an explicit order the generated regex - and every rule description built from it -
-     * varies between JVM runs.
-     */
+    /// Longest suffix first, then alphabetically. TEST_CLASS_SUFFIXES is a mutable HashSet, so
+    /// without an explicit order the generated regex - and every rule description built from it -
+    /// varies between JVM runs.
     private static String suffixAlternation() {
         var longestFirst = Comparator.<String>comparingInt(String::length)
                 .reversed()

src/test/java/it/aboutbits/archunit/fixture/barren/PlainClass.java

@@ -2,10 +2,8 @@
 
 import org.jspecify.annotations.NullMarked;
 
-/**
- * A codebase with no test classes, no records, no controllers and no stores. Used to pin that a rule
- * whose selection comes up empty fails instead of reporting success.
- */
+/// A codebase with no test classes, no records, no controllers and no stores. Used to pin that a rule
+/// whose selection comes up empty fails instead of reporting success.
 @NullMarked
 public class PlainClass {
     public String value() {

src/test/java/it/aboutbits/archunit/fixture/blacklistannotations/badctorparam/AnnotatedConstructorParameter.java

@@ -1,6 +1,6 @@
 package it.aboutbits.archunit.fixture.blacklistannotations.badctorparam;
 
-/** The canonical Lombok position, and the one a rule iterating only getMethods() cannot see. */
+/// The canonical Lombok position, and the one a rule iterating only getMethods() cannot see.
 public class AnnotatedConstructorParameter {
     private final String value;