Merge pull request #2 from diffblue/roxspring/docs-update

@InTestsUseEnums + Docs

Author: roxspring

README.md

@@ -37,21 +37,17 @@ dependencies {
 }
 ```
 
-## Annotations
-
 Annotations placed on packages affect tests for all classes and methods under test in that package.
 Annotations placed on classes affect tests for that class and all it's methods under test, overriding package level annotations.
 Annotations placed on methods affect just that method under test, overriding package and class level annotations.
 
-| Annotation                 | Equivalent `dcover create` option |
-|:---------------------------|:----------------------------------|
-| `@InTestsMock`             | `--mock`, `--disable-mock-inputs` |
-| `@InTestsMockConstruction` | `--mock-construction`             |
-| `@InTestsMockStatic`       | `--mock-static`                   |
-
 The annotations will be respected by Diffblue Cover via both command line and IntelliJ Plugin.
 When used from the command line in conjunction with equivalent options then the command line options take priority over the annotations found.
 
+## Mocking Annotations
+
+Mocking annotations allow fine grained control over what mocking should be preferred when testing.
+
 ### Using `@InTestsMock`
 
 Perhaps you have a method that Diffblue Cover would ordinarily test using an `Integer` but you'd prefer to see it tested using `Mockito.mock(..)`.
@@ -77,6 +73,13 @@ public class ClassUnderTest {
 }
 ```
 
+> [!NOTE]
+> Using `@InTestsMock` has the same effect as, and can be overridden by, Cover CLI command line options:
+>
+> ```
+> dcover create --mock ClassToMock --disable-mock-inputs ClassToForbidMocking
+> ```
+
 ### Using `@InTestsMockConstruction`
 
 Perhaps you have a method that Diffblue Cover is unable to test, and you think it could make more progress using `Mockito.mockConstruction(Random.class)`.
@@ -91,6 +94,13 @@ public class ClassUnderTest {
 }
 ```
 
+> [!NOTE]
+> Note that using `@InTestsMockConstruction` has the same effect as, and can be overridden by, Cover CLI command line option:
+>
+> ```
+> dcover create --mock-construction ClassToMockConstruction
+> ```
+
 ### Using `@InTestsMockStatic`
 
 Perhaps you have a method that Diffblue Cover is unable to test, and you think it could make more progress using `Mockito.mockStatic(UUID.class)`.
@@ -105,6 +115,28 @@ public class ClassUnderTest {
 }
 ```
 
+> [!NOTE]
+> Using `@InTestsMockStatic` has the same effect as, and can be overridden by, Cover CLI command line option:
+>
+> ```
+> dcover create --mock-static ClassToMockStatic
+> ```
+
+## Custom Input Annotations
+
+Custom input annotations allow particular inputs to be recommended to Diffblue Cover when writing tests.
+
+### Using `@InTestsUseEnum`
+
+The `@InTestsUseEnum` annotation allows the user to recommend specific `enum` literal values to use in tests.
+Sometimes this can be useful to control the values used for cosmetic reasons, but it can also be useful when Cover is unable to identify values to cover all cases.
+
+```java
+public static boolean isDateOrTimeBased(@InTestsUseEnums({"SECONDS", "YEARS", "FOREVER"}) ChronoUnit chronoUnit) {
+    return chronoUnit.isDateBased() || chronoUnit.isTimeBased();
+}
+```
+
 ### Using `@InTestsUseClasses`
 
 The `@InTestsUseClasses` annotation allows the user to recommend specific `Class` literal values to use in tests.
@@ -126,9 +158,9 @@ For example the following method is annotated with some genuine examples of song
 ```java
 public static boolean isDayRelatedSongTitle(@InTestsUseStrings({"I Don't Like Mondays", "Here Comes The Weekend"}) String title) {
     return Stream.of(DayOfWeek.values())
-        .map(DayOfWeek::name)
-        .map(String::toLowerCase)
-        .anyMatch(title.toLowerCase()::contains);
+            .map(DayOfWeek::name)
+            .map(String::toLowerCase)
+            .anyMatch(title.toLowerCase()::contains);
 }
 ```
 
