Javadoc fixes (#392)

Fixes #377
smallrye · Jan 27, 2025 · 2ab65fa · 2ab65fa
1 parent 3682883
commit 2ab65fa
Show file tree

Hide file tree

Showing 59 changed files with 827 additions and 40 deletions.
diff --git a/annotation/src/main/java/io/smallrye/common/annotation/Identifier.java b/annotation/src/main/java/io/smallrye/common/annotation/Identifier.java
@@ -34,8 +34,17 @@
     final class Literal extends AnnotationLiteral<Identifier> implements Identifier {
         private static final long serialVersionUID = 1L;
 
+        /**
+         * The identifier value.
+         */
         private final String value;
 
+        /**
+         * Construct a new instance.
+         *
+         * @param value the identifier value (must not be {@code null})
+         * @return the annotation literal
+         */
         public static Literal of(String value) {
             return new Literal(value);
         }

diff --git a/annotation/src/main/java/module-info.java b/annotation/src/main/java/module-info.java
@@ -1,3 +1,6 @@
+/**
+ * Common annotations for SmallRye projects and their consumers.
+ */
 module io.smallrye.common.annotation {
     requires static jakarta.cdi;
     requires static jakarta.inject;

diff --git a/classloader/src/main/java/io/smallrye/common/classloader/ClassDefiner.java b/classloader/src/main/java/io/smallrye/common/classloader/ClassDefiner.java
@@ -4,7 +4,23 @@
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 
+/**
+ * A utility to define classes within a target lookup.
+ */
+@SuppressWarnings("removal")
 public class ClassDefiner {
+    private ClassDefiner() {
+    }
+
+    /**
+     * Define a class.
+     *
+     * @param lookup the lookup of the class (must not be {@code null})
+     * @param parent the host class to define the new class to (must not be {@code null})
+     * @param className the name of the new class (must not be {@code null})
+     * @param classBytes the bytes of the new class (must not be {@code null})
+     * @return the defined class (not {@code null})
+     */
     public static Class<?> defineClass(MethodHandles.Lookup lookup, Class<?> parent, String className, byte[] classBytes) {
         SecurityManager sm = System.getSecurityManager();
         if (sm != null) {

diff --git a/classloader/src/main/java/io/smallrye/common/classloader/ClassPathUtils.java b/classloader/src/main/java/io/smallrye/common/classloader/ClassPathUtils.java
@@ -18,10 +18,16 @@
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+/**
+ * Miscellaneous class path related utilities.
+ */
 public class ClassPathUtils {
     private static final String FILE = "file";
     private static final String JAR = "jar";
 
+    private ClassPathUtils() {
+    }
+
     /**
      * Invokes {@link #consumeAsStreams(ClassLoader, String, Consumer)} passing in
      * an instance of the current thread's context classloader as the classloader
@@ -138,6 +144,8 @@ public static void consumeAsPath(URL url, Consumer<Path> consumer) {
      *
      * @param url resource url
      * @param function resource path function
+     * @param <R> the result type
+     * @return the result of the function
      */
     public static <R> R processAsPath(URL url, Function<Path, R> function) {
         if (JAR.equals(url.getProtocol())) {
@@ -233,6 +241,8 @@ public static void consumeStream(URL url, Consumer<InputStream> consumer) throws
      *
      * @param url URL
      * @param function input stream processing function
+     * @param <R> the result type
+     * @return the result of the function
      * @throws IOException in case of an IO failure
      */
     public static <R> R readStream(URL url, Function<InputStream, R> function) throws IOException {

diff --git a/classloader/src/main/java/io/smallrye/common/classloader/DefineClassPermission.java b/classloader/src/main/java/io/smallrye/common/classloader/DefineClassPermission.java
@@ -2,22 +2,40 @@
 
 import java.security.Permission;
 
+/**
+ * A security manager permission which indicates the ability to define a class.
+ */
 public class DefineClassPermission extends Permission {
     private static final long serialVersionUID = 142067672163413424L;
     private static final DefineClassPermission INSTANCE = new DefineClassPermission();
 
+    /**
+     * Construct a new instance.
+     */
     public DefineClassPermission() {
         super("");
     }
 
+    /**
+     * Construct a new instance.
+     *
+     * @param name ignored
+     * @param actions ignored
+     */
     public DefineClassPermission(final String name, final String actions) {
         this();
     }
 
+    /**
+     * {@return the singular instance}
+     */
     public static DefineClassPermission getInstance() {
         return INSTANCE;
     }
 
+    /**
+     * {@return {@code true} if this permission implies the given permission}
+     */
     @Override
     public boolean implies(final Permission permission) {
         return permission != null && permission.getClass() == this.getClass();

diff --git a/classloader/src/main/java/module-info.java b/classloader/src/main/java/module-info.java
@@ -1,3 +1,6 @@
+/**
+ * General class loading related utilities.
+ */
 module io.smallrye.common.classloader {
     exports io.smallrye.common.classloader;
 }
diff --git a/constraint/src/main/java/io/smallrye/common/constraint/Assert.java b/constraint/src/main/java/io/smallrye/common/constraint/Assert.java
@@ -90,6 +90,8 @@ public static CharSequence checkNotEmptyParam(String name, CharSequence value) {
      *
      * @param name the parameter name
      * @param value the parameter value
+     * @param <E> the element type
+     * @param <T> the collection type
      * @return the value that was passed in
      * @throws IllegalArgumentException if the value is empty
      */
@@ -107,6 +109,9 @@ public static <E, T extends Collection<E>> T checkNotEmptyParam(String name, T v
      *
      * @param name the parameter name
      * @param value the parameter value
+     * @param <K> the map key type
+     * @param <V> the map value type
+     * @param <T> the map type
      * @return the value that was passed in
      * @throws IllegalArgumentException if the value is empty
      */
@@ -125,6 +130,7 @@ public static <K, V, T extends Map<K, V>> T checkNotEmptyParam(String name, T va
      * @param name the parameter name
      * @param value the parameter value
      * @return the value that was passed in
+     * @param <T> the element type
      * @throws IllegalArgumentException if the value is empty
      */
     @NotNull
@@ -274,6 +280,12 @@ public static <T extends Comparable<T>> T checkMinimumParameter(String name, T m
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
+     * @param <T> the parameter type
      * @hidden
      */
     public static <T extends Comparable<T>> void checkMinimumParameter$$bridge(String name, T min, T actual)
@@ -298,6 +310,11 @@ public static int checkMinimumParameter(String name, int min, int actual) throws
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMinimumParameter$$bridge(String name, int min, int actual) throws IllegalArgumentException {
@@ -321,6 +338,11 @@ public static int checkMinimumParameterUnsigned(String name, int min, int actual
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMinimumParameterUnsigned$$bridge(String name, int min, int actual) throws IllegalArgumentException {
@@ -344,6 +366,11 @@ public static long checkMinimumParameter(String name, long min, long actual) thr
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMinimumParameter$$bridge(String name, long min, long actual) throws IllegalArgumentException {
@@ -367,6 +394,11 @@ public static long checkMinimumParameterUnsigned(String name, long min, long act
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMinimumParameterUnsigned$$bridge(String name, long min, long actual)
@@ -391,6 +423,11 @@ public static float checkMinimumParameter(String name, float min, float actual)
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMinimumParameter$$bridge(String name, float min, float actual) throws IllegalArgumentException {
@@ -414,6 +451,11 @@ public static double checkMinimumParameter(String name, double min, double actua
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param min the minimum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMinimumParameter$$bridge(String name, double min, double actual) throws IllegalArgumentException {
@@ -439,6 +481,12 @@ public static <T extends Comparable<T>> T checkMaximumParameter(String name, T m
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
+     * @param <T> the parameter type
      * @hidden
      */
     public static <T extends Comparable<T>> void checkMaximumParameter$$bridge(String name, T max, T actual)
@@ -463,6 +511,11 @@ public static int checkMaximumParameter(String name, int max, int actual) throws
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMaximumParameter$$bridge(String name, int max, int actual) throws IllegalArgumentException {
@@ -486,6 +539,11 @@ public static int checkMaximumParameterUnsigned(String name, int max, int actual
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMaximumParameterUnsigned$$bridge(String name, int max, int actual) throws IllegalArgumentException {
@@ -509,6 +567,11 @@ public static long checkMaximumParameter(String name, long max, long actual) thr
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMaximumParameter$$bridge(String name, long max, long actual) throws IllegalArgumentException {
@@ -532,6 +595,11 @@ public static long checkMaximumParameterUnsigned(String name, long max, long act
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMaximumParameterUnsigned$$bridge(String name, long max, long actual)
@@ -556,6 +624,11 @@ public static float checkMaximumParameter(String name, float max, float actual)
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMaximumParameter$$bridge(String name, float max, float actual) throws IllegalArgumentException {
@@ -579,6 +652,11 @@ public static double checkMaximumParameter(String name, double max, double actua
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param max the maximum value
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkMaximumParameter$$bridge(String name, double max, double actual) throws IllegalArgumentException {
@@ -602,6 +680,10 @@ public static int checkPow2Parameter(String name, int actual) throws IllegalArgu
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkPow2Parameter$$bridge(String name, int actual) throws IllegalArgumentException {
@@ -625,6 +707,10 @@ public static long checkPow2Parameter(String name, long actual) throws IllegalAr
     }
 
     /**
+     * Bridge method.
+     *
+     * @param name the parameter name
+     * @param actual the actual parameter value
      * @hidden
      */
     public static void checkPow2Parameter$$bridge(String name, long actual) throws IllegalArgumentException {

diff --git a/constraint/src/main/java/module-info.java b/constraint/src/main/java/module-info.java
@@ -1,3 +1,6 @@
+/**
+ * Constraint checking methods and annotations for SmallRye projects and their consumers.
+ */
 module io.smallrye.common.constraint {
     requires org.jboss.logging;
     requires static org.jboss.logging.annotations;