Polish

spring-web/src/main/java/org/springframework/http/server/PathContainer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2019 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,27 +21,26 @@
 import org.springframework.util.MultiValueMap;
 
 /**
- * Structured representation of a URI path whose elements have been pre-parsed
- * into a sequence of {@link Separator Separator} and {@link PathSegment
- * PathSegment} elements.
+ * Structured representation of a URI path parsed via {@link #parsePath(String)}
+ * into a sequence of {@link Separator} and {@link PathSegment} elements.
  *
- * <p>An instance of this class can be created via {@link #parsePath(String)}.
- * Each {@link PathSegment PathSegment} exposes its structure decoded
- * safely without the risk of encoded reserved characters altering the path or
- * segment structure and without path parameters for path matching purposes.
+ * <p>Each {@link PathSegment} exposes its content in decoded form and with path
+ * parameters removed. This makes it safe to match one path segment at a time
+ * without the risk of decoded reserved characters altering the structure of
+ * the path.
  *
  * @author Rossen Stoyanchev
  * @since 5.0
  */
 public interface PathContainer {
 
 	/**
-	 * The original (raw, encoded) path that this instance was parsed from.
+	 * The original path from which this instance was parsed.
 	 */
 	String value();
 
 	/**
-	 * The list of path elements, either {@link Separator} or {@link PathSegment}.
+	 * The contained path elements, either {@link Separator} or {@link PathSegment}.
 	 */
 	List<Element> elements();
 
@@ -55,8 +54,8 @@ default PathContainer subPath(int index) {
 	}
 
 	/**
-	 * Extract a sub-path from the given start offset (inclusive) into the
-	 * element list and to the end offset (exclusive).
+	 * Extract a sub-path from the given start offset into the element list
+	 * (inclusive) and to the end offset (exclusive).
 	 * @param startIndex the start element index (inclusive)
 	 * @param endIndex the end element index (exclusive)
 	 * @return the sub-path
@@ -78,12 +77,12 @@ static PathContainer parsePath(String path) {
 
 
 	/**
-	 * Common representation of a path element, e.g. separator or segment.
+	 * A path element, either separator or path segment.
 	 */
 	interface Element {
 
 		/**
-		 * Return the original (raw, encoded) value of this path element.
+		 * The unmodified, original value of this element.
 		 */
 		String value();
 	}
@@ -102,19 +101,17 @@ interface Separator extends Element {
 	interface PathSegment extends Element {
 
 		/**
-		 * Return the path segment value to use for pattern matching purposes.
-		 * By default this is the same as {@link #value()} but may also differ
-		 * in sub-interfaces (e.g. decoded, sanitized, etc.).
+		 * Return the path segment value, decoded and sanitized, for path matching.
 		 */
 		String valueToMatch();
 
 		/**
-		 * The same as {@link #valueToMatch()} but as a {@code char[]}.
+		 * Expose {@link #valueToMatch()} as a character array.
 		 */
 		char[] valueToMatchAsChars();
 
 		/**
-		 * Path parameters parsed from the path segment.
+		 * Path parameters associated with this path segment.
 		 */
 		MultiValueMap<String, String> parameters();
 	}

spring-web/src/main/java/org/springframework/web/util/pattern/PathPattern.java

@@ -352,7 +352,7 @@ public int compareTo(@Nullable PathPattern otherPattern) {
 	}
 
 	/**
-	 * Combine this pattern with another. Currently does not produce a new PathPattern, just produces a new string.
+	 * Combine this pattern with another.
 	 */
 	public PathPattern combine(PathPattern pattern2string) {
 		// If one of them is empty the result is the other. If both empty the result is ""