From e1c5dc0e66a17e3375ea04829e77137f4a47db9a Mon Sep 17 00:00:00 2001
From: Josh Cummings <josh.cummings@gmail.com>
Date: Fri, 22 Mar 2024 10:36:49 -0600
Subject: [PATCH] Polish JavaDoc

Issue gh-14597
---
 .../AuthorizationAdvisorProxyFactory.java     | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationAdvisorProxyFactory.java b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationAdvisorProxyFactory.java
index e73cc7bef1c..42248b3da26 100644
--- a/core/src/main/java/org/springframework/security/authorization/method/AuthorizationAdvisorProxyFactory.java
+++ b/core/src/main/java/org/springframework/security/authorization/method/AuthorizationAdvisorProxyFactory.java
@@ -195,9 +195,30 @@ public void setAdvisors(Collection<AuthorizationAdvisor> advisors) {
 	 *
 	 * <pre>
 	 * 	AuthorizationAdvisorProxyFactory proxyFactory = new AuthorizationAdvisorProxyFactory();
-	 * 	proxyFactory.setTargetVisitor(AuthorizationAdvisorProxyFactory.DEFAULT_VISITOR_IGNORE_VALUE_TYPES);
+	 * 	proxyFactory.setTargetVisitor(TargetVisitor.defaultsSkipValueTypes());
+	 * </pre>
+	 *
+	 * <p>
+	 * The default {@link TargetVisitor} proxies {@link Class} instances as well as
+	 * instances contained in reactive types (if reactor is present), collection types,
+	 * and other container types like {@link Optional} and {@link Supplier}.
+	 *
+	 * <p>
+	 * If you want to add support for another container type, you can do so in the
+	 * following way:
+	 *
+	 * <pre>
+	 * 	TargetVisitor functions = (factory, target) -> {
+	 *		if (target instanceof Function function) {
+	 *			return (input) -> factory.proxy(function.apply(input));
+	 *		}
+	 *		return null;
+	 * 	};
+	 * 	AuthorizationAdvisorProxyFactory proxyFactory = new AuthorizationAdvisorProxyFactory();
+	 * 	proxyFactory.setTargetVisitor(TargetVisitor.of(functions, TargetVisitor.defaultsSkipValueTypes()));
 	 * </pre>
 	 * @param visitor the visitor to use to introduce specialized behavior for a type
+	 * @see TargetVisitor#defaults
 	 */
 	public void setTargetVisitor(TargetVisitor visitor) {
 		Assert.notNull(visitor, "delegate cannot be null");
@@ -260,6 +281,17 @@ static TargetVisitor defaultsSkipValueTypes() {
 			return AuthorizationAdvisorProxyFactory.DEFAULT_VISITOR_SKIP_VALUE_TYPES;
 		}
 
+		/**
+		 * Compose a set of visitors. This is helpful when you are customizing for a given
+		 * type and still want the defaults applied for the remaining types.
+		 *
+		 * <p>
+		 * The resulting visitor will execute the first visitor that returns a non-null
+		 * value.
+		 * @param visitors the set of visitors
+		 * @return a composite that executes the first visitor that returns a non-null
+		 * value
+		 */
 		static TargetVisitor of(TargetVisitor... visitors) {
 			return (proxyFactory, target) -> {
 				for (TargetVisitor visitor : visitors) {