[UNDERTOW-2303] Minor improvements to documentation / comments.

Author: dirkroets

core/src/main/java/io/undertow/server/RoutingHandler.java

@@ -223,6 +223,13 @@ public void handleRequest(final HttpServerExchange exchange) throws Exception {
         handleFallback(exchange);
     }
 
+    /**
+     * Gets the builder for the specified HTTP method. A new builder will be created and added for the specified HTTP method if
+     * one wasn't already present, otherwise the existing builder will be returned.
+     *
+     * @param method The HTTP method.
+     * @return The builder.
+     */
     private PathTemplateRouterFactory.Builder<RoutingMatchBuilder, RoutingMatch> getOrAddMethodRouterBuiler(
             final HttpString method
     ) {
@@ -236,6 +243,15 @@ private PathTemplateRouterFactory.Builder<RoutingMatchBuilder, RoutingMatch> get
         return result;
     }
 
+    /**
+     * Gets the builder for the specified HTTP method and URL path template. A new builder will be created and added for the
+     * specified HTTP method and URL path template if one wasn't already present, otherwise the existing builder will be
+     * returned.
+     *
+     * @param method The HTTP method.
+     * @param template The URL path template. See {@link PathTemplateParser#parseTemplate(java.lang.String, java.lang.Object) }.
+     * @return The builder.
+     */
     private RoutingMatchBuilder getOrAddMethodRoutingMatchBuilder(
             final HttpString method,
             final String template
@@ -268,12 +284,25 @@ private Map<HttpString, PathTemplateRouter<RoutingMatch>> createMethodRouters()
         return Collections.unmodifiableMap(result);
     }
 
+    /**
+     * Creates a consumer around the specified builder. The consumer checks if the builder already contains the URL path
+     * template. If the builder does not contain the template, then the template is added to the builder. If the builder already
+     * contains the template, then the builder is left as is to avoid the builder throwing an {@link IllegalArgumentException}.
+     *
+     * @param <A> Target type.
+     * @param builder The builder
+     * @return The consumer.
+     */
     private static <A> Consumer<PathTemplateParser.PathTemplate<A>> createAddTemplateIfAbsentConsumer(
-            final PathTemplateRouterFactory.SimpleBuilder<Object> builder,
-            final Supplier<Object> targetFactory
+            final PathTemplateRouterFactory.SimpleBuilder<Object> builder
     ) {
         Objects.requireNonNull(builder);
-        Objects.requireNonNull(targetFactory);
+
+        /* Creates a dummy factory for targets. The specified builder is only used to determine if a matching template exists
+        for another HTTP method. If it does exist, then an HTTP 405 is returned. If not, then an HTTP 400 is returned. The
+        target itself is therefore never used. */
+        final Object target = new Object();
+        final Supplier<Object> targetFactory = () -> target;
 
         return (final PathTemplateParser.PathTemplate<A> item) -> {
             final String template = item.getPathTemplate();
@@ -289,14 +318,14 @@ private static <A> Consumer<PathTemplateParser.PathTemplate<A>> createAddTemplat
     }
 
     private PathTemplateRouter<Object> createAllMethodsRouter() {
-        final Object target = new Object();
-        final Supplier<Object> targetFactory = () -> target;
         final PathTemplateRouterFactory.SimpleBuilder<Object> builder = PathTemplateRouterFactory.SimpleBuilder
-                .newBuilder(target);
+                .newBuilder(new Object());
+        /* Adds all known patterns from all methods to a single builder in order to distinguish between HTTP 400 and 405 when
+        a requested method / patterns combination could not be found. */
         methodRouterBuilders.values().stream()
-                .flatMap(b -> b.getTemplates().keySet().stream()) //Extract all templates for all methods into a stream
-                .map(PathTemplateParser.PathTemplatePatternEqualsAdapter::getPattern) //Extract the patterns into a stream
-                .forEach(createAddTemplateIfAbsentConsumer(builder, targetFactory));
+                .flatMap(b -> b.getTemplates().keySet().stream()) //Extracts all templates for all methods into a single stream
+                .map(PathTemplateParser.PathTemplatePatternEqualsAdapter::getPattern) //Extracts the patterns into a stream
+                .forEach(createAddTemplateIfAbsentConsumer(builder)); //Adds patterns whilst avoiding adding duplicates
         return builder.build();
     }
 

core/src/main/java/io/undertow/server/handlers/PathTemplateHandler.java

@@ -144,6 +144,7 @@ public String toString() {
             sb.append(templates.get(0).getPattern().getPathTemplate()).append(" )");
         } else {
             sb.append('{').append(
+                    // Creates a ", " separated string of all patterns in this handler.
                     templates.stream().map(s -> s.getPattern().getPathTemplate()).collect(Collectors.joining(", "))
             ).append("} )");
         }

core/src/main/java/io/undertow/util/PathTemplateRouterFactory.java

@@ -824,7 +824,7 @@ private SimpleRouter(
 
         @Override
         public String toString() {
-            return "SimpleRouter{" + '}';
+            return "SimpleRouter{}";
         }
 
         @Override
@@ -976,12 +976,12 @@ private CompositeRouter(
             this.routers = Objects.requireNonNull(routers);
             this.len = this.routers.length;
             this.defaultResult = Objects.requireNonNull(defaultResult);
-            //Find the minimum number of segments in any of the underlying routers
+            //Finds the minimum number of segments in any of the underlying routers.
             this.minSegmentCount = Arrays.stream(routers)
                     .mapToInt(AbstractRouter::getMinSegmentCount)
                     .min()
                     .orElse(Integer.MAX_VALUE);
-            //Find the maximum number of segments in any of the underlying routers
+            //Finds the maximum number of segments in any of the underlying routers.
             this.maxSegmentCount = Arrays.stream(routers)
                     .mapToInt(AbstractRouter::getMaxSegmentCount)
                     .max()
@@ -1848,6 +1848,7 @@ public PathTemplateRouter<T> build() {
             }
 
             return new RouterFactory<>(
+                    //Extracts all the URL path templates from the PatternEqualsAdapters and collects these as a set.
                     templates.keySet().stream()
                             .map(PathTemplateParser.PathTemplatePatternEqualsAdapter::getPattern)
                             .collect(Collectors.toSet()),