build: fix some javadoc warnings and errors

Author: jknack

etc/javadoc.sh

@@ -2,4 +2,4 @@
 
 DIR=$(cd "$(dirname "$0")"; pwd)
 
-mvn javadoc:javadoc -P source -Dmaven.plugin.validation=VERBOSE
+mvn javadoc:javadoc -P source -Dmaven.plugin.validation=VERBOSE -Dmaven.javadoc.failOnError=true -Dmaven.javadoc.failOnWarnings=true

jooby/src/main/java/io/jooby/ForwardingContext.java

@@ -41,6 +41,11 @@ public class ForwardingContext implements Context {
   public static class ForwardingBody implements Body {
     protected final Body delegate;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param body Underlying body.
+     */
     public ForwardingBody(Body body) {
       this.delegate = body;
     }
@@ -322,6 +327,11 @@ public Map<String, String> toMap() {
   public static class ForwardingValue implements Value {
     protected final Value delegate;
 
+    /**
+     * Creates a new instance.
+     *
+     * @param delegate Underlying value.
+     */
     public ForwardingValue(Value delegate) {
       this.delegate = delegate;
     }
@@ -561,6 +571,11 @@ public Map<String, String> toMap() {
 
   /** Forwarding/Delegate pattern over {@link QueryString}. */
   public static class ForwardingQueryString extends ForwardingValue implements QueryString {
+    /**
+     * Creates a new instance.
+     *
+     * @param queryString Underlying query string.
+     */
     public ForwardingQueryString(QueryString queryString) {
       super(queryString);
     }
@@ -578,6 +593,11 @@ public String queryString() {
 
   /** Forwarding/Delegate pattern over {@link Formdata}. */
   public static class ForwardingFormdata extends ForwardingValue implements Formdata {
+    /**
+     * Creates a new instance.
+     *
+     * @param delegate Underlying formdata.
+     */
     public ForwardingFormdata(Formdata delegate) {
       super(delegate);
     }
@@ -640,6 +660,11 @@ public Context setUser(@Nullable Object user) {
     return this;
   }
 
+  /**
+   * Get the underlying context.
+   *
+   * @return Get the underlying context.
+   */
   public Context getDelegate() {
     return ctx;
   }

jooby/src/main/java/io/jooby/Jooby.java

@@ -783,6 +783,13 @@ public ServiceRegistry getServices() {
     return basePackage;
   }
 
+  /**
+   * Set the base package, it has no direct effect on how jooby works but some modules might use it
+   * for package scanning. Defaults is main application package.
+   *
+   * @param basePackage Application base package.
+   * @return This instance.
+   */
   public Jooby setBasePackage(@Nullable String basePackage) {
     this.basePackage = basePackage;
     return this;

jooby/src/main/java/io/jooby/LoggingService.java

@@ -62,6 +62,7 @@ public interface LoggingService {
    * @param classLoader Class loader to use.
    * @param names Actives environment names. Useful for choosing an environment specific logging
    *     configuration file.
+   * @return Location of logging configuration file or <code>null</code>.
    */
   static @Nullable String configure(@NonNull ClassLoader classLoader, @NonNull List<String> names) {
     // Supported well-know implementation
@@ -133,6 +134,12 @@ public interface LoggingService {
     return null;
   }
 
+  /**
+   * True when path contains one of: <code>target, build, bin</code> directories.
+   *
+   * @param path Path to test.
+   * @return True when path contains one of: <code>target, build, bin</code> directories.
+   */
   static boolean isBinary(Path path) {
     var bin = Set.of("target", "build", "bin");
     return StreamSupport.stream(path.spliterator(), false)

jooby/src/main/java/io/jooby/MapModelAndView.java

@@ -12,6 +12,7 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/** A {@link ModelAndView} which uses a map as model. */
 public class MapModelAndView extends ModelAndView<Map<String, Object>> {
   /**
    * Creates a new model and view.

jooby/src/main/java/io/jooby/OpenAPIModule.java

@@ -41,11 +41,11 @@ public class OpenAPIModule implements Extension {
 
   private static class OpenAPIAsset implements Asset {
 
-    private long lastModified;
+    private final long lastModified;
 
-    private byte[] content;
+    private final byte[] content;
 
-    private MediaType type;
+    private final MediaType type;
 
     OpenAPIAsset(MediaType type, byte[] content, long lastModified) {
       this.content = content;
@@ -68,7 +68,7 @@ public boolean isDirectory() {
       return false;
     }
 
-    @NonNull @Override
+    @Override
     public MediaType getContentType() {
       return type;
     }
@@ -107,6 +107,12 @@ public enum Format {
     /** YAML. */
     YAML;
 
+    /**
+     * Find format based on files extension.
+     *
+     * @param filePath File name.
+     * @return File format.
+     */
     public static Format from(@NonNull String filePath) {
       for (Format value : values()) {
         if (filePath.endsWith("." + value.name().toLowerCase())) {

jooby/src/main/java/io/jooby/ReactiveSupport.java

@@ -21,6 +21,8 @@ public class ReactiveSupport {
 
   private static final Route.Filter CONCURRENT = new ConcurrentHandler();
 
+  private ReactiveSupport() {}
+
   /**
    * Creates a subscriber from web context.
    *
@@ -41,6 +43,12 @@ public static Route.Filter concurrent() {
     return CONCURRENT;
   }
 
+  /**
+   * Handler for {@link CompletionStage} and {@link Flow.Publisher} result types.
+   *
+   * @param next Next handler in pipeline.
+   * @return A new wrapped route handler.
+   */
   public static Route.Handler concurrent(Route.Handler next) {
     return CONCURRENT.then(next);
   }

jooby/src/main/java/io/jooby/Reified.java

@@ -269,6 +269,7 @@ public static <T> Reified<CompletableFuture<T>> completableFuture(@NonNull Type
    *
    * @param rawType Raw type.
    * @param typeArguments Parameter types.
+   * @param <T> Target type.
    * @return Gets type literal for the parameterized type represented by applying {@code
    *     typeArguments} to {@code rawType}.
    */
@@ -283,6 +284,7 @@ public static <T> Reified<T> getParameterized(
    *
    * @param rawType Raw type.
    * @param argument Parameter types.
+   * @param <T> Target type.
    * @return Gets type literal for the parameterized type represented by applying {@code
    *     typeArguments} to {@code rawType}.
    */

jooby/src/main/java/io/jooby/Route.java

@@ -13,8 +13,6 @@
 import java.lang.reflect.Method;
 import java.util.*;
 import java.util.concurrent.Executor;
-import java.util.function.Consumer;
-import java.util.function.Predicate;
 import java.util.stream.Stream;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
@@ -253,6 +251,10 @@ public interface Complete {
     void apply(@NonNull Context ctx) throws Exception;
   }
 
+  /**
+   * Callback that allow to customize a route while the route pipeline is being created. The {@link
+   * #setRoute(Route)} is called once at application startup time.
+   */
   public interface Aware {
     /**
      * Allows a handler to listen for route metadata.
@@ -277,7 +279,7 @@ public interface Handler extends Serializable, Aware {
      * @return Route response.
      * @throws Exception If something goes wrong.
      */
-    @NonNull Object apply(@NonNull Context ctx) throws Exception;
+    Object apply(@NonNull Context ctx) throws Exception;
 
     /**
      * Chain this after decorator with next and produces a new decorator.
@@ -722,7 +724,7 @@ public boolean isNonBlockingSet() {
    * your application using {@link ExecutionMode#EVENT_LOOP}.
    *
    * @param nonBlocking True for non-blocking routes.
-   * @return
+   * @return This route.
    */
   public Route setNonBlocking(boolean nonBlocking) {
     this.nonBlocking = nonBlocking;
@@ -1176,6 +1178,11 @@ public static class Set implements Iterable<Route> {
 
     private String description;
 
+    /**
+     * Set of routes.
+     *
+     * @param routes Routes.
+     */
     public Set(List<Route> routes) {
       this.routes = routes;
     }
@@ -1384,10 +1391,6 @@ public Set description(@Nullable String description) {
       return setDescription(description);
     }
 
-    public void forEach(Predicate<Route> predicate, Consumer<? super Route> action) {
-      routes.stream().filter(predicate).forEach(action);
-    }
-
     @Override
     public Iterator<Route> iterator() {
       return routes.iterator();

jooby/src/main/java/io/jooby/Router.java

@@ -65,11 +65,18 @@ interface Match {
     /**
      * Executes matched route.
      *
-     * @param context not null.
-     * @param pipeline Handler.
+     * @param context Web Context.
+     * @param pipeline Route pipeline.
+     * @return route response.
      */
     Object execute(@NonNull Context context, @NonNull Route.Handler pipeline);
 
+    /**
+     * Executes matched route.
+     *
+     * @param context Web Context.
+     * @return route response.
+     */
     default Object execute(@NonNull Context context) {
       return execute(context, route().getPipeline());
     }
@@ -202,10 +209,20 @@ default Object execute(@NonNull Context context) {
    *
    * @return Application context path (a.k.a as base path).
    */
-  @NonNull String getContextPath();
+  String getContextPath();
 
+  /**
+   * True when router started.
+   *
+   * @return True when router started.
+   */
   boolean isStarted();
 
+  /**
+   * True when router stopped.
+   *
+   * @return True when router stopped.
+   */
   boolean isStopped();
 
   /**
@@ -450,17 +467,22 @@ default Object execute(@NonNull Context context) {
    * @param worker Default worker thread pool.
    * @return This router.
    */
-  @NonNull Router setDefaultWorker(@NonNull Executor worker);
+  Router setDefaultWorker(@NonNull Executor worker);
 
-  @NonNull OutputFactory getOutputFactory();
+  /**
+   * Output factory.
+   *
+   * @return Output factory.
+   */
+  OutputFactory getOutputFactory();
 
   /**
    * Attach a filter to the route pipeline.
    *
    * @param filter Filter.
    * @return This router.
    */
-  @NonNull Router use(@NonNull Route.Filter filter);
+  Router use(@NonNull Route.Filter filter);
 
   /**
    * Add a before route decorator to the route pipeline.
@@ -841,7 +863,7 @@ default Object execute(@NonNull Context context) {
    *
    * @return Template for the flash cookie.
    */
-  @NonNull Cookie getFlashCookie();
+  Cookie getFlashCookie();
 
   /**
    * Sets a cookie used as a template to generate the flash cookie, allowing to customize the cookie
@@ -850,19 +872,30 @@ default Object execute(@NonNull Context context) {
    * @param flashCookie The cookie template.
    * @return This router.
    */
-  @NonNull Router setFlashCookie(@NonNull Cookie flashCookie);
+  Router setFlashCookie(@NonNull Cookie flashCookie);
 
-  @NonNull ValueFactory getValueFactory();
+  /**
+   * Value factory.
+   *
+   * @return Value factory.
+   */
+  ValueFactory getValueFactory();
 
-  @NonNull Router setValueFactory(@NonNull ValueFactory valueFactory);
+  /**
+   * Set value factory, useful for custom value factory.
+   *
+   * @param valueFactory Value factory.
+   * @return This router.
+   */
+  Router setValueFactory(@NonNull ValueFactory valueFactory);
 
   /**
    * Ensure path start with a <code>/</code>(leading slash).
    *
    * @param path Path to process.
    * @return Path with leading slash.
    */
-  static @NonNull String leadingSlash(@Nullable String path) {
+  static String leadingSlash(@Nullable String path) {
     if (path == null || path.length() == 0 || path.equals("/")) {
       return "/";
     }