@@ -222,6 +254,10 @@ public static boolean isNearPi(@InTestsUseDoubles(Math.PI) float input) {
 }
 ```
 
+## Interesting Value Annotations
+
+Interesting value annotations allow users to promote existing fields and methods to be identified and used in particular roles by Diffblue Cover when writing tests.
+
 ### Using `@InterestingTestFactory`
 
 Indicates the annotated method as a useful factory method for use in tests.

src/main/java/com/diffblue/cover/annotations/InTestsMock.java

@@ -29,6 +29,8 @@
  * #value()}. Without annotation then mocking is assumed to be {@link MockDecision#ALLOWED}, but
  * with annotation then the decision defaults to {@link MockDecision#RECOMMENDED}. The decision can
  * be overridden with an explicit {@link #decision()} value.
+ *
+ * @since Diffblue Cover 2024.04.02
  */
 @Retention(CLASS)
 @Target({PACKAGE, TYPE, METHOD})

src/main/java/com/diffblue/cover/annotations/InTestsMockConstruction.java

@@ -30,6 +30,8 @@
  * MockDecision#ALLOWED}, but with annotation then the decision defaults to {@link
  * MockDecision#RECOMMENDED}. The decision can be overridden with an explicit {@link #decision()}
  * value.
+ *
+ * @since Diffblue Cover 2024.04.02
  */
 @Retention(CLASS)
 @Repeatable(InTestsMockConstruction.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsMockStatic.java

@@ -30,6 +30,8 @@
  * MockDecision#ALLOWED}, but with annotation then the decision defaults to {@link
  * MockDecision#RECOMMENDED}. The decision can be overridden with an explicit {@link #decision()}
  * value.
+ *
+ * @since Diffblue Cover 2024.04.02
  */
 @Retention(CLASS)
 @Repeatable(InTestsMockStatic.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseBytes.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * byte} or {@link Byte}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseBytes.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseCharacters.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * char} or {@link Character}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseCharacters.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseClasses.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@link
  * Class}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseClasses.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseDoubles.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * double} or {@link Double}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseDoubles.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseEnums.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2024 Diffblue Limited.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+package com.diffblue.cover.annotations;
+
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.PACKAGE;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Repeatable;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Identifies values that should be considered when writing tests that require inputs of type {@link
+ * Enum}.
+ *
+ * @since Diffblue Cover 2024.06.01
+ */
+@Retention(RUNTIME)
+@Repeatable(InTestsUseEnums.Repeatable.class)
+public @interface InTestsUseEnums {
+
+  /** Collects multiple {@link InTestsUseEnums} annotations. */
+  @Retention(RUNTIME)
+  @Target({PACKAGE, TYPE, METHOD, PARAMETER})
+  @interface Repeatable {
+
+    /**
+     * @return the repeated {@link InTestsUseEnums} annotations.
+     */
+    InTestsUseEnums[] value();
+  }
+
+  /**
+   * @return {@link String} values that should be tried as names of the annotated enum.
+   */
+  String[] value() default {};
+}

src/main/java/com/diffblue/cover/annotations/InTestsUseFloats.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * float} or {@link Float}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseFloats.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseIntegers.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * int} or {@link Integer}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseIntegers.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseLongs.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * long} or {@link Long}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseLongs.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseShorts.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@code
  * short} or {@link Short}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseShorts.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InTestsUseStrings.java

@@ -27,6 +27,8 @@
 /**
  * Identifies values that should be considered when writing tests that require inputs of type {@link
  * String}.
+ *
+ * @since Diffblue Cover 2024.05.02
  */
 @Retention(RUNTIME)
 @Repeatable(InTestsUseStrings.Repeatable.class)

src/main/java/com/diffblue/cover/annotations/InterestingTestFactory.java

@@ -20,7 +20,11 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-/** Indicates the annotated method as a useful factory method for use in tests. */
+/**
+ * Indicates the annotated method as a useful factory method for use in tests.
+ *
+ * @since Diffblue Cover 2024.05.02
+ */
 @Retention(RUNTIME)
 @Target(METHOD)
 public @interface InterestingTestFactory {}