diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Ascii.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Ascii.java index e6558d6fc..5108d4077 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Ascii.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Ascii.java @@ -24,6 +24,11 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a {@code String} consisting only of ASCII characters (including control characters). + * + * @see WithUtf8Length + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo(String.class) diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/DoubleInRange.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/DoubleInRange.java index fbb08bf7d..1845ada6b 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/DoubleInRange.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/DoubleInRange.java @@ -25,16 +25,20 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** Generates a {@code double} in the specified range. */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({double.class, Double.class}) @ValidateMinMax @PropertyConstraint public @interface DoubleInRange { + /** The minimum value of the range, inclusive. */ double min() default Double.NEGATIVE_INFINITY; + /** The maximum value of the range, inclusive. */ double max() default Double.POSITIVE_INFINITY; + /** Whether NaN is allowed to be generated. */ boolean allowNaN() default true; /** diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Finite.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Finite.java index 716645334..cd35c6f06 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Finite.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Finite.java @@ -24,6 +24,10 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a {@code float} or {@code double} which is finite, that is, a number which is neither + * NaN nor Infinity. + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({float.class, Float.class, double.class, Double.class}) diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/FloatInRange.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/FloatInRange.java index b34dcadde..e9282bca0 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/FloatInRange.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/FloatInRange.java @@ -25,16 +25,20 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** Generates a {@code float} in the specified range. */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({float.class, Float.class}) @ValidateMinMax @PropertyConstraint public @interface FloatInRange { + /** The minimum value of the range, inclusive. */ float min() default Float.NEGATIVE_INFINITY; + /** The maximum value of the range, inclusive. */ float max() default Float.POSITIVE_INFINITY; + /** Whether NaN is allowed to be generated. */ boolean allowNaN() default true; /** diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/InRange.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/InRange.java index 001249a30..73924bd69 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/InRange.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/InRange.java @@ -25,6 +25,12 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates an integral number in the specified range. + * + * @see FloatInRange + * @see DoubleInRange + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({ @@ -40,8 +46,10 @@ @ValidateMinMax @PropertyConstraint public @interface InRange { + /** The minimum value of the range, inclusive. */ long min() default Long.MIN_VALUE; + /** The maximum value of the range, inclusive. */ long max() default Long.MAX_VALUE; /** diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Negative.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Negative.java index 0cc5fe857..00e67b7dc 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Negative.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Negative.java @@ -24,6 +24,11 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a negative number, that is, a number {@literal <} 0. + * + *

For {@code float} and {@code double} this does not include -0.0 or NaN. + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({ diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonNegative.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonNegative.java index 128660261..9fd0b23f8 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonNegative.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonNegative.java @@ -24,6 +24,11 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a non-negative number, that is, a number >= 0. + * + *

For {@code float} and {@code double} this does not include NaN. + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({ diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonPositive.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonPositive.java index 65da76ae3..3a73d536d 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonPositive.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NonPositive.java @@ -24,6 +24,11 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a non-positive number, that is, a number {@literal <=} 0. + * + *

For {@code float} and {@code double} this does not include NaN. + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({ diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NotNull.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NotNull.java index 440caa7e2..7b82a8381 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NotNull.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/NotNull.java @@ -25,6 +25,10 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a not-{@code null} value. By default the mutation framework can generate {@code null} + * for objects (including arrays). + */ @Target({PARAMETER, TYPE_USE}) @Retention(RUNTIME) @AppliesTo(subClassesOf = Object.class) diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Positive.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Positive.java index 4a0695449..367557ac4 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Positive.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/Positive.java @@ -24,6 +24,11 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates a positive number, that is, a number > 0. + * + *

For {@code float} and {@code double} this does not include NaN. + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({ diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithLength.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithLength.java index 6dd7c4ffb..dd89cfdf9 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithLength.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithLength.java @@ -25,6 +25,12 @@ import java.lang.annotation.Retention; import java.lang.annotation.Target; +/** + * Generates an array of the specified length. + * + * @see WithSize + * @see WithUtf8Length + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo( @@ -42,8 +48,10 @@ @ValidateContainerDimensions @PropertyConstraint public @interface WithLength { + /** The minimum length, inclusive. */ int min() default 0; + /** The maximum length, inclusive. */ int max() default 1000; /** diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithSize.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithSize.java index e8e72888a..5d735158b 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithSize.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithSize.java @@ -27,14 +27,22 @@ import java.util.List; import java.util.Map; +/** + * Generates a {@link List} or {@link Map} with the specified size. + * + * @see WithLength + * @see WithUtf8Length + */ @Target(TYPE_USE) @Retention(RUNTIME) @AppliesTo({List.class, Map.class}) @ValidateContainerDimensions @PropertyConstraint public @interface WithSize { + /** The minimum size, inclusive. */ int min() default 0; + /** The maximum size, inclusive. */ int max() default 1000; /** diff --git a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java index ccc2bccc5..3139a4cf3 100644 --- a/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java +++ b/src/main/java/com/code_intelligence/jazzer/mutation/annotation/WithUtf8Length.java @@ -44,8 +44,10 @@ @ValidateContainerDimensions @PropertyConstraint public @interface WithUtf8Length { + /** The minimum length of the UTF-8 encoding, inclusive. */ int min() default 0; + /** The maximum length of the UTF-8 encoding, inclusive. */ int max() default 1000; /**