Ported @InTestsUseEnums from internal repository

Author: roxspring

README.md

@@ -105,6 +105,17 @@ public class ClassUnderTest {
 }
 ```
 
+### 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 +137,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);
 }
 ```
 

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

@@ -0,0 +1,50 @@
+/*
+ * 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}.
+ */
+@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 {};
+}