Add Javadoc

web/src/main/java/org/springframework/security/web/util/matcher/RequestMatcher.java

@@ -38,7 +38,12 @@ public interface RequestMatcher {
 	boolean matches(HttpServletRequest request);
 
 	/**
-	 * @since 5.2
+	 * Returns a MatchResult for this RequestMatcher
+	 * The default implementation returns  {@link Collections#emptyMap()}
+	 * when {@link MatchResult#getVariables()} is invoked.
+	 *
+	 * @return the MatchResult from comparing this RequestMatcher against the HttpServletRequest
+ 	 * @since 5.2
 	 */
 	default MatchResult matcher(HttpServletRequest request) {
 		boolean match = matches(request);
@@ -46,7 +51,10 @@ public interface RequestMatcher {
 	}
 
 	/**
-	 * The result of matching
+	 * The result of matching against an HttpServletRequest
+	 * Contains the status, true or false, of the match and
+	 * if present, any variables extracted from the match
+	 * @since 5.2
 	 */
 	class MatchResult {
 		private final boolean match;
@@ -57,10 +65,18 @@ public interface RequestMatcher {
 			this.variables = variables;
 		}
 
+		/**
+		 * @return true if the comparison against the HttpServletRequest produced a successful match
+		 */
 		public boolean isMatch() {
 			return this.match;
 		}
 
+		/**
+		 * Returns the extracted variable values where the key is the variable name and the value is the variable value
+		 *
+		 * @return a map containing key-value pairs representing extracted variable names and variable values
+		 */
 		public Map<String, String> getVariables() {
 			return this.variables;
 		}