OpenRewrite recipe best practices

Co-authored-by: Moderne <team@moderne.io>

Author: timtebeek

src/main/resources/META-INF/rewrite/examples.yml

@@ -493,11 +493,8 @@ void test(Set<Locale> localeSet) {
         );
     }
 
-    /**
-     * Chained AssertJ assertions should be simplified to the corresponding dedicated assertion, as
-     * per <a
-     * href="https://next.sonarqube.com/sonarqube/coding_rules?open=java%3AS5838&rule_key=java%3AS5838">java:S5838</a>
-     */
+    /// Chained AssertJ assertions should be simplified to the corresponding dedicated assertion, as
+    /// per <a href="https://next.sonarqube.com/sonarqube/coding_rules?open=java%3AS5838&rule_key=java%3AS5838">java:S5838</a>
     @Nested
     class SonarDedicatedAssertions {
         private static Stream<Arguments> replacements() {

src/test/java/org/openrewrite/java/testing/assertj/AssertJBestPracticesTest.java

@@ -388,10 +388,8 @@ NullPointerException exception() {
         );
     }
 
-    /**
-     * A degenerate case showing we don't perform the conversion when the <code>assertThrows</code> appears
-     * immediately inside a J.Lambda.
-     */
+    /// A degenerate case showing we don't perform the conversion when the `assertThrows` appears
+    /// immediately inside a J.Lambda.
     @Test
     void assertThrowsConsumerUsage() {
         //language=java
@@ -414,10 +412,8 @@ public void throwsExceptionWithSpecificType() {
         );
     }
 
-    /**
-     * A degenerate case showing we don't perform the conversion when the <code>assertThrows</code> appears
-     * immediately inside a J.Lambda.
-     */
+    /// A degenerate case showing we don't perform the conversion when the `assertThrows` appears
+    /// immediately inside a J.Lambda.
     @Test
     void assertThrowsSupplierUsage() {
         //language=java

src/test/java/org/openrewrite/java/testing/assertj/JUnitAssertThrowsToAssertExceptionTypeTest.java

@@ -25,11 +25,9 @@
 import static org.openrewrite.java.Assertions.java;
 import static org.openrewrite.java.testing.jmockit.JMockitTestUtils.setDefaultParserSettings;
 
-/**
- * At the moment, JMockit Delegates are not migrated to mockito. What I'm seeing is that they are being trashed
- * with the template being printed out. These tests were written to try to replicate this issue, however I was unable to.
- * They may help anyone who wants to add Delegate migration.
- */
+/// At the moment, JMockit Delegates are not migrated to mockito. What I'm seeing is that they are being trashed
+/// with the template being printed out. These tests were written to try to replicate this issue, however I was unable to.
+/// They may help anyone who wants to add Delegate migration.
 @Disabled
 @Issue("https://github.com/openrewrite/rewrite-testing-frameworks/issues/522")
 @SuppressWarnings("ResultOfMethodCallIgnored")

src/test/java/org/openrewrite/java/testing/jmockit/JMockitDelegateToMockitoTest.java

@@ -23,9 +23,7 @@
 import static org.openrewrite.java.Assertions.java;
 import static org.openrewrite.java.testing.jmockit.JMockitTestUtils.setDefaultParserSettings;
 
-/**
- * Not doing comprehensive testing as it is covered in JMockitVerificationsToMockitoTest and shares same code path
- */
+/// Not doing comprehensive testing as it is covered in JMockitVerificationsToMockitoTest and shares same code path
 @SuppressWarnings("SpellCheckingInspection")
 class JMockitFullVerificationsToMockitoTest implements RewriteTest {
 

src/test/java/org/openrewrite/java/testing/jmockit/JMockitFullVerificationsToMockitoTest.java

@@ -24,9 +24,7 @@
 import static org.openrewrite.java.Assertions.java;
 import static org.openrewrite.java.testing.jmockit.JMockitTestUtils.setDefaultParserSettings;
 
-/**
- * Not doing full testing of VerificationsInOrder as it is covered in JMockitVerificationsToMockitoTest
- */
+/// Not doing full testing of VerificationsInOrder as it is covered in JMockitVerificationsToMockitoTest
 class JMockitVerificationsInOrderToMockitoTest implements RewriteTest {
 
     @Override

src/test/java/org/openrewrite/java/testing/jmockit/JMockitVerificationsInOrderToMockitoTest.java

@@ -940,12 +940,10 @@ void test() {
         );
     }
 
-    /**
-     * The bug this test is reproducing is likely not specific to the JUnit5 upgrade, it's just where it was first
-     * encountered and isolated. It would probably be reproducible using other recipes that reorder method parameters,
-     * provided that a Javadoc link refers to an affected method, and the link has a newline in between the parameters.
-     * If that proves to be true, this test should be generalized and moved to the tests of {@code rewrite-java}.
-     */
+    /// The bug this test is reproducing is likely not specific to the JUnit5 upgrade, it's just where it was first
+    /// encountered and isolated. It would probably be reproducible using other recipes that reorder method parameters,
+    /// provided that a Javadoc link refers to an affected method, and the link has a newline in between the parameters.
+    /// If that proves to be true, this test should be generalized and moved to the tests of `rewrite-java`.
     @Issue("https://github.com/openrewrite/rewrite/issues/6001")
     @Test
     void correctlyHandleALineBreakInAJavadocLinkThatReferencesAMethodWhoseParametersGetReordered() {

src/test/java/org/openrewrite/java/testing/junit5/JUnit5MigrationTest.java

@@ -25,9 +25,7 @@
 
 import static org.openrewrite.java.Assertions.java;
 
-/**
- * Validates the recipes related to upgrading from Mockito 1 to Mockito 3
- */
+/// Validates the recipes related to upgrading from Mockito 1 to Mockito 3
 @SuppressWarnings({"NotNullFieldNotInitialized", "NewClassNamingConvention"})
 class JunitMockitoUpgradeIntegrationTest implements RewriteTest {
 
@@ -42,9 +40,7 @@ public void defaults(RecipeSpec spec) {
             .activateRecipes("org.openrewrite.java.testing.junit5.JUnit4to5Migration"));
     }
 
-    /**
-     * Replace org.mockito.MockitoAnnotations.Mock with org.mockito.Mock
-     */
+    /// Replace org.mockito.MockitoAnnotations.Mock with org.mockito.Mock
     @DocumentExample
     @Test
     void replaceMockAnnotation() {
@@ -129,10 +125,8 @@ void tearDown() throws Exception {
         );
     }
 
-    /**
-     * Mockito 1 used Matchers.anyVararg() to match the arguments to a variadic function.
-     * Mockito 2+ uses Matchers.any() to match anything including the arguments to a variadic function.
-     */
+    /// Mockito 1 used Matchers.anyVararg() to match the arguments to a variadic function.
+    /// Mockito 2+ uses Matchers.any() to match anything including the arguments to a variadic function.
     @Test
     void replacesAnyVararg() {
         //language=java
@@ -176,11 +170,9 @@ public void usesVarargMatcher() {
         );
     }
 
-    /**
-     * Mockito 1 has InvocationOnMock.getArgumentAt(int, Class)
-     * Mockito 3 has InvocationOnMock.getArgument(int, Class)
-     * swap 'em
-     */
+    /// Mockito 1 has InvocationOnMock.getArgumentAt(int, Class)
+    /// Mockito 3 has InvocationOnMock.getArgument(int, Class)
+    /// swap 'em
     @Test
     void replacesGetArgumentAt() {
         //language=java

src/test/java/org/openrewrite/java/testing/mockito/JunitMockitoUpgradeIntegrationTest.java

@@ -187,11 +187,9 @@ class A {
         );
     }
 
-    /**
-     * End-to-end reproduction of the customer-reported Kotlin files (issue #2437) run through the full
-     * {@code Testcontainers2Migration}, asserting the LocalStack member references are migrated alongside
-     * the type rename so the result compiles against Testcontainers 2.x.
-     */
+    /// End-to-end reproduction of the customer-reported Kotlin files (issue #2437) run through the full
+    /// `Testcontainers2Migration`, asserting the LocalStack member references are migrated alongside
+    /// the type rename so the result compiles against Testcontainers 2.x.
     @Nested
     class FullMigration implements RewriteTest {
 

src/test/java/org/openrewrite/java/testing/testcontainers/Testcontainers2LocalStackTest.java

@@ -31,9 +31,7 @@ public void defaults(RecipeSpec spec) {
           .recipeFromResources("org.openrewrite.java.testing.assertj.Assertj");
     }
 
-    /**
-     * Verify that we can throw new Exception from the JavaTemplate in the generated recipe.
-     */
+    /// Verify that we can throw new Exception from the JavaTemplate in the generated recipe.
     @DocumentExample
     @Test
     void failWithMessage() {
@@ -66,9 +64,7 @@ void test() {
         );
     }
 
-    /**
-     * Verify some assertions as implemented through Refaster rules converted to Recipes. No need to test all variants.
-     */
+    /// Verify some assertions as implemented through Refaster rules converted to Recipes. No need to test all variants.
     @Test
     void assertTrueFalse() {
         rewriteRun(
@@ -141,11 +137,9 @@ void bbb(Object obj) {
         );
     }
 
-    /**
-     * Qualified `Assert.assertX(...)` calls should become static-imported `assertThat(...)`, rather than
-     * mirroring the source qualification as `Assertions.assertThat(...)`; see
-     * <a href="https://github.com/openrewrite/rewrite-testing-frameworks/issues/1029">issue 1029</a>.
-     */
+    /// Qualified `Assert.assertX(...)` calls should become static-imported `assertThat(...)`, rather than
+    /// mirroring the source qualification as `Assertions.assertThat(...)`; see
+    /// <a href="https://github.com/openrewrite/rewrite-testing-frameworks/issues/1029">issue 1029</a>.
     @Test
     void qualifiedAssertBecomesStaticImport() {
         rewriteRun(