refactor: revise function callback API deprecation messages and documentation

- Update deprecated annotation messages to correctly reference functions() instead of function()
- Add detailed documentation for FunctionCallback.Builder hierarchy
- Deprecate FunctionCallbackWrapper class in favor of Builder pattern
- Fix typos and improve code documentation

Author: tzolov

spring-ai-core/src/main/java/org/springframework/ai/chat/client/ChatClient.java

@@ -213,14 +213,14 @@ interface ChatClientRequestSpec {
 		<T extends ChatOptions> ChatClientRequestSpec options(T options);
 
 		/**
-		 * @deprecated use {@link #function(FunctionCallback)} instead.
+		 * @deprecated use {@link #functions(FunctionCallback...)} instead.
 		 */
 		@Deprecated
 		<I, O> ChatClientRequestSpec function(String name, String description,
 				java.util.function.Function<I, O> function);
 
 		/**
-		 * @deprecated use {@link #function(FunctionCallback)} instead.
+		 * @deprecated use {@link #functions(FunctionCallback...)} instead.
 		 */
 		@Deprecated
 		<I, O> ChatClientRequestSpec function(String name, String description,
@@ -229,7 +229,7 @@ <I, O> ChatClientRequestSpec function(String name, String description,
 		<I, O> ChatClientRequestSpec functions(FunctionCallback... functionCallbacks);
 
 		/**
-		 * @deprecated use {@link #function(FunctionCallback)} instead.
+		 * @deprecated use {@link #functions(FunctionCallback...)} instead.
 		 */
 		@Deprecated
 		<I, O> ChatClientRequestSpec function(String name, String description, Class<I> inputType,
@@ -291,13 +291,13 @@ interface Builder {
 		Builder defaultSystem(Consumer<PromptSystemSpec> systemSpecConsumer);
 
 		/**
-		 * @deprecated use {@link #defaultFunction(FunctionCallback)} instead.
+		 * @deprecated use {@link #defaultFunctions(FunctionCallback...)} instead.
 		 */
 		@Deprecated
 		<I, O> Builder defaultFunction(String name, String description, java.util.function.Function<I, O> function);
 
 		/**
-		 * @deprecated use {@link #defaultFunction(FunctionCallback)} instead.
+		 * @deprecated use {@link #defaultFunctions(FunctionCallback...)} instead.
 		 */
 		@Deprecated
 		<I, O> Builder defaultFunction(String name, String description,

spring-ai-core/src/main/java/org/springframework/ai/model/function/FunctionCallback.java

@@ -82,13 +82,22 @@ default String call(String functionInput, ToolContext tooContext) {
 
 	/**
 	 * Creates a new {@link FunctionCallback.Builder} instance used to build a default
-	 * {@link FunctionCallback} instance. *
+	 * {@link FunctionCallback} instance.
 	 * @return Returns a new {@link FunctionCallback.Builder} instance.
 	 */
 	static FunctionCallback.Builder builder() {
 		return new DefaultFunctionCallbackBuilder();
 	}
 
+	/**
+	 * Builder for creating a {@link FunctionCallback} instance. This is a hierarchical
+	 * builder with the following structure:
+	 * <ul>
+	 * <li>{@link Builder} - The root builder interface.
+	 * <li>{@link FunctionInvokingSpec} - The function invoking builder interface.
+	 * <li>{@link MethodInvokingSpec} - The method invoking builder interface.
+	 * </ul>
+	 */
 	interface Builder {
 
 		/**
@@ -122,14 +131,26 @@ interface Builder {
 		 */
 		Builder objectMapper(ObjectMapper objectMapper);
 
+		/**
+		 * Builds a {@link Function} invoking {@link FunctionCallback} instance.
+		 */
 		<I, O> FunctionInvokingSpec<I, O> function(String name, Function<I, O> function);
 
+		/**
+		 * Builds a {@link BiFunction} invoking {@link FunctionCallback} instance.
+		 */
 		<I, O> FunctionInvokingSpec<I, O> function(String name, BiFunction<I, ToolContext, O> biFunction);
 
+		/**
+		 * Builds a {@link Method} invoking {@link FunctionCallback} instance.
+		 */
 		MethodInvokingSpec method(String methodName, Class<?>... argumentTypes);
 
 	}
 
+	/**
+	 * {@link Function} invoking builder interface.
+	 */
 	interface FunctionInvokingSpec<I, O> {
 
 		/**
@@ -152,6 +173,9 @@ interface FunctionInvokingSpec<I, O> {
 
 	}
 
+	/**
+	 * {@link Method} invoking builder interface.
+	 */
 	interface MethodInvokingSpec {
 
 		/**

spring-ai-core/src/main/java/org/springframework/ai/model/function/FunctionCallbackWrapper.java

@@ -39,7 +39,9 @@
  *
  * @author Christian Tzolov
  * @author Sebastien Deleuze
+ * @deprecated in favor of {@link FunctionCallbackWrapper.Builder}
  */
+@Deprecated
 public final class FunctionCallbackWrapper<I, O> extends AbstractFunctionCallback<I, O> {
 
 	private final BiFunction<I, ToolContext, O> biFunction;
@@ -57,15 +59,15 @@ public O apply(I input, ToolContext context) {
 	}
 
 	/**
-	 * @deprecated use {@link FunctionCallback#builder(BiFunction)} instead.
+	 * @deprecated use {@link FunctionCallback#builder()} instead.
 	 */
 	@Deprecated
 	public static <I, O> Builder<I, O> builder(BiFunction<I, ToolContext, O> biFunction) {
 		return new Builder<>(biFunction);
 	}
 
 	/**
-	 * @deprecated use {@link FunctionCallback#builder(Function)} instead.
+	 * @deprecated use {@link FunctionCallback#builder()} instead.
 	 */
 	@Deprecated
 	public static <I, O> Builder<I, O> builder(Function<I, O> function) {