Java: SK v1 javadoc (#4990)

### Motivation and Context

<!-- Thank you for your contribution to the semantic-kernel repo!
Please help reviewers and future users, providing the following
information:
  1. Why is this change required?
  2. What problem does it solve?
  3. What scenario does it contribute to?
  4. If it fixes an open issue, please link to the issue here.
-->

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [ ] The code builds clean without any errors or warnings
- [ ] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [ ] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example30_ChatWithPrompts.java

@@ -5,7 +5,6 @@ import com.azure.ai.openai.OpenAIClientBuilder;
 import com.azure.core.credential.AzureKeyCredential;
 import com.azure.core.credential.KeyCredential;
 import com.microsoft.semantickernel.Kernel;
-import com.microsoft.semantickernel.ServiceNotFoundException;
 import com.microsoft.semantickernel.chatcompletion.ChatCompletionService;
 import com.microsoft.semantickernel.chatcompletion.ChatHistory;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
@@ -14,7 +13,9 @@ import com.microsoft.semantickernel.plugin.KernelPluginFactory;
 import com.microsoft.semantickernel.samples.plugins.TimePlugin;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateFactory;
+import com.microsoft.semantickernel.services.ServiceNotFoundException;
 import com.microsoft.semantickernel.util.EmbeddedResourceLoader;
+
 import java.io.FileNotFoundException;
 import java.time.ZoneId;
 import java.time.ZonedDateTime;

java/samples/sample-code/src/main/java/com/microsoft/semantickernel/samples/syntaxexamples/Example57_KernelHooks.java

@@ -222,7 +222,7 @@ public class Example57_KernelHooks {
             String result = (String) event.getResult().getResult();
             result = result.replaceAll("[aeiouAEIOU0-9]", "*");
 
-            return new FunctionInvokedEvent<>(
+            return new FunctionInvokedEvent(
                 event.getFunction(),
                 event.getArguments(),
                 new FunctionResult<>(

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/AIService.java

@@ -2,14 +2,21 @@
 package com.microsoft.semantickernel;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
+
 import java.util.Map;
+
 import javax.annotation.Nullable;
 
 /**
- * Marker interface for AI services
+ * Marker interface for AI services. {@code AIService}s are registered with the {@code Kernel} 
+ * and are used to provide access to AI services.
  */
 public interface AIService {
 
+    /**
+     * Gets the attributes of the service.
+     * @return The attributes of the service.
+     */
     Map<String, ContextVariable<?>> getAttributes();
 
     /**
@@ -32,7 +39,7 @@ public interface AIService {
      * Gets the model identifier from the {@code attributes} map.
      *
      * @return The model identifier if it was specified in the service's attributes; otherwise,
-     * null.
+     * {@code null}.
      */
     @Nullable
     default String getModelId() {
@@ -42,7 +49,7 @@ public interface AIService {
     /**
      * Gets the endpoint from the {@code attributes} map.
      *
-     * @return The endpoint if it was specified in the service's attributes; otherwise, null.
+     * @return The endpoint if it was specified in the service's attributes; otherwise, {@code null}.
      */
     @Nullable
     default String getEndpoint() {
@@ -52,19 +59,26 @@ public interface AIService {
     /**
      * Gets the API version from the {@code attributes} map.
      *
-     * @return The API version if it was specified in the service's attributes; otherwise, null.
+     * @return The API version if it was specified in the service's attributes; otherwise, {@code null}.
      */
     @Nullable
     default String getApiVersion() {
         return getAttribute(this, API_VERSION_KEY);
     }
 
+    /**
+     * Gets the service identifier.
+     * @return The service identifier.
+     */
     @Nullable
     String getServiceId();
 
-    /// <summary>
-    /// Gets the specified attribute.
-    /// </summary>
+    /**
+     * Get the named attribute from the service's attributes.
+     * @param service The service to get the attribute from.
+     * @param key The key of the attribute to get.
+     * @return The value of the attribute if it exists; otherwise, {@code null}.
+     */
     @Nullable
     static String getAttribute(AIService service, String key) {
         if (service.getAttributes() != null) {

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/Kernel.java

@@ -10,6 +10,7 @@ import com.microsoft.semantickernel.plugin.KernelPlugin;
 import com.microsoft.semantickernel.services.AIServiceSelection;
 import com.microsoft.semantickernel.services.AIServiceSelector;
 import com.microsoft.semantickernel.services.OrderedAIServiceSelector;
+import com.microsoft.semantickernel.services.ServiceNotFoundException;
 
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -19,22 +20,26 @@ import java.util.function.Function;
 
 import javax.annotation.Nullable;
 
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 
 /**
- * Interface for the semantic kernel.
+ * Provides state for use throughout a Semantic Kernel workload.
+ * <p>
+ * An instance of {@code Kernel} is passed through to every function invocation and service call
+ * throughout the system, providing to each the ability to access shared state and services.
  */
 public class Kernel implements Buildable {
 
-    private static final Logger LOGGER = LoggerFactory.getLogger(Kernel.class);
-
     private final AIServiceSelector serviceSelector;
     private final KernelPluginCollection plugins;
     private final KernelHooks globalKernelHooks;
 
+    /**
+     * Initializes a new instance of {@code Kernel}.
+     * @param serviceSelector The {@code AIServiceSelector} used to query for services available through the kernel.
+     * @param plugins The collection of plugins available through the kernel. If {@code null}, an empty collection will be used.
+     * @param globalKernelHooks The global hooks to be used throughout the kernel. If {@code null}, an empty collection will be used.
+     */
     public Kernel(
         AIServiceSelector serviceSelector,
         @Nullable List<KernelPlugin> plugins,
@@ -49,6 +54,16 @@ public class Kernel implements Buildable {
         this.globalKernelHooks = new KernelHooks(globalKernelHooks);
     }
 
+    /**
+     * Invokes a {@code KernelFunction} function by name.
+     * @param <T> The return type of the function.
+     * @param pluginName The name of the plugin containing the function.
+     * @param functionName The name of the function to invoke.
+     * @return The result of the function invocation.
+     * @throws IllegalArgumentException if the plugin or function is not found.
+     * @see KernelFunction#invokeAsync(Kernel)
+     * @see KernelPluginCollection#getFunction(String, String)
+     */
     @SuppressWarnings({"rawtypes", "unchecked"})
     public <T> FunctionInvocation<T> invokeAsync(
         String pluginName,
@@ -57,42 +72,100 @@ public class Kernel implements Buildable {
         return invokeAsync(function);
     }
 
+    /**
+     * Invokes a {@code KernelFunction}.
+     * @param <T> The return type of the function.
+     * @param function The function to invoke.
+     * @return The result of the function invocation.
+     * @see KernelFunction#invokeAsync(Kernel)
+     */
     public <T> FunctionInvocation<T> invokeAsync(KernelFunction<T> function) {
         return function.invokeAsync(this);
     }
 
-    public void addPlugin(KernelPlugin plugin) {
+    /**
+     * This method is used to add plugins to the kernel after it has been created.
+     * If a plugin with the same name already exists, it will be replaced.
+     * @param plugin The plugin to add.
+     * @return {@code this} kernel with the plugin added.
+     */
+    public Kernel addPlugin(KernelPlugin plugin) {
         plugins.add(plugin);
+        return this;
     }
 
+    /**
+     * Gets the plugin with the specified name.
+     * @param pluginName The name of the plugin to get.
+     * @return The plugin with the specified name, or {@code null} if no such plugin exists.
+     */    
     @Nullable
     public KernelPlugin getPlugin(String pluginName) {
         return plugins.getPlugin(pluginName);
     }
 
+    /**
+     * Gets the plugins that were added to the kernel.
+     * @return The plugins available through the kernel.
+     * @see Kernel#getPlugins()
+     */
+    @SuppressFBWarnings("EI_EXPOSE_REP")
     public List<KernelPlugin> getPlugins() {
         return plugins.getPlugins();
     }
 
+    /**
+     * Gets the function with the specified name from the plugin with the specified name.
+     * @param <T> The return type of the function.
+     * @param pluginName The name of the plugin containing the function.
+     * @param functionName The name of the function to get.
+     * @return The function with the specified name from the plugin with the specified name.
+     * @throws IllegalArgumentException if the plugin or function is not found.
+     * @see KernelPluginCollection#getFunction(String, String)
+     */
     @SuppressWarnings("unchecked")
     public <T> KernelFunction<T> getFunction(String pluginName, String functionName) {
         return (KernelFunction<T>)plugins.getFunction(pluginName, functionName);
     }
 
+    /**
+     * Gets the functions available through the kernel. Functions are collected from all plugins
+     * available through the kernel. 
+     * @return The functions available through the kernel.
+     * @see Kernel#getPlugins()
+     * @see Kernel.Builder#withPlugin(KernelPlugin)
+     */
     public List<KernelFunction<?>> getFunctions() {
         return plugins.getFunctions();
     }
 
+    /**
+     * Get the {@code KernelHooks} used throughout the kernel. 
+     * These {@code KernelHooks} are used in addition to any hooks provided to a function.
+     * @return The {@code KernelHooks} used throughout the kernel.
+     * @see KernelFunction#invokeAsync(Kernel, KernelFunctionArguments, ContextVariableType, InvocationContext)
+     */
+    @SuppressFBWarnings("EI_EXPOSE_REP")
+    public KernelHooks getGlobalKernelHooks() {
+         return globalKernelHooks;
+    }
+
+    /**
+     * Get the AIServiceSelector used to query for services available through the kernel.
+     * @return The AIServiceSelector used to query for services available through the kernel.
+     */
     public AIServiceSelector getServiceSelector() {
         return serviceSelector;
     }
 
-
-    @SuppressFBWarnings("EI_EXPOSE_REP")
-    public KernelHooks getGlobalKernelHooks() {
-        return globalKernelHooks;
-    }
-
+    /**
+     * Get the service of the specified type from the kernel.
+     * @param <T> The type of the service to get.
+     * @param clazz The class of the service to get.
+     * @return The service of the specified type from the kernel.
+     * @throws ServiceNotFoundException if the service is not found.
+     * @see com.microsoft.semantickernel.services.AIServiceSelector#trySelectAIService(Class, KernelFunction, KernelFunctionArguments)
+     */
     public <T extends AIService> T getService(Class<T> clazz) throws ServiceNotFoundException {
         AIServiceSelection<T> selector = serviceSelector
             .trySelectAIService(
@@ -108,11 +181,18 @@ public class Kernel implements Buildable {
         return selector.getService();
     }
 
+    /**
+     * Get the fluent builder for creating a new instance of {@code Kernel}.
+     * @return The fluent builder for creating a new instance of {@code Kernel}.
+     */
     public static Kernel.Builder builder() {
         return new Kernel.Builder();
     }
 
 
+    /**
+     * A fluent builder for creating a new instance of {@code Kernel}.
+     */
     public static class Builder implements SemanticKernelBuilder<Kernel> {
 
         private final Map<Class<? extends AIService>, AIService> services = new HashMap<>();
@@ -120,22 +200,43 @@ public class Kernel implements Buildable {
         @Nullable
         private Function<Map<Class<? extends AIService>, AIService>, AIServiceSelector> serviceSelectorProvider;
 
+        /**
+         * Adds a service to the kernel.
+         * @param <T> The type of the service to add.
+         * @param clazz The class of the service to add.
+         * @param aiService The service to add.
+         * @return {@code this} builder with the service added.
+         */
         public <T extends AIService> Builder withAIService(Class<T> clazz, T aiService) {
             services.put(clazz, aiService);
             return this;
         }
 
+        /**
+         * Adds a plugin to the kernel.
+         * @param plugin The plugin to add.
+         * @return {@code this} builder with the plugin added.
+         */
         public Kernel.Builder withPlugin(KernelPlugin plugin) {
             plugins.add(plugin);
             return this;
         }
 
+        /**
+         * Sets the service selector provider for the kernel.
+         * @param serviceSelector The service selector provider for the kernel.
+         * @return {@code this} builder with the service selector provider set.
+         */
         public Kernel.Builder withServiceSelector(
             Function<Map<Class<? extends AIService>, AIService>, AIServiceSelector> serviceSelector) {
             this.serviceSelectorProvider = serviceSelector;
             return this;
         }
 
+        /**
+         * Builds a new instance of {@code Kernel} with the services and plugins provided.
+         * @return A new instance of {@code Kernel}.
+         */
         @Override
         public Kernel build() {
 

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/KernelContent.java

@@ -1,17 +1,41 @@
 package com.microsoft.semantickernel;
 
 import com.microsoft.semantickernel.orchestration.FunctionResultMetadata;
+
 import javax.annotation.Nullable;
 
+/**
+ * Base class which represents the content returned by an AI service.
+ * @param <T> The type of the content. 
+ */
 public abstract class KernelContent<T extends KernelContent<T>> {
 
+    /*
+     * The inner content representation. Use this to bypass the current
+     * abstraction. The usage of this property is considered "unsafe". 
+     * Use it only if strictly necessary.
+     */
     @Nullable
-    private Object innerContent;
+    private final Object innerContent;
+    
+    /** 
+     * The model ID used to generate the content.
+     */
     @Nullable
     private final String modelId;
-    @Nullable
-    private FunctionResultMetadata metadata;
 
+    /**
+     * The metadata associated with the content.
+     */
+    @Nullable
+    private final FunctionResultMetadata metadata;
+
+    /**
+     * Initializes a new instance of the {@link KernelContent} class.
+     * @param innerContent The inner content representation.
+     * @param modelId The model identifier used to generate the content.
+     * @param metadata The metadata associated with the content.
+     */
     public KernelContent(
         @Nullable
         Object innerContent,
@@ -22,31 +46,40 @@ public abstract class KernelContent<T extends KernelContent<T>> {
     ) {
         this.innerContent = innerContent;
         this.modelId = modelId;
-        if (metadata != null) {
-            this.metadata = metadata;
-        }
-    }
-
-    KernelContent<T> setInnerContent(@Nullable Object innerContent) {
-        this.innerContent = innerContent;
-        return this;
+        this.metadata = metadata;
     }
 
+    /**
+     * Gets the inner content representation.
+     * @return The inner content representation.
+     */
     @Nullable
     public Object getInnerContent() {
         return innerContent;
     }
 
+    /**
+     * Gets the model identifier used to generate the content.
+     * @return The model identifier used to generate the content.
+     */
     @Nullable
     public String getModelId() {
         return modelId;
     }
 
+    /**
+     * Gets the metadata associated with the content.
+     * @return The metadata associated with the content.
+     */
     @Nullable
     public FunctionResultMetadata getMetadata() {
         return metadata;
     }
 
+    /**
+     * Gets the content returned by the AI service.
+     * @return The content.
+     */
     @Nullable
     public abstract String getContent();
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/KernelPluginCollection.java

@@ -13,19 +13,37 @@ import java.util.stream.Collectors;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * A collection of {@link KernelPlugin} instances.
+ */
 class KernelPluginCollection {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(KernelPluginCollection.class);
 
     private final Map<String, KernelPlugin> plugins = new CaseInsensitiveMap<>();
 
+    /**
+     * Initialize a new instance of the {@link KernelPluginCollection} 
+     * class with an empty collection of plugins.
+     */
     KernelPluginCollection() {
     }
 
+    /**
+     * Initialize a new instance of the {@link KernelPluginCollection} 
+     * class from a collection of plugins.
+     */
     KernelPluginCollection(List<KernelPlugin> plugins) {
         plugins.forEach(plugin -> this.plugins.put(plugin.getName(), plugin));
     }
 
+    /**
+     * Gets the function with the given name from the plugin with the given name.
+     * @param pluginName The name of the plugin containing the function.
+     * @param functionName The name of the function to get.
+     * @return The function with the given name from the plugin with the given name.
+     * @throws IllegalArgumentException If the plugin or function is not found.
+     */
     KernelFunction<?> getFunction(String pluginName, String functionName) {
         KernelPlugin plugin = plugins.get(pluginName);
         if (plugin == null) {
@@ -40,12 +58,20 @@ class KernelPluginCollection {
         return function;
     }
 
+    /**
+     * Gets all functions from all plugins.
+     * @return A list of all functions from all plugins.
+     */
     List<KernelFunction<?>> getFunctions() {
         return plugins.values().stream()
             .flatMap(plugin -> plugin.getFunctions().values().stream())
             .collect(Collectors.toList());
     }
 
+    /**
+     * Gets all function metadata from all plugins.
+     * @return A list of all function metadata from all plugins.
+     */
     List<KernelFunctionMetadata<?>> getFunctionsMetadata() {
         return plugins.values().stream()
             .flatMap(plugin -> plugin.getFunctions().values().stream())
@@ -53,14 +79,28 @@ class KernelPluginCollection {
             .collect(Collectors.toList());
     }
 
+    /**
+     * Gets all plugins that were added to the kernel.
+     * @return The plugins available through the kernel.
+     */
     List<KernelPlugin> getPlugins() {
         return new ArrayList<>(plugins.values());
     }
 
+    /**
+     * Gets the plugin with the specified name.
+     * @param pluginName The name of the plugin to get.
+     * @return The plugin with the specified name, or {@code null} if no such plugin exists.
+     */
     KernelPlugin getPlugin(String pluginName) {
         return plugins.get(pluginName);
     }
 
+    /**
+     * Adds a plugin to the collection.
+     * If a plugin with the same name already exists, it will be replaced.
+     * @param plugin The plugin to add.
+     */
     void add(KernelPlugin plugin) {
         if (plugins.containsKey(plugin.getName())) {
             LOGGER.warn("Plugin {} already exists, overwriting existing plugin", plugin.getName());

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/ServiceNotFoundException.java

@@ -1,10 +0,0 @@
-package com.microsoft.semantickernel;
-
-import com.microsoft.semantickernel.exceptions.SKCheckedException;
-
-public class ServiceNotFoundException extends SKCheckedException {
-
-    public ServiceNotFoundException(String s) {
-        super(s);
-    }
-}

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/StreamingKernelContent.java

@@ -1,45 +1,44 @@
 package com.microsoft.semantickernel;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
+
 import java.util.Map;
+
 import javax.annotation.Nullable;
 
-public abstract class StreamingKernelContent<T> {
+/**
+ * Base class which represents the content returned by a streaming AI service.
+ * @param <T> The type of the content. 
+ */
+public abstract class StreamingKernelContent<T extends KernelContent<T>> extends KernelContent<T> {
 
-    /// <summary>
-    /// The inner content representation. Use this to bypass the current abstraction.
-    /// </summary>
-    /// <remarks>
-    /// The usage of this property is considered "unsafe". Use it only if strictly necessary.
-    /// </remarks>
-    @Nullable
-    private final T innerContent;
-
-    /// <summary>
-    /// In a scenario of multiple choices per request, this represents zero-based index of the choice in the streaming sequence
-    /// </summary>
+    /**
+     * In a scenario of multiple choices per request, this represents 
+     * the zero-based index of the choice in the streaming sequence
+     */
     private final int choiceIndex;
 
-    /// <summary>
-    /// The model ID used to generate the content.
-    /// </summary>
-    @Nullable
-    private String modelId;
-
-    /// <summary>
-    /// The metadata associated with the content.
-    /// </summary>
-    @Nullable
-    private final Map<String, ContextVariable<?>> metadata;
-
+    /**
+     * Initializes a new instance of the {@link StreamingKernelContent} class.
+     * @param innerContent The inner content representation.
+     * @param choiceIndex The zero-based index of the choice in the streaming sequence.
+     * @param modelId The model identifier used to generate the content.
+     * @param metadata The metadata associated with the content.
+     */
     protected StreamingKernelContent(
         @Nullable T innerContent,
         int choiceIndex,
         @Nullable String modelId,
         @Nullable Map<String, ContextVariable<?>> metadata) {
-        this.innerContent = innerContent;
+        super(innerContent, modelId, null);
         this.choiceIndex = choiceIndex;
-        this.modelId = modelId;
-        this.metadata = metadata;
+    }
+
+    /**
+     * Gets the zero-based index of the choice in the streaming sequence.
+     * @return The zero-based index of the choice in the streaming sequence.
+     */
+    public int getChoiceIndex() {
+        return choiceIndex;
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/TextAIService.java

@@ -5,5 +5,9 @@ package com.microsoft.semantickernel;
  * Marker interface for Text AI services, typically Chat or Text generation for OpenAI
  */
 public interface TextAIService extends AIService {
+    
+    /**
+     * The maximum number of results per prompt
+     */
     int MAX_RESULTS_PER_PROMPT = 128;
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/Todo.java

@@ -1,5 +1,14 @@
 package com.microsoft.semantickernel;
 
+/**
+ * This is used as a placeholder for methods that are not yet implemented.
+ */
 public class Todo extends RuntimeException {
 
+    /**
+     * Initializes a new instance of the {@link Todo} class.
+     */
+    public Todo() {
+        super("TODO: Implement this method");
+    }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/Verify.java

@@ -3,16 +3,34 @@ package com.microsoft.semantickernel;
 
 import javax.annotation.Nullable;
 
+/**
+ * Provides methods for verifying the state of objects and strings in 
+ * a consistent manner.
+ */
 public class Verify {
 
+    /**
+     * Verifies that the given object is not {@code null}.
+     * @param object The object to verify.
+     */
     public static void notNull(Object object) {
         assert object != null;
     }
 
+    /**
+     * Verifies that the given object is {@code null} or empty.
+     * @param s The String to verify.
+     * @return true if the object is {@code null} or empty; otherwise, false.
+     */
     public static boolean isNullOrEmpty(@Nullable String s) {
         return s == null || s.isEmpty();
     }
 
+    /**
+     * Verifies that the given object is {@code null} or contains only whitespace.
+     * @param s The String to verify.
+     * @return true if the object is {@code null} or whitespace; otherwise, false.
+     */
     public static boolean isNullOrWhiteSpace(String s) {
         return s == null || s.matches("^\\w+$");
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/builders/Buildable.java

@@ -2,7 +2,8 @@
 package com.microsoft.semantickernel.builders;
 
 /**
- * A marker interface for all classes that are buildable, typically via obtaining a builder from
- * {@link com.microsoft.semantickernel.SKBuilders}.
+ * A marker interface for all classes that are buildable. By convention, {@code Buildable}
+ * classes will have a {@code public static Builder builder()} method for obtaining a
+ * {@link SemanticKernelBuilder} for the given class.
  */
 public interface Buildable {}

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/builders/SemanticKernelBuilder.java

@@ -2,10 +2,9 @@
 package com.microsoft.semantickernel.builders;
 
 /**
- * Interface for all builders that create Buildable objects. Typically, these builders can be
- * obtained via {@link com.microsoft.semantickernel.SKBuilders}.
+ * Interface for all builders that create Buildable objects.
  *
- * @param <T>
+ * @param <T> the type of {@code Buildable} to build.
  */
 public interface SemanticKernelBuilder<T extends Buildable> {
 

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/builders/ServiceLoadUtil.java

@@ -11,6 +11,11 @@ import java.util.function.Supplier;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * This class is used for loading services that are not directly referenced
+ * in the code, but are instead loaded using the ServiceLoader pattern.
+ *
+ */
 public class ServiceLoadUtil {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ServiceLoadUtil.class);
@@ -18,6 +23,15 @@ public class ServiceLoadUtil {
     private ServiceLoadUtil() {
     }
 
+    /**
+     * Finds a service loader for the given class and returns a supplier for it.
+     *
+     * @param clazz The class to find a service loader for.
+     * @param <T>   The type of the class to find a service loader for.
+     * @param alternativeClassName The name of the alternative class to load if the service loader
+     *                            is not found.
+     * @return A {@code java.util.function.Supplier} for the service loader.
+     */
     public static <T>
     Supplier<T> findServiceLoader(Class<T> clazz, String alternativeClassName) {
         List<T> services = findAllServiceLoaders(clazz);

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/chatcompletion/AuthorRole.java

@@ -6,9 +6,22 @@ package com.microsoft.semantickernel.chatcompletion;
  */
 public enum AuthorRole {
 
+    /** 
+     * A system message helps set the behavior of the assistant. 
+     */
     SYSTEM("system"),
+    /**
+     * An assistant message is a message generated by the assistant.
+     */
     ASSISTANT("assistant"),
+    /**
+     * A user message is a message generated by the user.
+     */
     USER("user"),
+
+    /**
+     * A tool message is a message generated by a tool.
+     */
     TOOL("tool");
 
     @Override
@@ -18,7 +31,7 @@ public enum AuthorRole {
 
     private final String role;
 
-    AuthorRole(String role) {
+    private AuthorRole(String role) {
         this.role = role;
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/chatcompletion/ChatCompletionService.java

@@ -9,30 +9,65 @@ import com.microsoft.semantickernel.builders.Buildable;
 import com.microsoft.semantickernel.builders.SemanticKernelBuilder;
 import com.microsoft.semantickernel.builders.ServiceLoadUtil;
 import com.microsoft.semantickernel.orchestration.InvocationContext;
+
 import java.util.List;
+
 import javax.annotation.Nullable;
+
 import reactor.core.publisher.Mono;
 
+/**
+ * Chat completion service interface.
+ */
 public interface ChatCompletionService extends Buildable, TextAIService {
 
+    /**
+     * Gets the chat message contents asynchronously using 
+     * {@code ChatHistory} to support a turn-based conversation. 
+     * Typically, the resulting chat message contents is appended
+     * to the {@code chatHistory} to continue the conversation.
+     *
+     * @param chatHistory the chat history
+     * @param kernel the kernel
+     * @param invocationContext the invocation context
+     * @return the chat message contents
+     */
     Mono<List<ChatMessageContent>> getChatMessageContentsAsync(
         ChatHistory chatHistory,
         @Nullable Kernel kernel,
         @Nullable InvocationContext invocationContext
     );
 
+    /**
+     * Gets the chat message contents asynchronously using a prompt.
+     *
+     * @param prompt the prompt
+     * @param kernel the kernel
+     * @param invocationContext the invocation context
+     * @return the chat message contents
+     */
     Mono<List<ChatMessageContent>> getChatMessageContentsAsync(
         String prompt,
         @Nullable Kernel kernel,
         @Nullable InvocationContext invocationContext
     );
 
+    /**
+     * Get a builder for creating a {@code ChatCompletionService}. The builder loads a service
+     * that implements the {@link ChatCompletionService.Builder} interface.
+     * @return a builder for creating a {@code ChatCompletionService}
+     */
     static Builder builder() {
         return ServiceLoadUtil.findServiceLoader(Builder.class,
                 "com.microsoft.semantickernel.aiservices.openai.chatcompletion.OpenAIChatCompletion$Builder")
             .get();
     }
 
+    /**
+     * Builder API for creating a {@link ChatCompletionService}. Concrete implementations of
+     * {@link ChatCompletionService} must implement the {@link SemanticKernelBuilder#build()} 
+     * method.
+     */
     abstract class Builder implements SemanticKernelBuilder<ChatCompletionService> {
 
         @Nullable
@@ -68,6 +103,12 @@ public interface ChatCompletionService extends Buildable, TextAIService {
             return this;
         }
 
+        /**
+         * Sets the service ID to use with the ChatCompletion service.
+         *
+         * @param serviceId the service ID to use with the ChatCompletion service
+         * @return this builder
+         */
         public Builder withServiceId(String serviceId) {
             this.serviceId = serviceId;
             return this;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/chatcompletion/ChatHistory.java

@@ -1,19 +1,17 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.chatcompletion;
 
+import com.microsoft.semantickernel.orchestration.FunctionResultMetadata;
+
 import java.nio.charset.Charset;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.Iterator;
 import java.util.List;
-import java.util.Map;
 import java.util.Optional;
 import java.util.Spliterator;
 import java.util.function.Consumer;
 
-import com.microsoft.semantickernel.orchestration.FunctionResultMetadata;
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
-
 /**
  * Provides a history of messages between the User, Assistant and System
  */
@@ -23,10 +21,19 @@ public class ChatHistory implements Iterable<ChatMessageContent> {
 
     private final List<ChatMessageContent> chatMessageContents;
 
+    /**
+     * The default constructor adds an "Assistant is a large language model."
+     * system message to the chat history
+     */
     public ChatHistory() {
         this(DEFAULT_CHAT_SYSTEM_PROMPT);
     }
 
+    /**
+     * Constructor that adds the given system instructions to the chat history.
+     *
+     * @param instructions The instructions to add to the chat history
+     */
     public ChatHistory(String instructions) {
         this.chatMessageContents = new ArrayList<>();
         this.chatMessageContents.add(
@@ -37,6 +44,11 @@ public class ChatHistory implements Iterable<ChatMessageContent> {
         );
     }
 
+    /**
+     * Constructor that adds the given chat message contents to the chat history.
+     *
+     * @param chatMessageContents The chat message contents to add to the chat history
+     */
     public ChatHistory(List<ChatMessageContent> chatMessageContents) {
         this.chatMessageContents = new ArrayList<>(chatMessageContents);
     }
@@ -62,46 +74,100 @@ public class ChatHistory implements Iterable<ChatMessageContent> {
         return Optional.of(chatMessageContents.get(chatMessageContents.size() - 1));
     }
 
+    /**
+     * Add all messages from the given chat history to this chat history
+     *
+     * @param value The chat history to add to this chat history
+     */
     public void addAll(ChatHistory value) {
         this.chatMessageContents.addAll(value.getMessages());
     }
 
+    /**
+     * Create an {@code Iterator} from the chat history.
+     */
     @Override
     public Iterator<ChatMessageContent> iterator() {
         return chatMessageContents.iterator();
     }
 
+    /**
+     * Perform the given action for each message in the chat history
+     *
+     * @param action The action to perform for each message in the chat history
+     */
     @Override
     public void forEach(Consumer<? super ChatMessageContent> action) {
         chatMessageContents.forEach(action);
     }
 
+    /**
+     * Create a {@code Spliterator} from the chat history
+     */
     @Override
     public Spliterator<ChatMessageContent> spliterator() {
         return chatMessageContents.spliterator();
     }
 
+    /**
+     * Add a message to the chat history
+     *
+     * @param authorRole The role of the author of the message
+     * @param content The content of the message
+     * @param encoding The encoding of the message
+     * @param metadata The metadata of the message
+     */
     public void addMessage(AuthorRole authorRole, String content, Charset encoding,
         FunctionResultMetadata metadata) {
         chatMessageContents.add(
             new ChatMessageContent(authorRole, content, null, null, encoding, metadata));
     }
 
-
+    /**
+     * Add a message to the chat history
+     *
+     * @param authorRole The role of the author of the message
+     * @param content The content of the message
+     */
     public void addMessage(AuthorRole authorRole, String content) {
         chatMessageContents.add(
             new ChatMessageContent(authorRole, content, null, null, null, null));
     }
 
+    /**
+     * Add a message to the chat history
+     *
+     * @param content The content of the message
+     */
     public void addMessage(ChatMessageContent content) {
         chatMessageContents.add(content);
     }
 
+    /**
+     * Add a user message to the chat history
+     *
+     * @param content The content of the user message
+     */
     public void addUserMessage(String content) {
         addMessage(AuthorRole.USER, content);
     }
 
+    /**
+     * Add an assistant message to the chat history
+     *
+     * @param content The content of the assistant message
+     */    
     public void addAssistantMessage(String content) {
         addMessage(AuthorRole.ASSISTANT, content);
     }
+
+    /**
+     * Add an system message to the chat history
+     *
+     * @param content The content of the system message
+     */    
+    public void addSystemMessage(String content) {
+        addMessage(AuthorRole.SYSTEM, content);
+    }
+
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/chatcompletion/ChatMessageContent.java

@@ -3,23 +3,33 @@ package com.microsoft.semantickernel.chatcompletion;
 
 import com.microsoft.semantickernel.KernelContent;
 import com.microsoft.semantickernel.orchestration.FunctionResultMetadata;
+
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+
 import javax.annotation.Nullable;
 
+/**
+ * Represents the content of a chat message
+ */
 public class ChatMessageContent extends KernelContent<ChatMessageContent> {
 
     private AuthorRole authorRole;
     @Nullable
     private String content;
     @Nullable
-    private List<KernelContent> items;
+    private List<KernelContent<?>> items;
     @Nullable
     private Charset encoding;
 
+    /**
+     * Creates a new instance of the {@link ChatMessageContent} class.
+     * @param authorRole the author role that generated the content
+     * @param content the content
+     */
     public ChatMessageContent(
         AuthorRole authorRole,
         String content
@@ -33,6 +43,15 @@ public class ChatMessageContent extends KernelContent<ChatMessageContent> {
             null);
     }
 
+    /**
+     * Creates a new instance of the {@link ChatMessageContent} class.
+     * @param authorRole the author role that generated the content
+     * @param content the content
+     * @param modelId the model id
+     * @param innerContent the inner content
+     * @param encoding the encoding
+     * @param metadata the metadata
+     */
     public ChatMessageContent(
         AuthorRole authorRole,
         String content,
@@ -51,6 +70,15 @@ public class ChatMessageContent extends KernelContent<ChatMessageContent> {
         this.encoding = encoding != null ? encoding : StandardCharsets.UTF_8;
     }
 
+    /**
+     * Creates a new instance of the {@link ChatMessageContent} class.
+     * @param authorRole the author role that generated the content
+     * @param items the items
+     * @param modelId the model id
+     * @param innerContent the inner content
+     * @param encoding the encoding
+     * @param metadata the metadata
+     */
     public ChatMessageContent(
         AuthorRole authorRole,
         List<KernelContent<?>> items,
@@ -66,37 +94,69 @@ public class ChatMessageContent extends KernelContent<ChatMessageContent> {
         this.items = new ArrayList<>(items);
     }
 
+    /**
+     * Gets the author role that generated the content
+     * @return the author role that generated the content
+     */
     public AuthorRole getAuthorRole() {
         return authorRole;
     }
 
+    /**
+     * Sets the author role that generated the content
+     * @param authorRole the author role that generated the content
+     */
     public void setAuthorRole(AuthorRole authorRole) {
         this.authorRole = authorRole;
     }
 
+    /**
+     * Gets the content
+     * @return the content, which may be {@code null}
+     */
     @Nullable
     @Override
     public String getContent() {
         return content;
     }
 
+    /**
+     * Sets the content
+     * @param content the content
+     */
     public void setContent(@Nullable String content) {
         this.content = content;
     }
 
-    public List<KernelContent> getItems() {
+    /**
+     * Gets the {@code KernelContent} items that comprise the content.
+     * @return the items, which may be {@code null}
+     */
+    public List<KernelContent<?>> getItems() {
         return Collections.unmodifiableList(items);
     }
 
-    public void setItems(List<KernelContent> items) {
+    /**
+     * Sets the {@code KernelContent} items that comprise the content.
+     * @param items the items
+     */
+    public void setItems(List<KernelContent<?>> items) {
         this.items = new ArrayList<>(items);
     }
 
+    /**
+     * Gets the encoding of the content
+     * @return the encoding, which may be {@code null}
+     */
     @Nullable
     public Charset getEncoding() {
         return encoding;
     }
 
+    /**
+     * Sets the encoding of the content
+     * @param encoding the encoding
+     */
     public void setEncoding(Charset encoding) {
         this.encoding = encoding;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/chatcompletion/StreamingChatMessageContent.java

@@ -1,19 +1,32 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.chatcompletion;
 
+import com.microsoft.semantickernel.KernelContent;
 import com.microsoft.semantickernel.StreamingKernelContent;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
+
 import java.nio.charset.Charset;
 import java.nio.charset.StandardCharsets;
 import java.util.Map;
+
 import javax.annotation.Nullable;
 
-public class StreamingChatMessageContent<T> extends StreamingKernelContent<T> {
+/**
+ * Represents the content of a chat message that is streamed.
+ * @param <T> the type of the inner content
+ */
+public class StreamingChatMessageContent<T extends KernelContent<T>> extends StreamingKernelContent<T> {
 
     private final String content;
     private final AuthorRole role;
     private Charset encoding;
 
+    /**
+     * Creates a new instance of the {@link StreamingChatMessageContent} class.
+     * @param role the author role that generated the content
+     * @param content the content
+     * @param modelId the model id
+     */
     public StreamingChatMessageContent(
         AuthorRole role,
         String content,
@@ -22,6 +35,16 @@ public class StreamingChatMessageContent<T> extends StreamingKernelContent<T> {
         this(role, content, null, 0, modelId, null, null);
     }
 
+    /**
+     * Creates a new instance of the {@link StreamingChatMessageContent} class.
+     * @param role the author role that generated the content
+     * @param content the content
+     * @param innerContent the inner content
+     * @param choiceIndex the choice index
+     * @param modelId the model id
+     * @param encoding the encoding
+     * @param metadata the metadata
+     */
     public StreamingChatMessageContent(
         AuthorRole role,
         String content,
@@ -45,18 +68,32 @@ public class StreamingChatMessageContent<T> extends StreamingKernelContent<T> {
         return content != null ? content : "";
     }
 
+    @Override
     public String getContent() {
         return content;
     }
 
+    /**
+     * Gets the role of the author of the message
+     * @return the role of the author of the message
+     */
     public AuthorRole getRole() {
         return role;
     }
 
+    /**
+     * Gets the encoding of the message
+     * @return the encoding of the message
+     */
     public Charset getEncoding() {
         return encoding;
     }
 
+    /**
+     * Sets the encoding of the message
+     * @param encoding the encoding of the message
+     * @return this instance
+     */
     public StreamingChatMessageContent<T> setEncoding(Charset encoding) {
         this.encoding = encoding;
         return this;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/connectors/WebSearchEngineConnector.java

@@ -1,15 +1,34 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.connectors;
 
-import reactor.core.publisher.Mono;
-
 import java.util.List;
 
-public interface WebSearchEngineConnector {
+import reactor.core.publisher.Mono;
 
+/**
+ * Web search engine connector interface.
+ */
+public interface WebSearchEngineConnector {
+    /**
+     * Represents a web page.
+     */
     interface WebPage {
+        /**
+         * Gets the name of the web page.
+         * @return The name of the web page.
+         */
         String getName();
+
+        /** 
+         * Gets the URL of the web page.
+         * @return The URL of the web page.
+         */
         String getUrl();
+
+        /**
+         * Gets the snippet of the web page.
+         * @return The snippet of the web page.
+         */
         String getSnippet();
     }
 

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/ConfigurationException.java

@@ -5,21 +5,37 @@ import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
- * Kernel logic exception
+ * An exception that is thrown when there is an error with the 
+ * Semantic Kernel configuration.
  */
 public class ConfigurationException extends SKCheckedException {
 
     @Nonnull
     private final ErrorCodes errorCode;
 
+    /**
+     * Creates a new instance of the {@link ConfigurationException} class.
+     * @param error the error code
+     */
     public ConfigurationException(@Nonnull ErrorCodes error) {
         this(error, null, null);
     }
 
+    /**
+     * Creates a new instance of the {@link ConfigurationException} class.
+     * @param errorCode the error code
+     * @param message the message
+     */
     public ConfigurationException(@Nonnull ErrorCodes errorCode, @Nullable String message) {
         this(errorCode, message, null);
     }
 
+    /**
+     * Creates a new instance of the {@link ConfigurationException} class.
+     * @param errorCode the error code
+     * @param message the message
+     * @param innerException the inner exception
+     */
     public ConfigurationException(
         @Nonnull ErrorCodes errorCode,
         @Nullable String message,
@@ -28,17 +44,31 @@ public class ConfigurationException extends SKCheckedException {
         this.errorCode = errorCode;
     }
 
+    /**
+     * Gets the error code.
+     * @return the error code
+     */
     public ErrorCodes getErrorCode() {
         return errorCode;
     }
 
+    /**
+     * ErrorCodes for this exception.
+     */
     public enum ErrorCodes {
+        /** Unknown error */
         UNKNOWN_ERROR("Unknown error"),
 
+        /** Could not find configuration file */
         CONFIGURATION_NOT_FOUND("Could not find configuration file"),
 
+        /** Could not parse or load configuration file */
         COULD_NOT_READ_CONFIGURATION("Could not parse or load configuration file"),
+
+        /** Could not find any valid configuration settings */
         NO_VALID_CONFIGURATIONS_FOUND("Could not find any valid configuration settings"),
+
+        /** Could not find value for configuration key */
         VALUE_NOT_FOUND("Could not find value for configuration key");
 
         private final String message;
@@ -47,10 +77,19 @@ public class ConfigurationException extends SKCheckedException {
             this.message = message;
         }
 
+        /**
+         * Gets the message for the error code.
+         * @return the message for the error code
+         */
         public String getMessage() {
             return message;
         }
 
+        /**
+         * Format the message with the given parameter.
+         * @param param helpful information
+         * @return the formatted message
+         */
         public String getMessage(String param) {
             return String.format(message, param);
         }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/exceptions/NotSupportedException.java

@@ -1,42 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-package com.microsoft.semantickernel.exceptions;
-
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-
-public class NotSupportedException extends SKException {
-
-    private final ErrorCodes errorCode;
-
-    public NotSupportedException(@Nonnull ErrorCodes errorCode) {
-        this(errorCode, null, null);
-    }
-
-    public NotSupportedException(@Nonnull ErrorCodes errorCode, @Nullable String message) {
-        this(errorCode, message, null);
-    }
-
-    public NotSupportedException(
-            @Nonnull ErrorCodes errorCode, @Nullable String message, @Nullable Throwable cause) {
-        super(formatDefaultMessage(errorCode.getMessage(), message), cause);
-        this.errorCode = errorCode;
-    }
-
-    public ErrorCodes getErrorCode() {
-        return errorCode;
-    }
-
-    public enum ErrorCodes {
-        NOT_SUPPORTED("Not Supported");
-
-        final String message;
-
-        ErrorCodes(String message) {
-            this.message = message;
-        }
-
-        String getMessage() {
-            return message;
-        }
-    }
-}

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/FunctionInvokedEvent.java

@@ -1,22 +1,32 @@
 package com.microsoft.semantickernel.hooks;
 
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.orchestration.FunctionResult;
 import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
 
+import javax.annotation.Nullable;
+
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 
+/**
+ * Represents a KernelHookEvent that is raised after a function is invoked.
+ * @param <T> The type of the function result
+ */
 public class FunctionInvokedEvent<T> implements KernelHookEvent {
 
-    private final KernelFunction function;
+    private final KernelFunction<T> function;
     @Nullable
     private final KernelFunctionArguments arguments;
     private final FunctionResult<T> result;
 
+    /**
+     * Creates a new instance of the {@link FunctionInvokedEvent} class.
+     * @param function the function
+     * @param arguments the arguments
+     * @param result the result
+     */
     public FunctionInvokedEvent(
-        KernelFunction function,
+        KernelFunction<T> function,
         @Nullable KernelFunctionArguments arguments,
         FunctionResult<T> result) {
         this.function = function;
@@ -24,16 +34,28 @@ public class FunctionInvokedEvent<T> implements KernelHookEvent {
         this.result = result;
     }
 
-    public KernelFunction getFunction() {
+    /**
+     * Gets the function that was invoked.
+     * @return the function
+     */
+    public KernelFunction<T> getFunction() {
         return function;
     }
 
+    /**
+     * Gets the arguments that were passed to the function.
+     * @return the arguments
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP")
     @Nullable
     public KernelFunctionArguments getArguments() {
         return arguments;
     }
 
+    /**
+     * Gets the result of the function invocation.
+     * @return the result
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP")
     public FunctionResult<T> getResult() {
         return result;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/FunctionInvokingEvent.java

@@ -1,27 +1,46 @@
 package com.microsoft.semantickernel.hooks;
 
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
 
+import javax.annotation.Nullable;
+
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 
-public class FunctionInvokingEvent implements KernelHookEvent {
+/**
+ * Represents a KernelHookEvent that is raised before a function is invoked.
+ * This event is raised before the function is invoked, and can be used to 
+ * by a {@code KernelHook} to modify the arguments before the function is invoked.
+ * @param <T> The type of the KernelFunction being invoked
+ */
+public class FunctionInvokingEvent<T> implements KernelHookEvent {
 
-    private final KernelFunction function;
+    private final KernelFunction<T> function;
     private final KernelFunctionArguments arguments;
 
-    public FunctionInvokingEvent(KernelFunction function, 
+    /**
+     * Creates a new instance of the FunctionInvokingEvent class.
+     * @param function The function that is being invoked
+     * @param arguments The arguments that are being passed to the function
+     */
+    public FunctionInvokingEvent(KernelFunction<T> function, 
         @Nullable KernelFunctionArguments arguments) {
         this.function = function;
         this.arguments = arguments != null ? new KernelFunctionArguments(arguments) : new KernelFunctionArguments();
     }
 
-    public KernelFunction getFunction() {
+    /**
+     * Gets the function that is being invoked.
+     * @return the function
+     */
+    public KernelFunction<T> getFunction() {
         return function;
     }
 
+    /**
+     * Gets the arguments that are being passed to the function.
+     * @return the arguments
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP")
     public KernelFunctionArguments getArguments() {
         return arguments;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/KernelHook.java

@@ -2,10 +2,17 @@ package com.microsoft.semantickernel.hooks;
 
 import com.azure.ai.openai.models.ChatCompletionsOptions;
 import com.azure.ai.openai.models.ChatRequestMessage;
+
 import java.util.List;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
+/**
+ * Represents a hook that can be used to intercept and modify arguments to {@code KernelFunction}s.
+ * A {@code KernelHook} implements a {@code Predicate} that determines if the hook is interested 
+ * in a particular event, and a {@code Function} that can be used to modify the event. The 
+ * @param <T> The type of the event that the hook is interested in
+ */
 public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelHookEvent>,
     Function<T, T> {
 
@@ -20,7 +27,10 @@ public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelH
         return 50;
     }
 
-    interface FunctionInvokingHook extends KernelHook<FunctionInvokingEvent> {
+    /**
+     * A hook that accepts {@link FunctionInvokingEvent} 
+     */
+    interface FunctionInvokingHook extends KernelHook<FunctionInvokingEvent<?>> {
 
         @Override
         default boolean test(KernelHookEvent arguments) {
@@ -28,7 +38,10 @@ public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelH
         }
     }
 
-    interface FunctionInvokedHook extends KernelHook<FunctionInvokedEvent> {
+    /**
+     * A hook that accepts {@link FunctionInvokedEvent} 
+     */
+    interface FunctionInvokedHook extends KernelHook<FunctionInvokedEvent<?>> {
 
         @Override
         default boolean test(KernelHookEvent arguments) {
@@ -36,6 +49,9 @@ public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelH
         }
     }
 
+    /**
+     * A hook that accepts {@link PromptRenderingEvent} 
+     */
     interface PromptRenderingHook extends KernelHook<PromptRenderingEvent> {
 
         @Override
@@ -44,6 +60,9 @@ public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelH
         }
     }
 
+    /**
+     * A hook that accepts {@link PromptRenderedEvent} 
+     */
     interface PromptRenderedHook extends KernelHook<PromptRenderedEvent> {
 
         @Override
@@ -52,6 +71,10 @@ public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelH
         }
     }
 
+
+    /**
+     * A hook that accepts {@link PreChatCompletionEvent} 
+     */
     interface PreChatCompletionHook extends KernelHook<PreChatCompletionEvent> {
 
         @Override
@@ -59,6 +82,12 @@ public interface KernelHook<T extends KernelHookEvent> extends Predicate<KernelH
             return PreChatCompletionEvent.class.isAssignableFrom(arguments.getClass());
         }
 
+        /**
+         * A convenience method to clone the options with the messages from the event.
+         * @param options the options to clone
+         * @param messages the messages to use
+         * @return the new options
+         */
         static ChatCompletionsOptions cloneOptionsWithMessages(
             ChatCompletionsOptions options,
             List<ChatRequestMessage> messages) {

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/KernelHookEvent.java

@@ -1,5 +1,8 @@
 package com.microsoft.semantickernel.hooks;
 
+/**
+ * A marker interface for events that can be intercepted by a {@link KernelHook}.
+ */
 public interface KernelHookEvent {
 
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/KernelHooks.java

@@ -5,6 +5,7 @@ import com.microsoft.semantickernel.hooks.KernelHook.FunctionInvokingHook;
 import com.microsoft.semantickernel.hooks.KernelHook.PreChatCompletionHook;
 import com.microsoft.semantickernel.hooks.KernelHook.PromptRenderedHook;
 import com.microsoft.semantickernel.hooks.KernelHook.PromptRenderingHook;
+
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashMap;
@@ -13,16 +14,27 @@ import java.util.SortedSet;
 import java.util.TreeSet;
 import java.util.UUID;
 import java.util.function.Function;
+
 import javax.annotation.Nullable;
 
+/**
+ * Represents a collection of hooks that can be used to intercept and modify events in the kernel.
+ */
 public class KernelHooks {
 
     private final Map<String, KernelHook<?>> hooks;
 
+    /**
+     * Creates a new instance of the {@link KernelHooks} class.
+     */
     public KernelHooks() {
         this.hooks = new HashMap<>();
     }
 
+    /**
+     * Creates a copy of the {@link KernelHooks}.
+     * @param kernelHooks the hooks to copy
+     */
     public KernelHooks(@Nullable KernelHooks kernelHooks) {
         this();
         if (kernelHooks != null) {
@@ -30,44 +42,89 @@ public class KernelHooks {
         }
     }
 
+    /**
+     * Creates a new instance of the {@link KernelHooks} class 
+     * from the given hooks.
+     * @param hooks the hooks to add
+     */
     public KernelHooks(Map<String, KernelHook<?>> hooks) {
         this();
         this.hooks.putAll(hooks);
     }
 
+    /**
+     * Creates an unmodifiable copy of this {@link KernelHooks}.
+     * @return an unmodifiable copy of this {@link KernelHooks}
+     */
     public UnmodifiableKernelHooks unmodifiableClone() {
         return new UnmodifiableKernelHooks(this);
     }
+    
 
+    /**
+     * Gets the hooks in this collection.
+     * @return an unmodifiable map of the hooks
+     */
     private Map<String, KernelHook<?>> getHooks() {
         return Collections.unmodifiableMap(hooks);
     }
 
+    /**
+     * Add a {@link FunctionInvokingHook} to the collection of hooks.
+     * @param function the function to add
+     * @return the key of the hook in the collection
+     */
     public String addFunctionInvokingHook(
-        Function<FunctionInvokingEvent, FunctionInvokingEvent> function) {
+        Function<FunctionInvokingEvent<?>, FunctionInvokingEvent<?>> function) {
         return addHook((FunctionInvokingHook) function::apply);
     }
 
+    /**
+     * Add a {@link FunctionInvokedHook} to the collection of hooks.
+     * @param function the function to add
+     * @return the key of the hook in the collection
+     */
     public String addFunctionInvokedHook(
         Function<FunctionInvokedEvent<?>, FunctionInvokedEvent<?>> function) {
         return addHook((FunctionInvokedHook) function::apply);
     }
 
+    /**
+     * Add a {@link PreChatCompletionHook} to the collection of hooks.
+     * @param function the function to add
+     * @return the key of the hook in the collection
+     */
     public String addPreChatCompletionHook(
         Function<PreChatCompletionEvent, PreChatCompletionEvent> function) {
         return addHook((PreChatCompletionHook) function::apply);
     }
 
+    /**
+     * Add a {@link PromptRenderedHook} to the collection of hooks.
+     * @param function the function to add
+     * @return the key of the hook in the collection
+     */
     public String addPromptRenderedHook(
         Function<PromptRenderedEvent, PromptRenderedEvent> function) {
         return addHook((PromptRenderedHook) function::apply);
     }
 
+    /**
+     * Add a {@link PromptRenderingHook} to the collection of hooks.
+     * @param function the function to add
+     * @return the key of the hook in the collection
+     */
     public String addPromptRenderingHook(
         Function<PromptRenderingEvent, PromptRenderingEvent> function) {
         return addHook((PromptRenderingHook) function::apply);
     }
 
+    /**
+     * Executes the hooks in this collection that accept the event.
+     * @param event the event to execute the hooks on
+     * @param <T> the type of the event
+     * @return the event after the hooks have been executed
+     */
     @SuppressWarnings("unchecked")
     public <T extends KernelHookEvent> T executeHooks(T event) {
         SortedSet<KernelHook<?>> hooks = new TreeSet<>(Comparator.comparingInt(KernelHook::getPriority));
@@ -83,20 +140,41 @@ public class KernelHooks {
         return event;
     }
 
+    /**
+     * Add a {@link KernelHook} to the collection of hooks.
+     * @param hook the hook to add
+     * @return the key of the hook in the collection
+     */
     public String addHook(KernelHook<?> hook) {
         return addHook(UUID.randomUUID().toString(), hook);
     }
 
+    /**
+     * Add a {@link KernelHook} to the collection of hooks.
+     * @param hookName the key of the hook in the collection
+     * @param hook the hook to add
+     * @return the key of the hook in the collection
+     */
     public String addHook(String hookName, KernelHook<?> hook) {
         hooks.put(hookName, hook);
         return hookName;
     }
 
+    /**
+     * Remove a hook from the collection of hooks.
+     * @param hookName the key of the hook in the collection
+     * @return the removed hook, or {@code null} if the hook was not found
+     */
     public KernelHook<?> removeHook(String hookName) {
         return hooks.remove(hookName);
     }
 
-    public KernelHooks append(@Nullable KernelHooks kernelHooks) {
+    /**
+     * Appends the given hooks to this collection.
+     * @param kernelHooks the hooks to append
+     * @return this instance of the {@link KernelHooks} class
+     */
+    public KernelHooks addHooks(@Nullable KernelHooks kernelHooks) {
         if (kernelHooks == null) {
             return this;
         }
@@ -105,15 +183,17 @@ public class KernelHooks {
         return this;
     }
 
+    /**
+     * Determines if this collection of hooks is empty.
+     * @return {@code true} if the collection is empty, otherwise {@code false}
+     */
     public boolean isEmpty() {
         return hooks.isEmpty();
     }
 
-    public KernelHooks addHooks(KernelHooks hooks) {
-        this.hooks.putAll(hooks.getHooks());
-        return this;
-    }
-
+    /**
+     * A wrapper for KernelHooks that disables mutating methods.
+     */
     public static class UnmodifiableKernelHooks extends KernelHooks {
 
         private UnmodifiableKernelHooks(KernelHooks kernelHooks) {
@@ -122,7 +202,7 @@ public class KernelHooks {
 
         @Override
         public String addFunctionInvokingHook(
-            Function<FunctionInvokingEvent, FunctionInvokingEvent> function) {
+            Function<FunctionInvokingEvent<?>, FunctionInvokingEvent<?>> function) {
             throw new UnsupportedOperationException("unmodifiable instance of KernelHooks");
         }
 
@@ -161,7 +241,7 @@ public class KernelHooks {
         }
 
         @Override
-        public KernelHooks append(@Nullable KernelHooks kernelHooks) {
+        public KernelHooks addHooks(@Nullable KernelHooks kernelHooks) {
             throw new UnsupportedOperationException("unmodifiable instance of KernelHooks");
         }
 

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PreChatCompletionEvent.java

@@ -2,14 +2,25 @@ package com.microsoft.semantickernel.hooks;
 
 import com.azure.ai.openai.models.ChatCompletionsOptions;
 
+/**
+ * Represents a KernelHookEvent that is raised before a chat completion is invoked.
+ */
 public class PreChatCompletionEvent implements KernelHookEvent {
 
     private final ChatCompletionsOptions options;
 
+    /**
+     * Creates a new instance of the {@link PreChatCompletionEvent} class.
+     * @param options the chat completion options
+     */
     public PreChatCompletionEvent(ChatCompletionsOptions options) {
         this.options = options;
     }
 
+    /**
+     * Gets the chat completion options.
+     * @return the options
+     */
     public ChatCompletionsOptions getOptions() {
         return options;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PromptRenderedEvent.java

@@ -2,15 +2,26 @@ package com.microsoft.semantickernel.hooks;
 
 import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
 import javax.annotation.Nullable;
 
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+/**
+ * Represents a KernelHookEvent that is raised after a prompt is rendered.
+ */
 public class PromptRenderedEvent implements KernelHookEvent {
 
-    private final KernelFunction function;
+    private final KernelFunction<?> function;
     private final KernelFunctionArguments arguments;
     private final String prompt;
 
+    /**
+     * Creates a new instance of the {@link PromptRenderedEvent} class.
+     * @param function the function
+     * @param arguments the arguments
+     * @param prompt the prompt
+     */
     public PromptRenderedEvent(
         KernelFunction function,
         @Nullable
@@ -22,15 +33,27 @@ public class PromptRenderedEvent implements KernelHookEvent {
         this.prompt = prompt;
     }
 
+    /**
+     * Gets the function that was invoked.
+     * @return the function
+     */
     public KernelFunction getFunction() {
         return function;
     }
 
+    /**
+     * Gets the arguments that were passed to the function.
+     * @return the arguments
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP")
     public KernelFunctionArguments getArguments() {
         return arguments;
     }
 
+    /**
+     * Gets the prompt that was rendered.
+     * @return the prompt
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP")
     public String getPrompt() {
         return prompt;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/hooks/PromptRenderingEvent.java

@@ -3,23 +3,40 @@ package com.microsoft.semantickernel.hooks;
 import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
 
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import javax.annotation.Nullable;
 
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
+/**
+ * Represents a KernelHookEvent that is raised after a prompt is rendered.
+ */
 public class PromptRenderingEvent implements KernelHookEvent {
 
-    private final KernelFunction function;
+    private final KernelFunction<?>function;
     private final KernelFunctionArguments arguments;
 
-    public PromptRenderingEvent(KernelFunction function, @Nullable KernelFunctionArguments arguments) {
+    /**
+     * Creates a new instance of the {@link PromptRenderingEvent} class.
+     * @param function the function
+     * @param arguments the arguments
+     */
+    public PromptRenderingEvent(KernelFunction<?>function, @Nullable KernelFunctionArguments arguments) {
         this.function = function;
         this.arguments = arguments != null ? new KernelFunctionArguments(arguments) : new KernelFunctionArguments();
     }
 
-    public KernelFunction getFunction() {
+    /**
+     * Gets the function that was invoked.
+     * @return the function
+     */
+    public KernelFunction<?>getFunction() {
         return function;
     }
 
+    /**
+     * Gets the arguments that were passed to the function.
+     * @return the arguments
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP")
     public KernelFunctionArguments getArguments() {
         return arguments;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionInvocation.java

@@ -9,15 +9,23 @@ import com.microsoft.semantickernel.orchestration.ToolCallBehavior.UnmodifiableT
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableType;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes;
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
 import java.util.function.BiConsumer;
+
 import javax.annotation.Nullable;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import reactor.core.CoreSubscriber;
 import reactor.core.publisher.Mono;
 import reactor.core.publisher.SynchronousSink;
 
+/** 
+ * {@code FunctionInvocation} supports fluent invocation of a function in the kernel.
+ * @param <T> The type of the result of the function invocation.
+ */
 public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(FunctionInvocation.class);
@@ -38,7 +46,11 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
     protected UnmodifiableToolCallBehavior toolCallBehavior;
     protected final ContextVariableTypes contextVariableTypes = new ContextVariableTypes();
 
-
+    /**
+     * Create a new function invocation.
+     * @param kernel The kernel to invoke the function on.
+     * @param function The function to invoke.
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP2")
     public FunctionInvocation(
         Kernel kernel,
@@ -49,6 +61,12 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
         this.addKernelHooks(kernel.getGlobalKernelHooks());
     }
 
+    /**
+     * Create a new function invocation.
+     * @param kernel The kernel to invoke the function on.
+     * @param function The function to invoke.
+     * @param resultType The type of the result of the function invocation.
+     */
     @SuppressFBWarnings("EI_EXPOSE_REP2")
     public FunctionInvocation(
         Kernel kernel,
@@ -64,6 +82,11 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
         this.addKernelHooks(kernel.getGlobalKernelHooks());
     }
 
+    /**
+     * Supply arguments to the function invocation.
+     * @param arguments The arguments to supply to the function invocation.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
     public FunctionInvocation<T> withArguments(
         @Nullable
         KernelFunctionArguments arguments) {
@@ -75,6 +98,12 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
         return this;
     }
 
+    /**
+     * Supply the result type of function invocation.
+     * @param resultType The arguments to supply to the function invocation.
+     * @param <U> The type of the result of the function invocation.
+     * @return A new {@code FunctionInvocation} for fluent chaining.
+     */
     public <U> FunctionInvocation<U> withResultType(ContextVariableType<U> resultType) {
         return new FunctionInvocation<>(
             kernel,
@@ -86,7 +115,12 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
             .withToolCallBehavior(toolCallBehavior);
     }
 
-    public FunctionInvocation<T> addKernelHook(@Nullable KernelHook hook) {
+    /**
+     * Add a kernel hook to the function invocation.
+     * @param hook The kernel hook to add.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
+    public FunctionInvocation<T> addKernelHook(@Nullable KernelHook<?> hook) {
         if (hook == null) {
             return this;
         }
@@ -96,6 +130,11 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
         return this;
     }
 
+    /**
+     * Add kernel hooks to the function invocation.
+     * @param hooks The kernel hooks to add.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
     public FunctionInvocation<T> addKernelHooks(
         @Nullable
         KernelHooks hooks) {
@@ -106,6 +145,11 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
         return this;
     }
 
+    /**
+     * Supply prompt execution settings to the function invocation.
+     * @param promptExecutionSettings The prompt execution settings to supply to the function invocation.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
     public FunctionInvocation<T> withPromptExecutionSettings(
         @Nullable
         PromptExecutionSettings promptExecutionSettings) {
@@ -113,22 +157,59 @@ public class FunctionInvocation<T> extends Mono<FunctionResult<T>> {
         return this;
     }
 
+    /**
+     * Supply tool call behavior to the function invocation.
+     * @param toolCallBehavior The tool call behavior to supply to the function invocation.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
     public FunctionInvocation<T> withToolCallBehavior(@Nullable ToolCallBehavior toolCallBehavior) {
         this.toolCallBehavior = unmodifiableClone(toolCallBehavior);
         return this;
     }
 
+    /**
+     * Supply a type converter to the function invocation.
+     * @param typeConverter The type converter to supply to the function invocation.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
     public FunctionInvocation<T> withTypeConverter(ContextVariableType<?> typeConverter) {
         contextVariableTypes.putConverter(typeConverter.getConverter());
         return this;
     }
 
 
+    /**
+     * Supply a context variable type to the function invocation.
+     * @param contextVariableTypes The context variable types to supply to the function invocation.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
     public FunctionInvocation<T> withTypes(ContextVariableTypes contextVariableTypes) {
         this.contextVariableTypes.putConverters(contextVariableTypes);
         return this;
     }
 
+    /**
+     * Use an invocation context variable to supply the types, tool call behavior,
+     * prompt execution settings, and kernel hooks to the function invocation.
+     * @param invocationContext The invocation context to supply to the function invocation.
+     * @return this {@code FunctionInvocation} for fluent chaining.
+     */
+    public FunctionInvocation<T> withInvocationContext(
+        @Nullable InvocationContext invocationContext) {
+        if (invocationContext == null) {
+            return this;
+        }
+        withTypes(invocationContext.getContextVariableTypes());
+        withToolCallBehavior(invocationContext.getToolCallBehavior());
+        withPromptExecutionSettings(invocationContext.getPromptExecutionSettings());
+        addKernelHooks(invocationContext.getKernelHooks());
+        return this;
+    }
+
+    /**
+     * This method hanldes the reactive stream when the KernelFunciton is invoked. 
+     * @param coreSubscriber The subscriber to subscribe to the function invocation.
+     */
     @Override
     public void subscribe(CoreSubscriber<? super FunctionResult<T>> coreSubscriber) {
         performSubscribe(

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionResult.java

@@ -1,13 +1,28 @@
 package com.microsoft.semantickernel.orchestration;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
+
 import javax.annotation.Nullable;
 
+/**
+ * The result of a function invocation.
+ * <p>
+ * This class is used to return the result of a function invocation. It contains the result of the
+ * function invocation and metadata about the result.
+ *
+ * @param <T> The type of the result of the function invocation.
+ */
 public class FunctionResult<T> {
 
     private final ContextVariable<T> result;
     private final FunctionResultMetadata metadata;
 
+    /**
+     * Create a new instance of FunctionResult.
+     *
+     * @param result   The result of the function invocation.
+     * @param metadata Metadata about the result of the function invocation.
+     */
     public FunctionResult(
         ContextVariable<T> result,
         @Nullable FunctionResultMetadata metadata) {
@@ -15,27 +30,43 @@ public class FunctionResult<T> {
         this.metadata = metadata == null ? FunctionResultMetadata.empty() : metadata;
     }
 
+    /**
+     * Create a new instance of FunctionResult with no metadata.
+     *
+     * @param of The result of the function invocation.
+     */
     public FunctionResult(ContextVariable<T> of) {
         this(of, FunctionResultMetadata.empty());
     }
 
     /**
-     * Get the result of the function invocation.
-     * <p>
-     * NOTE: IF YOU GET ClassCastException FROM THIS TRY ADDING withResultType() TO THE FUNCTION
-     * INVOCATION
+     * Get the result of the function invocation. 
+     * <em>NOTE: If you get a ClassCastException from this method, 
+     * try adding a result type with 
+     * {@link FunctionInvocation#withResultType(ContextVariableType)}</em>
      *
      * @return The result of the function invocation.
+     * @throws ClassCastException If the result is not of the expected type.
      */
     @Nullable
     public T getResult() {
         return result.getValue();
     }
 
+    /**
+     * Get the result of the function invocation.
+     *
+     * @return The result of the function invocation.
+     */
     public ContextVariable<T> getResultVariable() {
         return result;
     }
 
+    /**
+     * Get the metadata about the result of the function invocation.
+     *
+     * @return The metadata about the result of the function invocation.
+     */
     public FunctionResultMetadata getMetadata() {
         return metadata;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/FunctionResultMetadata.java

@@ -3,26 +3,54 @@ package com.microsoft.semantickernel.orchestration;
 import com.azure.ai.openai.models.CompletionsUsage;
 import com.microsoft.semantickernel.orchestration.contextvariables.CaseInsensitiveMap;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
+
 import java.time.OffsetDateTime;
+
 import javax.annotation.Nullable;
 
+/**
+ * Metadata about the result of a function invocation.
+ * <p>
+ * This class is used to return metadata about the result of a function invocation.
+ */
 public class FunctionResultMetadata {
 
+    /** The key for id metadata. */
     public static final String ID = "id";
+
+    /** The key for usage metadata. */
     public static final String USAGE = "usage";
+
+    /** The key for createdAt metadata. */
     public static final String CREATED_AT = "createdAt";
 
 
     private final CaseInsensitiveMap<ContextVariable<?>> metadata;
 
+    /**
+     * Create a new instance of FunctionResultMetadata.
+     */
     public FunctionResultMetadata() {
         this.metadata = new CaseInsensitiveMap<>();
     }
 
+    /**
+     * Create a new instance of FunctionResultMetadata.
+     *
+     * @param metadata Metadata about the result of the function invocation.
+     */
     public FunctionResultMetadata(CaseInsensitiveMap<ContextVariable<?>> metadata) {
         this.metadata = new CaseInsensitiveMap<>(metadata);
     }
 
+    /**
+     * Create a new instance of FunctionResultMetadata.
+     *
+     * @param id       The id of the result of the function invocation.
+     * @param usage    The usage of the result of the function invocation.
+     * @param createdAt The time the result was created.
+     * @return A new instance of FunctionResultMetadata.
+     */
     public static FunctionResultMetadata build(
         String id,
         CompletionsUsage usage,
@@ -36,14 +64,29 @@ public class FunctionResultMetadata {
         return new FunctionResultMetadata(metadata);
     }
 
+    /**
+     * Create a new instance of FunctionResultMetadata with no metadata.
+     *
+     * @return A new instance of FunctionResultMetadata.
+     */
     public static FunctionResultMetadata empty() {
         return new FunctionResultMetadata(new CaseInsensitiveMap<>());
     }
 
+    /**
+     * Get the metadata about the result of the function invocation.
+     *
+     * @return The metadata about the result of the function invocation.
+     */
     public CaseInsensitiveMap<ContextVariable<?>> getMetadata() {
         return new CaseInsensitiveMap<>(metadata);
     }
 
+    /**
+     * Get the id of the result of the function invocation.
+     *
+     * @return The id of the result of the function invocation.
+     */
     @Nullable
     public String getId() {
         ContextVariable<?> id = metadata.get(ID);
@@ -53,6 +96,11 @@ public class FunctionResultMetadata {
         return id.getValue(String.class);
     }
 
+    /**
+     * Get the usage of the result of the function invocation.
+     *
+     * @return The usage of the result of the function invocation.
+     */
     @Nullable
     public CompletionsUsage getUsage() {
         ContextVariable<?> usage = metadata.get(USAGE);
@@ -62,6 +110,11 @@ public class FunctionResultMetadata {
         return usage.getValue(CompletionsUsage.class);
     }
 
+    /**
+     * Get the time the result was created.
+     *
+     * @return The time the result was created.
+     */
     @Nullable
     public OffsetDateTime getCreatedAt() {
         ContextVariable<?> createdAt = metadata.get(CREATED_AT);

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/InvocationContext.java

@@ -7,11 +7,15 @@ import com.microsoft.semantickernel.hooks.KernelHooks.UnmodifiableKernelHooks;
 import com.microsoft.semantickernel.orchestration.ToolCallBehavior.UnmodifiableToolCallBehavior;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes;
-import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
 import javax.annotation.Nullable;
 
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+
 /**
- * Context passed to a Kernel or KernelFunction invoke
+ * Context passed to a Kernel or KernelFunction invoke. This class is primarily for
+ * internal use. The preferred way to supply a context is to use the discrete "with" 
+ * methods in {@link FunctionInvocation}.  
  */
 public class InvocationContext implements Buildable {
 
@@ -23,6 +27,14 @@ public class InvocationContext implements Buildable {
     private final UnmodifiableToolCallBehavior toolCallBehavior;
     private final ContextVariableTypes contextVariableTypes;
 
+    /**
+     * Create a new instance of InvocationContext.
+     *
+     * @param hooks                   The hooks to use for the invocation.
+     * @param promptExecutionSettings The settings for prompt execution.
+     * @param toolCallBehavior        The behavior for tool calls.
+     * @param contextVariableTypes    The types of context variables.
+     */
     public InvocationContext(
         @Nullable KernelHooks hooks,
         @Nullable PromptExecutionSettings promptExecutionSettings,
@@ -38,6 +50,9 @@ public class InvocationContext implements Buildable {
         }
     }
 
+    /**
+     * Create a new instance of InvocationContext.
+     */
     public InvocationContext() {
         this.hooks = null;
         this.promptExecutionSettings = null;
@@ -45,6 +60,11 @@ public class InvocationContext implements Buildable {
         this.contextVariableTypes = new ContextVariableTypes();
     }
 
+    /**
+     * Create a new instance of InvocationContext.
+     *
+     * @param context The context to copy.
+     */
     public InvocationContext(@Nullable InvocationContext context) {
         if (context == null) {
             this.hooks = null;
@@ -59,27 +79,47 @@ public class InvocationContext implements Buildable {
         }
     }
 
+    /**
+     * Get the hooks to use for the invocation.
+     * @return The hooks to use for the invocation.
+     */
     @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "returns UnmodifiableKernelHooks")
     @Nullable
     public UnmodifiableKernelHooks getKernelHooks() {
         return hooks;
     }
 
+    /**
+     * Get the settings for prompt execution.
+     * @return The settings for prompt execution.
+     */
     @Nullable
     public PromptExecutionSettings getPromptExecutionSettings() {
         return promptExecutionSettings;
     }
 
+    /**
+     * Get the behavior for tool calls.
+     * @return The behavior for tool calls.
+     */
     @SuppressFBWarnings(value = "EI_EXPOSE_REP", justification = "returns UnmodifiableToolCallBehavior")
     @Nullable
     public UnmodifiableToolCallBehavior getToolCallBehavior() {
         return toolCallBehavior;
     }
 
+    /**
+     * Get the types of context variables.
+     * @return The types of context variables.
+     */
     public ContextVariableTypes getContextVariableTypes() {
         return new ContextVariableTypes(contextVariableTypes);
     }
 
+    /**
+     * Create a new {@link Builder} for building an instance of {@code InvocationContext}.
+     * @return the new Builder.
+     */
     public static Builder builder() {
         return new Builder();
     }
@@ -110,6 +150,9 @@ public class InvocationContext implements Buildable {
         }
     }
 
+    /**
+     * Builder for {@link InvocationContext}.
+     */
     public static class Builder implements SemanticKernelBuilder<InvocationContext> {
 
         @Nullable
@@ -123,12 +166,22 @@ public class InvocationContext implements Buildable {
 
         private final ContextVariableTypes contextVariableTypes = new ContextVariableTypes();
 
+        /**
+         * Add kernel hooks to the builder.
+         * @param hooks the hooks to add.
+         * @return this {@link Builder}
+         */
         public Builder withKernelHooks(
             @Nullable KernelHooks hooks) {
             this.hooks = unmodifiableClone(hooks);
             return this;
         }
 
+        /**
+         * Add prompt execution settings to the builder.
+         * @param promptExecutionSettings the settings to add.
+         * @return this {@link Builder}
+         */
         public Builder withPromptExecutionSettings(
             @Nullable
             PromptExecutionSettings promptExecutionSettings) {
@@ -136,6 +189,11 @@ public class InvocationContext implements Buildable {
             return this;
         }
 
+        /**
+         * Add tool call behavior to the builder.
+         * @param toolCallBehavior the behavior to add.
+         * @return this {@link Builder}
+         */
         public Builder withToolCallBehavior(
             @Nullable
             ToolCallBehavior toolCallBehavior) {
@@ -143,6 +201,11 @@ public class InvocationContext implements Buildable {
             return this;
         }
 
+        /**
+         * Add a context variable type converter to the builder.
+         * @param converter the converter to add.
+         * @return this {@link Builder}
+         */
         public Builder withContextVariableConverter(ContextVariableTypeConverter<?> converter) {
             this.contextVariableTypes.putConverter(
                 converter
@@ -150,6 +213,7 @@ public class InvocationContext implements Buildable {
             return this;
         }
 
+        
         @Override
         public InvocationContext build() {
             return new InvocationContext(hooks, promptExecutionSettings, toolCallBehavior,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/KernelFunction.java

@@ -1,13 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.orchestration;
 
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.Kernel;
 import com.microsoft.semantickernel.Todo;
 import com.microsoft.semantickernel.builders.Buildable;
@@ -17,30 +10,42 @@ import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariab
 import com.microsoft.semantickernel.semanticfunctions.InputVariable;
 import com.microsoft.semantickernel.semanticfunctions.OutputVariable;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplate;
+import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateFactory;
 
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import javax.annotation.Nullable;
+
 import reactor.core.publisher.Mono;
 
 /**
- * Semantic Kernel callable function interface
+ * Semantic Kernel callable function interface. The Semantic Kernel creates 
+ * {@code KernelFunction}s from prompts, templates, or plugin methods.  
  *
  * @param <T> The type of the result of the function
+ * @see com.microsoft.semantickernel.semanticfunctions
+ * @see com.microsoft.semantickernel.plugin
+ * @see com.microsoft.semantickernel.plugin.annotations
  */
-// TODO: add example of using ContextVariableType to class documentation
 public abstract class KernelFunction<T> implements Buildable {
 
-    /// <summary>
-    /// Gets the metadata describing the function.
-    /// </summary>
-    /// <returns>An instance of <see cref="KernelFunctionMetadata"/> describing the function</returns>
     private final KernelFunctionMetadata<?> metadata;
 
-    /// <summary>
-    /// Gets the prompt execution settings.
-    /// </summary>
     @Nullable
     private final Map<String, PromptExecutionSettings> executionSettings;
 
+    /**
+     * Create a new instance of KernelFunction.
+     *
+     * @param metadata          The metadata for the function
+     * @param executionSettings The execution settings for the function
+     * @see com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromPrompt
+     * @see com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromMethod
+     */
     protected KernelFunction(
         KernelFunctionMetadata<?> metadata,
         @Nullable
@@ -93,10 +98,18 @@ public abstract class KernelFunction<T> implements Buildable {
         throw new Todo();
     }
 
+    /**
+     * Get an unmodifiable map of the execution settings for the function.
+     * @return An unmodifiable map of the execution settings for the function
+     */
     public Map<String, PromptExecutionSettings> getExecutionSettings() {
         return Collections.unmodifiableMap(executionSettings);
     }
 
+    /**
+     * Get the metadata for the function.
+     * @return The metadata for the function
+     */
     public KernelFunctionMetadata<?> getMetadata() {
         return metadata;
     }
@@ -134,42 +147,127 @@ public abstract class KernelFunction<T> implements Buildable {
         @Nullable ContextVariableType<T> variableType,
         @Nullable InvocationContext invocationContext);
 
+    /**
+     * Invokes this KernelFunction.
+     * @param kernel The Kernel containing services, plugins, and other state for use
+     *              throughout the operation.
+     * @return The result of the function's execution.
+     */
     public FunctionInvocation<T> invokeAsync(Kernel kernel) {
         return new FunctionInvocation<>(kernel, this);
     }
 
+    /**
+     * Builder for creating a {@link KernelFunction} from a prompt.
+     *
+     * @param <T> The type of the result of the function
+     * @see com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromPrompt.Builder
+     */
     public interface FromPromptBuilder<T> {
 
+        /**
+         * Set the name of the function.
+         *
+         * @param name The name of the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withName(@Nullable String name);
 
+        /**
+         * Set the input parameters for the function.
+         *
+         * @param inputVariables The input parameters for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withInputParameters(
             @Nullable List<InputVariable> inputVariables);
 
+        /**
+         * Set the prompt template for the function.
+         * @param promptTemplate The prompt template for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withPromptTemplate(
             @Nullable PromptTemplate promptTemplate);
 
+        /**
+         * Set the execution settings for the function.
+         * @param executionSettings The execution settings for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withExecutionSettings(
             @Nullable
             Map<String, PromptExecutionSettings> executionSettings);
 
+        /**
+         * Set the default execution settings for the function.
+         * 
+         * @param executionSettings The default execution settings for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withDefaultExecutionSettings(
             @Nullable
             PromptExecutionSettings executionSettings);
 
+        /**
+         * Set the description of the function.
+         * 
+         * @param description The description of the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withDescription(@Nullable String description);
 
+        /**
+         * Set the template for the function.
+         * 
+         * @param template The template for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withTemplate(@Nullable String template);
 
+        /**
+         * Create a new KernelFunction instance from the builder.
+         * @return The new KernelFunction instance
+         */
         KernelFunction<T> build();
 
+        /**
+         * Set the template format for the function.
+         * @param templateFormat The template format for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withTemplateFormat(String templateFormat);
 
+        /**
+         * Set the output variable for the function.
+         * @param outputVariable The output variable for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withOutputVariable(@Nullable OutputVariable outputVariable);
 
+        /**
+         * Set the output variable for the function.
+         * @param description The description of the output variable
+         * @param type The type of the output variable
+         * @return The builder
+         */
         FromPromptBuilder<T> withOutputVariable(@Nullable String description, String type);
 
-
+        /**
+         * Set the prompt template factory used to build the function.
+         * @param promptTemplateFactory The prompt template factory for the function
+         * @return The builder
+         */
         FromPromptBuilder<T> withPromptTemplateFactory(
             @Nullable PromptTemplateFactory promptTemplateFactory);
+
+        /**
+         * Set the prompt template config used to build the function.
+         * @param promptTemplateConfig The prompt template config for the function
+         * @return The builder
+         */
+        FromPromptBuilder<T> withPromptTemplateConfig(
+            @Nullable PromptTemplateConfig promptTemplateConfig);
+
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/KernelFunctionArguments.java

@@ -8,16 +8,18 @@ import com.microsoft.semantickernel.orchestration.contextvariables.CaseInsensiti
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableType;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
+
 import java.util.Collection;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Set;
+
 import javax.annotation.Nullable;
+
 import reactor.util.annotation.NonNull;
 
 /**
- * Context Variables is a data structure that holds temporary data while a task is being performed.
- * It is accessed by functions in the pipeline.
+ * Arguments to a kernel function. 
  */
 public class KernelFunctionArguments implements Buildable, Map<String, ContextVariable<?>> {
 
@@ -28,6 +30,11 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
 
     private final CaseInsensitiveMap<ContextVariable<?>> variables;
 
+    /**
+     * Create a new instance of KernelFunctionArguments.
+     *
+     * @param variables The variables to use for the function invocation.
+     */
     public KernelFunctionArguments(
         @Nullable
         Map<String, ContextVariable<?>> variables) {
@@ -38,12 +45,19 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
         }
     }
 
+    /**
+     * Create a new instance of KernelFunctionArguments.
+     *
+     * @param content The content to use for the function invocation.
+     */
     public KernelFunctionArguments(@NonNull ContextVariable<?> content) {
         this.variables = new CaseInsensitiveMap<>();
         this.variables.put(MAIN_KEY, content);
     }
 
-
+    /**
+     * Create a new instance of KernelFunctionArguments.
+     */
     public KernelFunctionArguments() {
         this.variables = new CaseInsensitiveMap<>();
     }
@@ -109,6 +123,11 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
                 key, value.getType().getClazz(), clazz));
     }
 
+    /**
+     * Return whether the variable with the given name is {@code null} or empty.
+     * @param key the key for the variable
+     * @return {@code true} if the variable is {@code null} or empty, {@code false} otherwise
+     */
     public boolean isNullOrEmpty(String key) {
         return get(key) == null || get(key).isEmpty();
     }
@@ -174,6 +193,11 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
         return variables.entrySet();
     }
 
+    /**
+     * Create a new instance of Builder.
+     *
+     * @return Builder
+     */
     public static Builder builder() {
         return new KernelFunctionArguments.Builder();
     }
@@ -185,6 +209,9 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
 
         private final Map<String, ContextVariable<?>> variables;
 
+        /**
+         * Create a new instance of Builder.
+         */
         public Builder() {
             variables = new HashMap<>();
             this.variables.put(MAIN_KEY, ContextVariable.of(""));
@@ -194,6 +221,7 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
          * Builds an instance with the given content in the default main key
          *
          * @param content Entry to place in the "input" slot
+         * @param <T>           Type of the value
          * @return {$code this} Builder for fluent coding
          */
         public <T> Builder withInput(ContextVariable<T> content) {
@@ -216,6 +244,7 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
          *
          * @param content       Entry to place in the "input" slot
          * @param typeConverter Type converter for the content
+         * @param <T>           Type of the value
          * @return {$code this} Builder for fluent coding
          * @throws SKException if the content cannot be converted to a ContextVariable
          */
@@ -245,6 +274,7 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
          *
          * @param key   variable name
          * @param value variable value
+         * @param <T>           Type of the value
          * @return {$code this} Builder for fluent coding
          */
         public <T> Builder withVariable(String key, ContextVariable<T> value) {
@@ -270,6 +300,7 @@ public class KernelFunctionArguments implements Buildable, Map<String, ContextVa
          * @param key           variable name
          * @param value         variable value
          * @param typeConverter Type converter for the value
+         * @param <T>           Type of the value
          * @return {$code this} Builder for fluent coding
          * @throws SKException if the value cannot be converted to a ContextVariable
          */

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/KernelFunctionMetadata.java

@@ -1,29 +1,35 @@
 package com.microsoft.semantickernel.orchestration;
 
+import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
+import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
+
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
 import javax.annotation.Nullable;
 
-import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
-import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
-
+/**
+ * Metadata about a kernel function.
+ *
+ * @param <T> The type of the return value of the function.
+ */
 public class KernelFunctionMetadata<T> {
 
-    /// <summary>The name of the function.</summary>
     private final String name;
-    /// <summary>The description of the function.</summary>
     @Nullable
     private final String description;
-    /// <summary>The function's parameters.</summary>
     private final List<KernelParameterMetadata<?>> parameters;
-
-
-    /// <summary>The function's return parameter.</summary>
     private final KernelReturnParameterMetadata<T> returnParameter;
 
-
+    /**
+     * Create a new instance of KernelFunctionMetadata.
+     *
+     * @param name           The name of the function.
+     * @param description    The description of the function.
+     * @param parameters     The parameters of the function.
+     * @param returnParameter The return parameter of the function.
+     */
     public KernelFunctionMetadata(
         String name,
         @Nullable
@@ -42,19 +48,35 @@ public class KernelFunctionMetadata<T> {
         this.returnParameter = returnParameter;
     }
 
+    /**
+     * Get the name of the function.
+     * @return The name of the function.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Get the parameters of the function.
+     * @return The parameters of the function.
+     */
     public List<KernelParameterMetadata<?>> getParameters() {
         return Collections.unmodifiableList(parameters);
     }
 
+    /**
+     * Get the description of the function.
+     * @return The description of the function.
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
+    /**
+     * Get the return parameter of the function.
+     * @return The return parameter of the function.
+     */
     public KernelReturnParameterMetadata<T> getReturnParameter() {
         return returnParameter;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/KernelFunctionYaml.java

@@ -7,22 +7,28 @@ import com.microsoft.semantickernel.semanticfunctions.PromptTemplate;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateFactory;
 import com.microsoft.semantickernel.templateengine.handlebars.HandlebarsPromptTemplate;
+
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
 import java.nio.file.Path;
+
 import javax.annotation.Nullable;
 
+/**
+ * A class for creating a {@link KernelFunction} instance from a YAML representation of a prompt function.
+ */
 public class KernelFunctionYaml {
 
-    /// <summary>
-    /// Creates a <see cref="KernelFunction"/> instance for a prompt function using the specified markdown text.
-    /// </summary>
-    /// <param name="text">YAML representation of the <see cref="PromptTemplateConfig"/> to use to create the prompt function</param>
-    /// <param name="promptTemplateFactory">>Prompt template factory.</param>
-    /// <param name="loggerFactory">The <see cref="ILoggerFactory"/> to use for logging. If null, no logging will be performed.</param>
-    /// <returns>The created <see cref="KernelFunction"/>.</returns>
+    /**
+     * Create a KernelFunction instance for a prompt function using the specified markdown text.
+     * @param yaml YAML representation of the PromptTemplateConfig to use to create the prompt function
+     * @param promptTemplateFactory Prompt template factory.
+     * @param <T> The return type of the function.
+     * @return The created KernelFunction.
+     * @throws IOException If an error occurs while reading the YAML.
+     */
     public static <T> KernelFunction<T> fromPromptYaml(
         String yaml,
         @Nullable PromptTemplateFactory promptTemplateFactory
@@ -31,6 +37,13 @@ public class KernelFunctionYaml {
         return fromYaml(targetStream, promptTemplateFactory);
     }
 
+    /**
+     * Create a KernelFunction instance for a prompt function using the specified markdown text.
+     * @param yaml YAML representation of the PromptTemplateConfig to use to create the prompt function
+     * @param <T> The return type of the function.
+     * @return The created KernelFunction.
+     * @throws IOException If an error occurs while reading the YAML.
+     */
     public static <T> KernelFunction<T> fromPromptYaml(
         String yaml
     ) throws IOException {
@@ -38,13 +51,20 @@ public class KernelFunctionYaml {
         return fromYaml(targetStream, null);
     }
 
+    /**
+     * Create a KernelFunction instance for a prompt function using the specified markdown text.
+     * @param filePath Path to the YAML representation of the PromptTemplateConfig to use to create the prompt function
+     * @param <T> The return type of the function.
+     * @return The created KernelFunction.
+     * @throws IOException If an error occurs while reading the YAML.
+     */
     public static <T> KernelFunction<T> fromYaml(Path filePath) throws IOException {
         InputStream inputStream = Thread.currentThread().getContextClassLoader()
             .getResourceAsStream(filePath.toString());
         return fromYaml(inputStream, null);
     }
 
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings({"unchecked", "rawtypes"})
     private static <T> KernelFunction<T> fromYaml(
         InputStream inputStream,
         @Nullable PromptTemplateFactory promptTemplateFactory

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/PromptExecutionSettings.java

@@ -2,13 +2,18 @@ package com.microsoft.semantickernel.orchestration;
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+
 import javax.annotation.Nullable;
 
+/**
+ * Configuration settings for prompt execution.
+ */
 public class PromptExecutionSettings {
 
     public static final String DEFAULT_SERVICE_ID = "default";
@@ -33,18 +38,8 @@ public class PromptExecutionSettings {
     private static final String RESULTS_PER_PROMPT = "results_per_prompt";
     private static final String TOKEN_SELECTION_BIASES = "token_selection_biases";
 
-    /// <summary>
-    /// Service identifier.
-    /// This identifies a service and is set when the AI service is registered.
-    /// </summary>
     private final String serviceId;
-
-    /// <summary>
-    /// Model identifier.
-    /// This identifies the AI model these settings are configured for e.g., gpt-4, gpt-3.5-turbo
-    /// </summary>
     private final String modelId;
-
     private final double temperature;
     private final double topP;
     private final double presencePenalty;
@@ -55,13 +50,23 @@ public class PromptExecutionSettings {
     private final String user;
     @Nullable
     private final List<String> stopSequences;
+    private Map<Integer, Integer> tokenSelectionBiases;
 
-    /// <summary>
-    /// Modify the likelihood of specified tokens appearing in the completion.
-    /// </summary>s
-    @Nullable
-    public Map<Integer, Integer> tokenSelectionBiases;
-
+    /**
+     * Create a new instance of PromptExecutionSettings.
+     * @param serviceId The id of the AI service to use for prompt execution.
+     * @param modelId The id of the model to use for prompt execution.
+     * @param temperature The temperature setting for prompt execution.
+     * @param topP The topP setting for prompt execution.
+     * @param presencePenalty The presence penalty setting for prompt execution.
+     * @param frequencyPenalty The frequency penalty setting for prompt execution.
+     * @param maxTokens The maximum number of tokens to generate in the output.
+     * @param resultsPerPrompt The number of results to generate for each prompt.
+     * @param bestOf The best of setting for prompt execution.
+     * @param user The user to associate with the prompt execution.
+     * @param stopSequences The stop sequences to use for prompt execution.
+     * @param tokenSelectionBiases The token selection biases to use for prompt execution.
+     */
     @JsonCreator
     public PromptExecutionSettings(
         @JsonProperty(SERVICE_ID) String serviceId,
@@ -80,72 +85,127 @@ public class PromptExecutionSettings {
         @JsonProperty(TOKEN_SELECTION_BIASES) Map<Integer, Integer> tokenSelectionBiases) {
         this.serviceId = serviceId;
         this.modelId = modelId;
-        this.temperature = temperature;
-        this.topP = topP;
-        this.presencePenalty = presencePenalty;
-        this.frequencyPenalty = frequencyPenalty;
-        this.maxTokens = maxTokens;
-        this.resultsPerPrompt = resultsPerPrompt;
-        this.bestOf = bestOf;
+        this.temperature = clamp(temperature, 0d, 2d, DEFAULT_TEMPERATURE);
+        this.topP = clamp(topP, 0d, 1d, DEFAULT_TOP_P);
+        this.presencePenalty = clamp(presencePenalty, -2d, 2d, DEFAULT_PRESENCE_PENALTY);
+        this.frequencyPenalty = clamp(frequencyPenalty, -2d, 2d, DEFAULT_FREQUENCY_PENALTY);
+        this.maxTokens = clamp(maxTokens, 1, Integer.MAX_VALUE);
+        this.resultsPerPrompt = clamp(resultsPerPrompt, 1, Integer.MAX_VALUE);
+        this.bestOf = clamp(bestOf, 1, Integer.MAX_VALUE); ;
         this.user = user;
         this.stopSequences =
             stopSequences != null ? new ArrayList<>(stopSequences) : Collections.emptyList();
         this.tokenSelectionBiases =
-            tokenSelectionBiases != null ? new HashMap<>(tokenSelectionBiases)
+            tokenSelectionBiases != null 
+                ? new HashMap<>(tokenSelectionBiases)
                 : Collections.emptyMap();
+        this.tokenSelectionBiases.replaceAll((k, v) -> clamp(v, -100, 100));
     }
 
+    /**
+     * Get the id of the AI service to use for prompt execution.
+     * @return The id of the AI service to use for prompt execution.
+     */
     @JsonProperty(SERVICE_ID)
     public String getServiceId() {
         return serviceId;
     }
 
+    /**
+     * Get the id of the model to use for prompt execution.
+     * @return The id of the model to use for prompt execution.
+     */
     @JsonProperty(MODEL_ID)
     public String getModelId() {
         return modelId;
     }
 
+    /**
+     * The temperature setting controls the randomness of the output. Lower values produce more
+     * deterministic outputs, while higher values produce more random outputs.
+     * @return The temperature setting.
+     */
     @JsonProperty(TEMPERATURE)
     public double getTemperature() {
         return Double.isNaN(temperature) ? DEFAULT_TEMPERATURE : temperature;
     }
 
+    /**
+     * The topP setting controls how many different words or phrases are considered to predict the
+     * next token. The value is a probability threshold, and the model considers the most likely
+     * tokens whose cumulative probability mass is greater than the threshold. For example, if the
+     * value is 0.1, the model considers only the tokens that make up the top 10% of the cumulative
+     * probability mass.
+     * @return The topP setting.
+     */
     @JsonProperty(TOP_P)
     public double getTopP() {
         return topP;
     }
 
+    /**
+     * Presence penalty encourages the model to use a more or less diverse range of tokens in the output.
+     * A higher value means that the model will try to use a greater variety of tokens
+     * in the ouput.
+     * @return The presence penalty setting.
+     */
     @JsonProperty(PRESENCE_PENALTY)
     public double getPresencePenalty() {
         return presencePenalty;
     }
 
+    /**
+     * Frequency penalty encourages the model to avoid repeating the same token in the output. 
+     * A higher value means that the model will be less likely to repeat a token.
+     * 
+     * @return The frequency penalty setting.
+     */
     @JsonProperty(FREQUENCY_PENALTY)
     public double getFrequencyPenalty() {
         return frequencyPenalty;
     }
 
+    /**
+     * The maximum number of tokens to generate in the output.
+     * @return The maximum number of tokens to generate in the output.
+     */
     @JsonProperty(MAX_TOKENS)
     public int getMaxTokens() {
         return maxTokens;
     }
 
+    /**
+     * The number of results to generate for each prompt. 
+     * @return The number of results to generate for each prompt.
+     */
     @JsonProperty(RESULTS_PER_PROMPT)
     public int getResultsPerPrompt() {
         return resultsPerPrompt;
     }
 
+    /**
+     * The log probability threshold for a result to be considered. 
+     * @return The log probability threshold for a result to be considered.
+     */
     @JsonProperty(BEST_OF)
     public int getBestOf() {
         // TODO: not present in com.azure:azure-ai-openai
         return bestOf;
     }
 
+    /**
+     * The user to associate with the prompt execution.
+     * @return The user to associate with the prompt execution.
+     */
     @JsonProperty(USER)
     public String getUser() {
         return user;
     }
 
+    /**
+     * The stop sequences to use for prompt execution.
+     * @return The stop sequences to use for prompt execution.
+     */
     @JsonProperty(STOP_SEQUENCES)
     @Nullable
     public List<String> getStopSequences() {
@@ -155,6 +215,12 @@ public class PromptExecutionSettings {
         return null;
     }
 
+    /**
+     * The token selection biases to use for prompt execution. The key is the token id 
+     * from the tokenizer, and the value is the bias. A negative bias will make the model less likely
+     * to use the token, and a positive bias will make the model more likely to use the token.
+     * @return The token selection biases to use for prompt execution.
+     */
     @JsonProperty(TOKEN_SELECTION_BIASES)
     @Nullable
     public Map<Integer, Integer> getTokenSelectionBiases() {
@@ -164,25 +230,48 @@ public class PromptExecutionSettings {
         return null;
     }
 
+    /**
+     * Create a new builder for PromptExecutionSettings.
+     * @return A new builder for PromptExecutionSettings.
+     */
     public static Builder builder() {
         return new Builder();
     }
 
 
+    /**
+     * Builder for PromptExecutionSettings.
+     */
     public static class Builder {
 
         Map<String, Object> settings = new HashMap<>();
 
+        /**
+         * Set the id of the AI service to use for prompt execution.
+         * @param serviceId The id of the AI service to use for prompt execution.
+         * @return This builder.
+         */
         public Builder withServiceId(String serviceId) {
             settings.put(SERVICE_ID, serviceId);
             return this;
         }
 
+        /**
+         * Set the id of the model to use for prompt execution.
+         * @param modelId The id of the model to use for prompt execution.
+         * @return This builder.
+         */
         public Builder withModelId(String modelId) {
             settings.put(MODEL_ID, modelId);
             return this;
         }
 
+        /**
+         * Set the temperature setting for prompt execution. The value is
+         * clamped to the range [0.0, 2.0], and the default is 1.0.
+         * @param temperature The temperature setting for prompt execution.
+         * @return This builder.
+         */
         public Builder withTemperature(double temperature) {
             if (!Double.isNaN(temperature)) {
                 settings.put(TEMPERATURE, temperature);
@@ -190,6 +279,12 @@ public class PromptExecutionSettings {
             return this;
         }
 
+        /**
+         * Set the topP setting for prompt execution. The value is clamped to the range [0.0, 1.0],
+         * and the default is 1.0.
+         * @param topP The topP setting for prompt execution.
+         * @return This builder.
+         */
         public Builder withTopP(double topP) {
             if (!Double.isNaN(topP)) {
                 settings.put(TOP_P, topP);
@@ -197,6 +292,12 @@ public class PromptExecutionSettings {
             return this;
         }
 
+        /**
+         * Set the presence penalty setting for prompt execution. The value is clamped to the range
+         * [-2.0, 2.0], and the default is 0.0.
+         * @param presencePenalty The presence penalty setting for prompt execution.
+         * @return This builder.
+         */
         public Builder withPresencePenalty(double presencePenalty) {
             if (!Double.isNaN(presencePenalty)) {
                 settings.put(PRESENCE_PENALTY, presencePenalty);
@@ -204,6 +305,12 @@ public class PromptExecutionSettings {
             return this;
         }
 
+        /**
+         * Set the frequency penalty setting for prompt execution. The value is clamped to the range
+         * [-2.0, 2.0], and the default is 0.0.
+         * @param frequencyPenalty The frequency penalty setting for prompt execution.
+         * @return This builder.
+         */
         public Builder withFrequencyPenalty(double frequencyPenalty) {
             if (!Double.isNaN(frequencyPenalty)) {
                 settings.put(FREQUENCY_PENALTY, frequencyPenalty);
@@ -211,26 +318,54 @@ public class PromptExecutionSettings {
             return this;
         }
 
+        /**
+         * Set the maximum number of tokens to generate in the output. The value is clamped to the
+         * range [1, Integer.MAX_VALUE], and the default is 256.
+         * @param maxTokens The maximum number of tokens to generate in the output.
+         * @return This builder.
+         */
         public Builder withMaxTokens(int maxTokens) {
             settings.put(MAX_TOKENS, maxTokens);
             return this;
         }
 
+        /**
+         * Set the number of results to generate for each prompt. The value is clamped to the
+         * range [1, Integer.MAX_VALUE], and the default is 1.
+         * @param resultsPerPrompt The number of results to generate for each prompt.
+         * @return This builder.
+         */
         public Builder withResultsPerPrompt(int resultsPerPrompt) {
             settings.put(RESULTS_PER_PROMPT, resultsPerPrompt);
             return this;
         }
 
+        /**
+         * Set the best of setting for prompt execution. The value is clamped to the
+         * range [1, Integer.MAX_VALUE], and the default is 1.
+         * @param bestOf The best of setting for prompt execution.
+         * @return This builder.
+         */
         public Builder withBestOf(int bestOf) {
             settings.put(BEST_OF, bestOf);
             return this;
         }
 
+        /**
+         * Set the user to associate with the prompt execution.
+         * @param user The user to associate with the prompt execution.
+         * @return This builder.
+         */
         public Builder withUser(String user) {
             settings.put(USER, user);
             return this;
         }
 
+        /**
+         * Set the stop sequences to use for prompt execution.
+         * @param stopSequences The stop sequences to use for prompt execution.
+         * @return This builder.
+         */
         @SuppressWarnings("unchecked")
         public Builder withStopSequences(List<String> stopSequences) {
             if (stopSequences != null) {
@@ -240,6 +375,12 @@ public class PromptExecutionSettings {
             return this;
         }
 
+        /**
+         * Set the token selection biases to use for prompt execution. The bias values
+         * are clamped to the range [-100, 100].
+         * @param tokenSelectionBiases The token selection biases to use for prompt execution.
+         * @return This builder.
+         */
         @SuppressWarnings("unchecked")
         public Builder withTokenSelectionBiases(Map<Integer, Integer> tokenSelectionBiases) {
             if (tokenSelectionBiases != null) {
@@ -249,6 +390,10 @@ public class PromptExecutionSettings {
             return this;
         }
 
+        /**
+         * Build the PromptExecutionSettings.
+         * @return A new PromptExecutionSettings from this builder.
+         */
         @SuppressWarnings("unchecked")
         public PromptExecutionSettings build() {
             return new PromptExecutionSettings(
@@ -268,4 +413,15 @@ public class PromptExecutionSettings {
             );
         }
     }
+
+    private static double clamp(double value, double min, double max, double defaultValue) {
+        if (Double.isNaN(value)) {
+            return defaultValue;
+        }
+        return Math.max(min, Math.min(max, value));
+    }  
+    
+    private static int clamp(int value, int min, int max) {
+        return Math.max(min, Math.min(max, value));
+    }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/ToolCallBehavior.java

@@ -15,7 +15,7 @@ public class ToolCallBehavior {
         private final boolean required;
         private final boolean enabled;
 
-        FunctionCallBehavior(KernelFunction function, boolean required, boolean enabled) {
+        FunctionCallBehavior(KernelFunction<?> function, boolean required, boolean enabled) {
             this.required = required;
             this.enabled = enabled;
         }
@@ -28,7 +28,7 @@ public class ToolCallBehavior {
             return enabled;
         }
 
-        static String getKey(KernelFunction function) {
+        static String getKey(KernelFunction<?> function) {
             return getKey(function.getPluginName(), function.getName());
         }
 
@@ -41,30 +41,70 @@ public class ToolCallBehavior {
     private final Map<String, FunctionCallBehavior> functionSettings = new HashMap<>();
     private final Map<String, Integer> settings = new HashMap<>();
 
+    /**
+     * Create a new instance of ToolCallBehavior with defaults.
+     */
     public ToolCallBehavior() {
     }
 
+    /**
+     * Create a copy of the other ToolCallBehavior.
+     *
+     * @param toolCallBehavior The behavior to copy.
+     */
     public ToolCallBehavior(ToolCallBehavior toolCallBehavior) {
         flags.putAll(toolCallBehavior.flags);
         functionSettings.putAll(toolCallBehavior.functionSettings);
         settings.putAll(toolCallBehavior.settings);
     }
 
+    /**
+     * Create an unmodifiable copy of this ToolCallBehavior.
+     * @return An unmodifiable copy of this ToolCallBehavior.
+     */
     public UnmodifiableToolCallBehavior unmodifiableClone() {
         return new UnmodifiableToolCallBehavior(this);
     }
 
+    /**
+     * Enable or disable kernel functions. If kernel functions
+     * are disabled, they will not be passed to the model. This
+     * is the default behavior.
+     *
+     * @param enable Whether to enable kernel functions.
+     * @return This ToolCallBehavior.
+     */
     public ToolCallBehavior kernelFunctions(boolean enable) {
         setFlag("kernelFunctions", enable);
         return this;
     }
 
+    /**
+     * Enable or disable auto-invocation. If auto-invocation is
+     * enabled, the model may request that the Semantic Kernel
+     * invoke functions and return the value to the model. The 
+     * default behavior is to disable auto-invocation.
+     *
+     * @param enable Whether to enable auto-invocation.
+     * @return This ToolCallBehavior.
+     */
     public ToolCallBehavior autoInvoke(boolean enable) {
-        setFlag("autoInvoke", true);
+        setFlag("autoInvoke", enable);
         return this;
     }
 
-    public ToolCallBehavior requireFunction(KernelFunction function, boolean require) {
+    /**
+     * Require or not require a function to be called. If a function
+     * is required, it will be called. If it is not required, it may
+     * be called if {@code auto-invcation} is enabled. Whether the functions
+     * are passed to the model is controlled by whether {@code kernelFunctions}
+     * is enabled. By default, no functions are required.
+     *
+     * @param function The function to require or not require.
+     * @param require  Whether to require the function.
+     * @return This ToolCallBehavior.
+     */
+    public ToolCallBehavior requireFunction(KernelFunction<?> function, boolean require) {
         if (function != null) {
             String key = FunctionCallBehavior.getKey(function);
             functionSettings.compute(
@@ -81,7 +121,18 @@ public class ToolCallBehavior {
         return this;
     }
 
-    public ToolCallBehavior enableFunction(KernelFunction function, boolean enable) {
+    /**
+     * Enable or disable a function. If a function is enabled, it
+     * may be called. If it is not enabled, it will not be called.
+     * By default, all functions are enabled. Whether the functions
+     * are passed to the model is controlled by whether {@code kernelFunctions}
+     * is enabled.
+     *
+     * @param function The function to enable or disable.
+     * @param enable   Whether to enable the function.
+     * @return This ToolCallBehavior.
+     */
+    public ToolCallBehavior enableFunction(KernelFunction<?> function, boolean enable) {
         if (function != null) {
             String key = FunctionCallBehavior.getKey(function);
             functionSettings.compute(
@@ -98,26 +149,55 @@ public class ToolCallBehavior {
         return this;
     }
 
+    /**
+     * Set the maximum number of times that auto-invocation will be attempted.
+     * If auto-invocation is enabled, the model may request that the Semantic Kernel
+     * invoke functions and return the value to the model. If the maximum number of
+     * attempts is reached, the model will be notified that the function could not be
+     * invoked. The default maximum number of attempts is 5.
+     *
+     * @param maximumAutoInvokeAttempts The maximum number of attempts.
+     * @return This ToolCallBehavior.
+     */
     public ToolCallBehavior maximumAutoInvokeAttempts(int maximumAutoInvokeAttempts) {
         setSetting("maximumAutoInvokeAttempts", maximumAutoInvokeAttempts);
         return this;
     }
 
+    /**
+     * Check whether kernel functions are enabled.
+     * @return Whether kernel functions are enabled.
+     */
     public boolean kernelFunctionsEnabled() {
         return getFlag("kernelFunctions");
     }
 
+    /**
+     * Check whether auto-invocation is enabled.
+     * @return Whether auto-invocation is enabled.
+     */
     public boolean autoInvokeEnabled() {
         return getFlag("autoInvoke");
     }
 
-    public boolean functionRequired(KernelFunction function) {
+    /**
+     * Check whether the given function is required.
+     * @param function The function to check.
+     * @return Whether the function is required.
+     */
+    public boolean functionRequired(KernelFunction<?> function) {
         if (function != null) {
             return functionRequired(function.getPluginName(), function.getName());
         }
         return false;
     }
 
+    /**
+     * Check whether the given function is required.
+     * @param pluginName   The name of the skill that the function is in.
+     * @param functionName The name of the function.
+     * @return Whether the function is required.
+     */
     public boolean functionRequired(String pluginName, String functionName) {
         String key = FunctionCallBehavior.getKey(pluginName, functionName);
         if (functionSettings.containsKey(key)) {
@@ -126,7 +206,12 @@ public class ToolCallBehavior {
         return false;
     }
 
-    public boolean functionEnabled(KernelFunction function) {
+    /**
+     * Check whether the given function is enabled.
+     * @param function The function to check.
+     * @return Whether the function is enabled.
+     */
+    public boolean functionEnabled(KernelFunction<?> function) {
 
         if (function != null) {
             return functionEnabled(function.getPluginName(), function.getName());
@@ -134,6 +219,12 @@ public class ToolCallBehavior {
         return functionSettings.isEmpty();
     }
 
+    /**
+     * Check whether the given function is enabled.
+     * @param pluginName   The name of the skill that the function is in.
+     * @param functionName The name of the function.
+     * @return Whether the function is enabled.
+     */
     public boolean functionEnabled(String pluginName, String functionName) {
 
         String key = FunctionCallBehavior.getKey(pluginName, functionName);
@@ -143,26 +234,54 @@ public class ToolCallBehavior {
         return functionSettings.isEmpty();
     }
 
+    /**
+     * Get the maximum number of times that auto-invocation will be attempted.
+     * @return The maximum number of attempts.
+     */
     public int maximumAutoInvokeAttempts() {
         return getSetting("maximumAutoInvokeAttempts", DEFAULT_MAXIMUM_AUTO_INVOKE_ATTEMPTS);
     }
 
+    /**
+     * Set a flag.
+     * @param key The key for the flag
+     * @param value The value for the flag
+     */
     protected void setFlag(String key, boolean value) {
         flags.put(key, value);
     }
 
+    /**
+     * Set a setting.
+     * @param key The key for the setting
+     * @param value The value for the setting
+     */
     protected void setSetting(String key, int value) {
         settings.put(key, value);
     }
 
+    /**
+     * Get a flag.
+     * @param key The key for the flag
+     * @return The value for the flag
+     */
     protected boolean getFlag(String key) {
         return flags.getOrDefault(key, false);
     }
 
+    /**
+     * Get a setting.
+     * @param key The key for the setting
+     * @param defaultValue The default value for the setting
+     * @return The value for the setting
+     */
     protected int getSetting(String key, int defaultValue) {
         return settings.getOrDefault(key, defaultValue);
     }
 
+    /**
+     * An unmodifiable instance of ToolCallBehavior.
+     */
     public static class UnmodifiableToolCallBehavior extends ToolCallBehavior {
 
         protected UnmodifiableToolCallBehavior(ToolCallBehavior toolCallBehavior) {
@@ -180,12 +299,12 @@ public class ToolCallBehavior {
         }
 
         @Override
-        public final ToolCallBehavior requireFunction(KernelFunction function, boolean require) {
+        public final ToolCallBehavior requireFunction(KernelFunction<?> function, boolean require) {
             throw new UnsupportedOperationException("unmodifiable instance of ToolCallBehavior");
         }
 
         @Override
-        public final ToolCallBehavior enableFunction(KernelFunction function, boolean enable) {
+        public final ToolCallBehavior enableFunction(KernelFunction<?> function, boolean enable) {
             throw new UnsupportedOperationException("unmodifiable instance of ToolCallBehavior");
         }
 

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/CaseInsensitiveMap.java

@@ -7,15 +7,27 @@ import java.util.Map;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.stream.Collectors;
+
 import javax.annotation.Nullable;
 
+/**
+ * A {@code java.util.HashMap} in which the keys are case-insensitive.
+ * @param <T> the type of the value
+ */
 public class CaseInsensitiveMap<T> extends HashMap<String, T> {
 
+    /**
+     * Creates a new instance of the {@link CaseInsensitiveMap} class.
+     * @param kvMap the map
+     */
     public CaseInsensitiveMap(Map<String, T> kvMap) {
         super();
         putAll(kvMap);
     }
 
+    /**
+     * Creates a new instance of the {@link CaseInsensitiveMap} class.
+     */
     public CaseInsensitiveMap() {
         super();
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/ContextVariable.java

@@ -4,11 +4,19 @@ package com.microsoft.semantickernel.orchestration.contextvariables;
 import com.azure.ai.openai.models.CompletionsUsage;
 import com.microsoft.semantickernel.exceptions.SKException;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter.NoopConverter;
+
 import java.time.OffsetDateTime;
 import java.util.Collections;
 import java.util.Objects;
+
 import javax.annotation.Nullable;
 
+/**
+ * A context variable wraps an arbitrary value and a {@code ContextVariableType}. 
+ * {@code ContextVariableType} is used throughout the Semantic Kernel for passing
+ * arguments to functions and as function return types. 
+ * @param <T> the type of the context variable
+ */
 public class ContextVariable<T> {
 
     private final ContextVariableType<T> type;
@@ -16,6 +24,11 @@ public class ContextVariable<T> {
     @Nullable
     private final T value;
 
+    /**
+     * Creates a new instance of the {@link ContextVariable} class.
+     * @param type the type
+     * @param value the value
+     */
     public ContextVariable(
         ContextVariableType<T> type,
         @Nullable T value) {
@@ -23,6 +36,14 @@ public class ContextVariable<T> {
         this.value = value;
     }
 
+    /**
+     * Converts the given value to the requested result type.
+     * @param <T> the type of the requested result
+     * @param <U> the type of the input value
+     * @param it the input value
+     * @param requestedResultType the requested result type
+     * @return the converted value
+     */
     public static <T, U> ContextVariable<T> convert(
         @Nullable
         U it,
@@ -34,6 +55,20 @@ public class ContextVariable<T> {
         );
     }
 
+    /**
+     * Converts the given value to the requested result type. The {@code ContextVariableTypes}
+     * parameter is used to find the appropriate converter for the input value and the requested
+     * result type.
+     * 
+     * @param <T> the type of the requested result
+     * @param <U> the type of the input value
+     * @param it the input value
+     * @param requestedResultType the requested result type
+     * @param contextVariableTypes the context variable types
+     * @return the converted value
+     * @throws SKException if a type converter cannot be found, or the input value 
+     *          cannot be converted to the requested result type
+     */
     public static <T, U> ContextVariable<T> convert(
         @Nullable
         U it,
@@ -126,6 +161,15 @@ public class ContextVariable<T> {
         throw new SKException("Unable to convert " + it.getClass() + " to " + requestedResultType);
     }
 
+    /**
+     * Creates a new instance of the {@link ContextVariable} class without using strong typing.
+     * 
+     * @param value the value
+     * @param clazz the class
+     * @param types the types
+     * @return the new instance
+     */
+    @SuppressWarnings({"rawtypes", "unchecked" })
     public static ContextVariable<?> untypedOf(
         @Nullable Object value,
         Class<?> clazz,
@@ -135,27 +179,62 @@ public class ContextVariable<T> {
         return new ContextVariable(type, value);
     }
 
+    /**
+     * Convenience method for creating a {@code ContextVariable} from the 
+     * given {@code CompletionsUsage} instance.
+     * @param x the value
+     * @return the new instance
+     */
     public static ContextVariable<CompletionsUsage> of(CompletionsUsage x) {
         return ofValue(x);
     }
 
+    /**
+     * Convenience method for creating a {@code ContextVariable} from the 
+     * given {@code OffsetDateTime} instance.
+     * @param x the value
+     * @return the new instance
+     */
     public static ContextVariable<OffsetDateTime> of(OffsetDateTime x) {
         return ofValue(x);
     }
 
+    /**
+     * Convenience method for creating a {@code ContextVariable} from the 
+     * given {@code String} instance.
+     * @param value the value
+     * @return the new instance
+     */
     public static ContextVariable<String> of(String value) {
         return ofValue(value);
     }
 
+    /**
+     * Convenience method for creating a {@code ContextVariable} from the 
+     * given object.
+     * @param x the object
+     * @return the new instance
+     */
     public static ContextVariable<Object> ofGlobalType(Object x) {
         return ofValue(x);
     }
 
+    /**
+     * Get the value of the context variable.
+     * @return the value
+     */
     @Nullable
     public T getValue() {
         return value;
     }
 
+    /**
+     * Get the value of the context variable.
+     * @param clazz the class
+     * @param <U> the type of the value
+     * @return the value
+     * @throws SKException if the value cannot be cast to the requested type
+     */
     @Nullable
     public <U> U getValue(Class<U> clazz) {
         try {
@@ -166,18 +245,39 @@ public class ContextVariable<T> {
         }
     }
 
+    /**
+     * Get the type of the context variable.
+     * @return the type
+     */
     public ContextVariableType<T> getType() {
         return type;
     }
 
+    /**
+     * Use the given {@code ContextVariableTypeConverter} to convert the
+     * value of this {@code ContextVariable} to a prompt string. This method
+     * is useful when the convert of this {@code ContextVariableType} does
+     * not create the expected prompt string.
+     * @param converter the converter to use when converting the value
+     * @return the value of this {@code ContextVariable} as a prompt string
+     */
     public String toPromptString(ContextVariableTypeConverter<T> converter) {
         return converter.toPromptString(value);
     }
 
+    /**
+     * Use the convert of the type of this {@code ContextVariable} to convert
+     * the value of this {@code ContextVariable} to a prompt string.
+     * @return the value of this {@code ContextVariable} as a prompt string
+     */
     public String toPromptString() {
         return toPromptString(type.getConverter());
     }
 
+    /** 
+     * Returns true if the value of this {@code ContextVariable} is {@code null} or empty.
+     * @return true if the value is {@code null} or empty
+     */
     public boolean isEmpty() {
         return value == null || value.toString().isEmpty();
     }
@@ -195,6 +295,13 @@ public class ContextVariable<T> {
         return new ContextVariable<>(type, value);
     }
 
+    /**
+     * Creates a new instance of the {@link ContextVariable} class.
+     * @param value the value
+     * @param converter the converter
+     * @param <T> the type of the value
+     * @return the new instance
+     */
     public static <T> ContextVariable<T> of(T value, ContextVariableTypeConverter<T> converter) {
         Objects.requireNonNull(value, "value cannot be null");
         Objects.requireNonNull(converter, "converter cannot be null");

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/ContextVariableType.java

@@ -2,21 +2,42 @@ package com.microsoft.semantickernel.orchestration.contextvariables;
 
 import javax.annotation.Nullable;
 
+/**
+ * A type of context variable, with a converter to convert objects to the type.
+ *
+ * @param <T> The type of the context variable.
+ */
 public class ContextVariableType<T> {
 
     private final ContextVariableTypeConverter<T> contextVariableTypeConverter;
     private final Class<T> clazz;
 
+    /**
+     * Create a new context variable type.
+     *
+     * @param contextVariableTypeConverter The converter to convert objects to the type.
+     * @param clazz The class of the type
+     */
     public ContextVariableType(ContextVariableTypeConverter<T> contextVariableTypeConverter,
         Class<T> clazz) {
         this.contextVariableTypeConverter = contextVariableTypeConverter;
         this.clazz = clazz;
     }
 
+    /**
+     * Get the converter for this type.
+     *
+     * @return The converter for this type.
+     */
     public ContextVariableTypeConverter<T> getConverter() {
         return contextVariableTypeConverter;
     }
 
+    /**
+     * Get the class of the type.
+     *
+     * @return The class of the type.
+     */
     public Class<T> getClazz() {
         return clazz;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/ContextVariableTypeConverter.java

@@ -11,6 +11,11 @@ import javax.annotation.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * A converter for a context variable type. This class is used to convert objects to and from a
+ * prompt string, and to convert objects to the type of the context variable.
+ * @param <T> the type of the context variable
+ */
 public class ContextVariableTypeConverter<T> {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(
@@ -22,15 +27,38 @@ public class ContextVariableTypeConverter<T> {
     private final Function<String, T> fromPromptString;
     private final List<Converter<T, ?>> toObjects;
 
+    /**
+     * A converter from one type to another.
+     * @param <T> the source type
+     * @param <U> the target type
+     */
     public interface Converter<T, U> {
 
+        /**
+         * Convert the object to the target type.
+         * @param t the object to convert
+         * @return the converted object
+         */
         U toObject(T t);
 
+        /**
+         * Get the class of the target type.
+         * @return the class of the target type
+         */
         Class<U> getTargetType();
     }
 
+    /**
+     * A converter that does no conversion. This converter is often used as a default when no
+     * other conveter can be found for the type. 
+     * @param <T> the type of the context variable
+     */
     public static class NoopConverter<T> extends ContextVariableTypeConverter<T> {
 
+        /**
+         * Create a new noop converter.
+         * @param clazz the class of the type
+         */
         public NoopConverter(Class<T> clazz) {
             super(
                 clazz,
@@ -46,6 +74,11 @@ public class ContextVariableTypeConverter<T> {
         }
     }
 
+    /**
+     * A base class for concrete implementations of {@link ContextVariableTypeConverter.Converter}.
+     * @param <T> the source type
+     * @param <U> the target type
+     */
     public static abstract class DefaultConverter<T, U> implements Converter<T, U> {
 
         private final Class<U> targetType;
@@ -60,6 +93,13 @@ public class ContextVariableTypeConverter<T> {
         }
     }
 
+    /**
+     * Create a new context variable type converter.
+     * @param clazz the class of the type
+     * @param fromObject a function to convert an object to the type
+     * @param toPromptString a function to convert the type to a prompt string
+     * @param fromPromptString a function to convert a prompt string to the type
+     */
     public ContextVariableTypeConverter(
         Class<T> clazz,
         Function<Object, T> fromObject,
@@ -68,6 +108,14 @@ public class ContextVariableTypeConverter<T> {
         this(clazz, fromObject, toPromptString, fromPromptString, Collections.emptyList());
     }
 
+    /**
+     * Create a new context variable type converter.
+     * @param clazz the class of the type
+     * @param fromObject a function to convert an object to the type
+     * @param toPromptString a function to convert the type to a prompt string
+     * @param fromPromptString a function to convert a prompt string to the type
+     * @param toObjects a list of converters to convert the type to other types
+     */
     public ContextVariableTypeConverter(
         Class<T> clazz,
         Function<Object, T> fromObject,
@@ -82,6 +130,13 @@ public class ContextVariableTypeConverter<T> {
     }
 
 
+    /**
+     * Use this converter to convert the object to the type of the context variable.
+     * @param <U> the type to convert to
+     * @param t the object to convert
+     * @param clazz the class of the type to convert to
+     * @return the converted object
+     */
     @Nullable
     @SuppressWarnings("unchecked")
     public <U> U toObject(@Nullable Object t, Class<U> clazz) {
@@ -111,6 +166,12 @@ public class ContextVariableTypeConverter<T> {
         return null;
     }
 
+    /**
+     * Convert the object to the type of the context variable using the {@code fromObject} function
+     * provided to the constructor.
+     * @param s the object to convert
+     * @return the converted object
+     */
     @Nullable
     public T fromObject(@Nullable Object s) {
         if (s == null) {
@@ -119,6 +180,12 @@ public class ContextVariableTypeConverter<T> {
         return fromObject.apply(s);
     }
 
+    /**
+     * Convert the type to a prompt string using the {@code toPromptString} function provided to the
+     * constructor.
+     * @param t the type to convert
+     * @return the prompt string
+     */
     public String toPromptString(@Nullable T t) {
         if (t == null) {
             return "";
@@ -126,6 +193,12 @@ public class ContextVariableTypeConverter<T> {
         return toPromptString.apply(t);
     }
 
+    /**
+     * Convert the prompt string to the type using the {@code fromPromptString} function provided to
+     * the constructor.
+     * @param t the prompt string to convert
+     * @return the type
+     */
     @Nullable
     public T fromPromptString(@Nullable String t) {
         if (t == null) {
@@ -134,6 +207,10 @@ public class ContextVariableTypeConverter<T> {
         return fromPromptString.apply(t);
     }
 
+    /**
+     * Get the class of the type.
+     * @return the class of the type
+     */
     public Class<T> getType() {
         return clazz;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/ContextVariableTypes.java

@@ -1,12 +1,5 @@
 package com.microsoft.semantickernel.orchestration.contextvariables;
 
-import java.util.Arrays;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.exceptions.SKException;
 import com.microsoft.semantickernel.orchestration.contextvariables.converters.BooleanVariableContextVariableTypeConverter;
 import com.microsoft.semantickernel.orchestration.contextvariables.converters.CharacterVariableContextVariableTypeConverter;
@@ -18,6 +11,16 @@ import com.microsoft.semantickernel.orchestration.contextvariables.converters.Nu
 import com.microsoft.semantickernel.orchestration.contextvariables.converters.StringVariableContextVariableTypeConverter;
 import com.microsoft.semantickernel.orchestration.contextvariables.converters.VoidVariableContextVariableTypeConverter;
 
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import javax.annotation.Nullable;
+
+/**
+ * A collection of context variable types, with converters to convert objects to the types.
+ */
 public class ContextVariableTypes {
 
     private static final ContextVariableTypes DEFAULT_TYPES;
@@ -69,28 +72,58 @@ public class ContextVariableTypes {
 
     private final Map<Class<?>, ContextVariableType<?>> variableTypes;
 
+    /**
+     * Create a new collection of context variable types.
+     *
+     * @param converters The converters to use to convert objects to the types.
+     */
     public ContextVariableTypes(List<ContextVariableTypeConverter<?>> converters) {
         variableTypes = new HashMap<>();
         converters.forEach(this::putConverter);
     }
 
+    /**
+     * Create a new collection of context variable types.
+     */
     public ContextVariableTypes() {
         variableTypes = new HashMap<>();
     }
 
+    /**
+     * Create a new collection of context variable types.
+     *
+     * @param contextVariableTypes The collection of context variable types to copy.
+     */
     public ContextVariableTypes(ContextVariableTypes contextVariableTypes) {
         this.variableTypes = new HashMap<>(contextVariableTypes.variableTypes);
     }
 
+    /**
+     * Add a converter to the global collection of context variable type converters.
+     * @param conveter The converter to add.
+     * @see #getGlobalVariableTypeForClass(Class)
+     */
     public static void addGlobalConverter(
-        ContextVariableTypeConverter<?> type) {
-        DEFAULT_TYPES.putConverter(type);
+        ContextVariableTypeConverter<?> conveter) {
+        DEFAULT_TYPES.putConverter(conveter);
     }
 
+    /**
+     * Get the global context variable type for the given class.
+     * @param aClass The class to get the context variable type for.
+     * @param <T> The type of the context variable.
+     * @return The context variable type for the given class.
+     * @see #addGlobalConverter(ContextVariableTypeConverter)
+     */
     public static <T> ContextVariableType<T> getGlobalVariableTypeForClass(Class<T> aClass) {
         return DEFAULT_TYPES.getVariableTypeForClass(aClass);
     }
 
+    /**
+     * Add a converter to this {@code ContextVariableTypes} instance.
+     * @param <T> The type of the context variable.
+     * @param contextVariableTypeConverter the converter to add.
+     */
     public <T> void putConverter(
         ContextVariableTypeConverter<T> contextVariableTypeConverter) {
         variableTypes.put(contextVariableTypeConverter.getType(),
@@ -98,6 +131,13 @@ public class ContextVariableTypes {
                 contextVariableTypeConverter.getType()));
     }
 
+    /**
+     * Convert the given object to the given class, if possible.
+     * @param <T> the type to convert to
+     * @param s the object to convert
+     * @param clazz the class of the type to convert to
+     * @return the converted object, or {@code null} if the object cannot be converted
+     */
     @Nullable
     @SuppressWarnings("unchecked")
     public static <T> T convert(@Nullable Object s, Class<T> clazz) {
@@ -113,6 +153,13 @@ public class ContextVariableTypes {
     }
 
 
+    /**
+     * Get the context variable type for the given class.
+     * @param aClass The class to get the context variable type for.
+     * @param <T> The type of the context variable.
+     * @return The context variable type for the given class
+     * @throws SKException if the type cannot be found.
+     */
     @SuppressWarnings("unchecked")
     public <T> ContextVariableType<T> getVariableTypeForClass(Class<T> aClass) {
         try {
@@ -122,6 +169,14 @@ public class ContextVariableTypes {
         }
     }
 
+    /**
+     * Get the context variable type for the given class or for a type that is assignable 
+     * from the given class. its super class.
+     * @param aClass The class to get the context variable type for.
+     * @param <T> The type of the context variable.
+     * @return The context variable type for the given class.
+     * @throws SKException if the type cannot be found.
+     */
     @SuppressWarnings("unchecked")
     public <T> ContextVariableType<T> getVariableTypeForSuperClass(Class<T> aClass) {
         try {
@@ -131,7 +186,6 @@ public class ContextVariableTypes {
         }
     }
 
-
     @SuppressWarnings("unchecked")
     private <T> ContextVariableType<T> getVariableTypeForClassInternal(Class<T> aClass) {
         ContextVariableType<?> contextVariableType = variableTypes.get(aClass);
@@ -170,6 +224,10 @@ public class ContextVariableTypes {
                 () -> new SKException("Unknown context variable type: " + aClass.getName()));
     }
 
+    /**
+     * Add all the converters from the given collection to this collection.
+     * @param contextVariableTypes The collection of converters to add.
+     */
     public void putConverters(ContextVariableTypes contextVariableTypes) {
         this.variableTypes.putAll(contextVariableTypes.variableTypes);
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/BooleanVariableContextVariableTypeConverter.java

@@ -1,12 +1,21 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
+import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
 import static com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes.convert;
 
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
-
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@link Boolean} variables. Use
+ * {@code ContextVariableTypes.getDefaultVariableTypeForClass(Boolean.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class BooleanVariableContextVariableTypeConverter extends
     ContextVariableTypeConverter<Boolean> {
 
+    /**
+     * Initializes a new instance of the {@link BooleanVariableContextVariableTypeConverter} class.
+     */
     public BooleanVariableContextVariableTypeConverter() {
         super(
             Boolean.class,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/CharacterVariableContextVariableTypeConverter.java

@@ -1,21 +1,33 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
-
 import static com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes.convert;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter}
+ * for {@code java.lang.Character} variables. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(Character.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class CharacterVariableContextVariableTypeConverter extends
     ContextVariableTypeConverter<Character> {
 
+    /**
+     * Initializes a new instance of the {@link CharacterVariableContextVariableTypeConverter} class.
+     */
     public CharacterVariableContextVariableTypeConverter() {
         super(
             Character.class,
             s -> convert(s, Character.class),
             Object::toString,
-            CharacterVariableContextVariableTypeConverter::charToPromptString);
+            CharacterVariableContextVariableTypeConverter::charFromPromptString);
     }
 
-    static Character charToPromptString(String s) {
+    /*
+     * Converts a prompt string to a Character.
+     */
+    static Character charFromPromptString(String s) {
         if (s.length() != 1) {
             throw new IllegalArgumentException("Cannot convert string to character: " + s);
         }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/ChatHistoryVariableContextVariableTypeConverter.java

@@ -1,13 +1,22 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
-import static com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes.convert;
-
 import com.microsoft.semantickernel.chatcompletion.ChatHistory;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
+import static com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes.convert;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code com.microsoft.semantickernel.chathistory.ChatHistory} variables. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(ChatHistory.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class ChatHistoryVariableContextVariableTypeConverter extends
     ContextVariableTypeConverter<ChatHistory> {
 
+    /**
+     * Initializes a new instance of the {@link ChatHistoryVariableContextVariableTypeConverter} class.
+     */
     public ChatHistoryVariableContextVariableTypeConverter() {
         super(
             ChatHistory.class,
@@ -20,6 +29,9 @@ public class ChatHistoryVariableContextVariableTypeConverter extends
         );
     }
 
+    /*
+     * Converts a {@link ChatHistory} to an XML string.
+     */
     private static String toXmlString(ChatHistory chatHistory) {
         return chatHistory
             .getMessages()

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/CompletionUsageContextVariableTypeConverter.java

@@ -3,9 +3,19 @@ package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 import com.azure.ai.openai.models.CompletionsUsage;
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code com.azure.ai.openai.models.CompletionsUsage} variables. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(CompletionsUsage.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class CompletionUsageContextVariableTypeConverter extends
     ContextVariableTypeConverter<CompletionsUsage> {
 
+    /**
+     * Creates a new instance of the {@link CompletionUsageContextVariableTypeConverter} class.
+     */
     public CompletionUsageContextVariableTypeConverter() {
         super(
             CompletionsUsage.class,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/DateTimeContextVariableTypeConverter.java

@@ -1,14 +1,25 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
+
 import java.time.Instant;
 import java.time.OffsetDateTime;
 import java.time.ZonedDateTime;
 import java.util.Arrays;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code java.time.OffsetDateTime} variables. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(OffsetDateTime.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class DateTimeContextVariableTypeConverter extends
     ContextVariableTypeConverter<OffsetDateTime> {
 
+    /**
+     * Creates a new instance of the {@link DateTimeContextVariableTypeConverter} class.
+     */
     public DateTimeContextVariableTypeConverter() {
         super(
             OffsetDateTime.class,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/InstantContextVariableTypeConverter.java

@@ -1,12 +1,23 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
+
 import java.time.Instant;
 import java.time.OffsetDateTime;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code java.time.Instant} variables. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(Instant.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class InstantContextVariableTypeConverter extends
     ContextVariableTypeConverter<Instant> {
 
+    /**
+     * Creates a new instance of the {@link InstantContextVariableTypeConverter} class.
+     */
     public InstantContextVariableTypeConverter() {
         super(
             Instant.class,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/NumberVariableContextVariableTypeConverter.java

@@ -1,16 +1,30 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
+import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
 import static com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes.convert;
 
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
 import java.util.function.Function;
+
 import javax.annotation.Nullable;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code java.lang.Number} type variables. Use, for example,
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(Integer.class)} 
+ * to get an instance of this class that works with the {@code Integer} type.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class NumberVariableContextVariableTypeConverter<T extends Number> extends
     ContextVariableTypeConverter<T> {
 
     private final Function<Number, T> fromNumber;
 
+    /**
+     * Creates a new instance of the {@link NumberVariableContextVariableTypeConverter} class.
+     * @param clazz the class
+     * @param fromPromptString the function to convert from a prompt string
+     * @param fromNumber the function to convert from a number
+     */
     public NumberVariableContextVariableTypeConverter(
         Class<T> clazz,
         Function<String, T> fromPromptString,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/StringVariableContextVariableTypeConverter.java

@@ -1,12 +1,21 @@
 package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
-
 import static com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes.convert;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code java.lang.String} variables. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(String.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class StringVariableContextVariableTypeConverter extends
     ContextVariableTypeConverter<String> {
 
+    /**
+     * Creates a new instance of the {@link StringVariableContextVariableTypeConverter} class.
+     */
     public StringVariableContextVariableTypeConverter() {
         super(
             String.class,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/orchestration/contextvariables/converters/VoidVariableContextVariableTypeConverter.java

@@ -2,9 +2,19 @@ package com.microsoft.semantickernel.orchestration.contextvariables.converters;
 
 import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
 
+/**
+ * A {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter} 
+ * for {@code java.lang.Void} types. Use
+ * {@code ContextVariableTypes.getGlobalVariableTypeForClass(Void.class)} 
+ * to get an instance of this class.
+ * @see com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypes#getGlobalVariableTypeForClass(Class)
+ */
 public class VoidVariableContextVariableTypeConverter extends
     ContextVariableTypeConverter<Void> {
 
+    /**
+     * Creates a new instance of the {@link VoidVariableContextVariableTypeConverter} class.
+     */
     public VoidVariableContextVariableTypeConverter() {
         super(
             Void.class,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelFunctionFactory.java

@@ -1,12 +1,5 @@
 package com.microsoft.semantickernel.plugin;
 
-import java.lang.reflect.Method;
-import java.util.HashMap;
-import java.util.List;
-import java.util.Map;
-
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.PromptExecutionSettings;
 import com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromMethod;
@@ -16,21 +9,30 @@ import com.microsoft.semantickernel.semanticfunctions.PromptTemplate;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateFactory;
 
+import java.lang.reflect.Method;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import javax.annotation.Nullable;
+
+/**
+ * Factory for creating {@link KernelFunction} instances.
+ */
 public class KernelFunctionFactory {
 
-
-    /// <summary>
-    /// Creates a <see cref="KernelFunction"/> instance for a method, specified via an <see cref="MethodInfo"/> instance
-    /// and an optional target object if the method is an instance method.
-    /// </summary>
-    /// <param name="method">The method to be represented via the created <see cref="KernelFunction"/>.</param>
-    /// <param name="target">The target object for the <paramref name="method"/> if it represents an instance method. This should be null if and only if <paramref name="method"/> is a static method.</param>
-    /// <param name="functionName">Optional function name. If null, it will default to one derived from the method represented by <paramref name="method"/>.</param>
-    /// <param name="description">Optional description of the method. If null, it will default to one derived from the method represented by <paramref name="method"/>, if possible (e.g. via a <see cref="DescriptionAttribute"/> on the method).</param>
-    /// <param name="parameters">Optional parameter descriptions. If null, it will default to one derived from the method represented by <paramref name="method"/>.</param>
-    /// <param name="returnParameter">Optional return parameter description. If null, it will default to one derived from the method represented by <paramref name="method"/>.</param>
-    /// <param name="loggerFactory">The <see cref="ILoggerFactory"/> to use for logging. If null, no logging will be performed.</param>
-    /// <returns>The created <see cref="KernelFunction"/> wrapper for <paramref name="method"/>.</returns>
+    /**
+     * Creates a {@link KernelFunction} instance for a method, specified via a {@link Method} instance
+     * @param <T> The return type of the method.
+     * @param method The method to be represented via the created {@link KernelFunction}.
+     * @param target The target object for the {@code method} if it represents an instance method. This should be {@code null} if and only if {@code method} is a static method.
+     * @param functionName Optional function name. If {@code null}, it will default to one derived from the method represented by {@code method}.
+     * @param description Optional description of the method. If {@code null}, it will default to one derived from the method represented by {@code method}, 
+     *                    if possible (e.g. via a {@link com.microsoft.semantickernel.plugin.annotations.DefineKernelFunction} on the method).
+     * @param parameters Optional parameter descriptions. If {@code null}, it will default to one derived from the method represented by {@code method}.
+     * @param returnParameter Optional return parameter description. If {@code null}, it will default to one derived from the method represented by {@code method}.
+     * @return The created {@link KernelFunction} wrapper for {@code method}.
+     */
     public static <T> KernelFunction<T> createFromMethod(
         Method method,
         Object target,
@@ -47,6 +49,7 @@ public class KernelFunctionFactory {
      * Creates a {@link KernelFunction} instance for a prompt specified via a prompt template.
      *
      * @param promptTemplate Prompt template for the function.
+     * @param <T>           Type of the value that the function will return
      * @return The created {@link KernelFunction} for invoking the prompt.
      */
     public static <T> KernelFunction<T> createFromPrompt(String promptTemplate) {
@@ -59,14 +62,15 @@ public class KernelFunctionFactory {
      * @param promptTemplate        Prompt template for the function.
      * @param executionSettings     Default execution settings to use when invoking this prompt
      *                              function.
-     * @param functionName          The name to use for the function. If null, it will default to a
+     * @param functionName          The name to use for the function. If {@code null}, it will default to a
      *                              randomly generated name.
      * @param description           The description to use for the function.
      * @param templateFormat        The template format of {@code promptTemplate}. This must be
-     *                              provided if {@code promptTemplateFactory} is not null.
+     *                              provided if {@code promptTemplateFactory} is not {@code null}.
      * @param promptTemplateFactory The {@link PromptTemplateFactory} to use when interpreting the
-     *                              {@code promptTemplate} into a {@link PromptTemplate}. If null, a
+     *                              {@code promptTemplate} into a {@link PromptTemplate}. If {@code null}, a
      *                              default factory will be used.
+     * @param <T>           Type of the value that the function will return
      * @return The created {@link KernelFunction} for invoking the prompt.
      */
     public static <T> KernelFunction<T> createFromPrompt(
@@ -85,6 +89,16 @@ public class KernelFunctionFactory {
             promptTemplateFactory);
     }
 
+    /**
+     * Creates a {@link KernelFunction} instance for a prompt specified via a {@link PromptTemplateConfig}.
+     *
+     * @param promptConfig        A prompt template configuration for the function.
+     * @param promptTemplateFactory The {@code PromptTemplateFactory} to use when interpreting
+     *                               the prompt template configuration into a {@link PromptTemplate}.
+     *                               If {@code null}, a default factory will be used.
+     * @param <T>           Type of the value that the function will return
+     * @return The created {@link KernelFunction} for invoking the prompt.
+     */
     public static <T> KernelFunction<T> createFromPrompt(
         PromptTemplateConfig promptConfig,
         @Nullable PromptTemplateFactory promptTemplateFactory) {
@@ -97,6 +111,14 @@ public class KernelFunctionFactory {
             promptConfig);
     }
 
+    /**
+     * Creates a {@link KernelFunction} instance for a prompt specified via a {@link PromptTemplateConfig}.
+     *
+     * @param promptConfig        A prompt template configuration for the function.
+     * @param promptTemplate The prompt template to use when creating the function.
+     * @param <T>           Type of the value that the function will return
+     * @return The created {@link KernelFunction} for invoking the prompt.
+     */
     public static <T> KernelFunction<T> create(
         PromptTemplate promptTemplate,
         PromptTemplateConfig promptConfig) {

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelParameterMetadata.java

@@ -2,11 +2,15 @@ package com.microsoft.semantickernel.plugin;
 
 import javax.annotation.Nullable;
 
+/**
+ * Metadata for a parameter to a kernel function. The Semantic Kernel creates
+ * this metadata from the annotations on the method that defines the function,
+ * or by introspection of a Java method. 
+ * @param <T> The type of the parameter.
+ */
 public class KernelParameterMetadata<T> {
 
-    /// <summary>The name of the parameter.</summary>
     private final String name;
-    /// <summary>The description of the parameter.</summary>
     @Nullable
     private final String description;
     @Nullable
@@ -14,6 +18,14 @@ public class KernelParameterMetadata<T> {
     private final boolean isRequired;
     private final Class<T> parameterType;
 
+    /**
+     * Creates a new instance of the {@link KernelParameterMetadata} class.
+     * @param name The name of the parameter.
+     * @param description The description of the parameter.
+     * @param parameterType The type of the parameter.
+     * @param defaultValue The default value of the parameter.
+     * @param isRequired Whether the parameter is required.
+     */
     public KernelParameterMetadata(
         String name,
         @Nullable
@@ -29,27 +41,45 @@ public class KernelParameterMetadata<T> {
         this.parameterType = parameterType;
     }
 
+    /**
+     * Gets the name of the parameter.
+     * @return The name of the parameter.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Gets the description of the parameter.
+     * @return The description of the parameter.
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
+    /**
+     * Gets the default value of the parameter.
+     * @return The default value of the parameter.
+     */
     @Nullable
     public String getDefaultValue() {
         return defaultValue;
     }
 
+    /**
+     * Gets whether the parameter is required.
+     * @return Whether the parameter is required.
+     */
     public boolean isRequired() {
         return isRequired;
     }
 
+    /**
+     * Gets the type of the parameter.
+     * @return The type of the parameter.
+     */
     public Class<?> getType() {
         return parameterType;
     }
-
-    //private KernelJsonSchema schema;
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelPlugin.java

@@ -2,11 +2,16 @@ package com.microsoft.semantickernel.plugin;
 
 import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.contextvariables.CaseInsensitiveMap;
+
 import java.util.Collections;
 import java.util.Iterator;
 import java.util.Map;
+
 import javax.annotation.Nullable;
 
+/**
+ * A plugin contains a collection of functions that can be invoked by the Semantic Kernel.
+ */
 public class KernelPlugin implements Iterable<KernelFunction<?>> {
 
     private final String name;
@@ -15,6 +20,12 @@ public class KernelPlugin implements Iterable<KernelFunction<?>> {
 
     private final CaseInsensitiveMap<KernelFunction<?>> functions;
 
+    /**
+     * Creates a new instance of the {@link KernelPlugin} class.
+     * @param name The name of the plugin.
+     * @param description The description of the plugin.
+     * @param plugins The functions in the plugin.
+     */
     public KernelPlugin(
         String name,
         @Nullable
@@ -28,29 +39,55 @@ public class KernelPlugin implements Iterable<KernelFunction<?>> {
         }
     }
 
+    /**
+     * Adds a function to the plugin.
+     * @param function The function to add.
+     */
     public void addFunction(KernelFunction<?> function) {
         functions.put(function.getName(), function);
     }
 
+    /**
+     * Gets the functions in the plugin.
+     * @return The functions in the plugin.
+     */
     public Map<String, KernelFunction<?>> getFunctions() {
         return Collections.unmodifiableMap(functions);
     }
 
+    /**
+     * Gets a function by name.
+     * @param functionName The name of the function.
+     * @param <T> The return type of the function.
+     * @return The function with the specified name, or {@code null} if no such function exists.
+     */
     @Nullable
     @SuppressWarnings("unchecked")
     public <T> KernelFunction<T> get(String functionName) {
         return (KernelFunction<T>) functions.get(functionName);
     }
 
+    /**
+     * Get an {@code Iterator} that iterates over the functions of this plugin.
+     * @return An {@code Iterator} that iterates over the functions of this plugin.
+     */
     @Override
     public Iterator<KernelFunction<?>> iterator() {
         return functions.values().iterator();
     }
 
+    /**
+     * Gets the name of the plugin.
+     * @return The name of the plugin.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Gets the description of the plugin.
+     * @return The description of the plugin.
+     */
     @Nullable
     public String getDescription() {
         return description;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelPluginFactory.java

@@ -1,5 +1,19 @@
 package com.microsoft.semantickernel.plugin;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.microsoft.semantickernel.exceptions.SKException;
+import com.microsoft.semantickernel.orchestration.KernelFunction;
+import com.microsoft.semantickernel.orchestration.contextvariables.CaseInsensitiveMap;
+import com.microsoft.semantickernel.plugin.annotations.DefineKernelFunction;
+import com.microsoft.semantickernel.plugin.annotations.KernelFunctionParameter;
+import com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromPrompt;
+import com.microsoft.semantickernel.semanticfunctions.KernelPromptTemplateFactory;
+import com.microsoft.semantickernel.semanticfunctions.PromptTemplate;
+import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
+import com.microsoft.semantickernel.semanticfunctions.PromptTemplateFactory;
+import com.microsoft.semantickernel.util.EmbeddedResourceLoader;
+import com.microsoft.semantickernel.util.EmbeddedResourceLoader.ResourceLocation;
+
 import java.io.File;
 import java.io.FileNotFoundException;
 import java.io.IOException;
@@ -20,36 +34,25 @@ import org.reactivestreams.Publisher;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.microsoft.semantickernel.exceptions.SKException;
-import com.microsoft.semantickernel.orchestration.KernelFunction;
-import com.microsoft.semantickernel.orchestration.contextvariables.CaseInsensitiveMap;
-import com.microsoft.semantickernel.plugin.annotations.DefineKernelFunction;
-import com.microsoft.semantickernel.plugin.annotations.KernelFunctionParameter;
-import com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromPrompt;
-import com.microsoft.semantickernel.semanticfunctions.KernelPromptTemplateFactory;
-import com.microsoft.semantickernel.semanticfunctions.PromptTemplate;
-import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
-import com.microsoft.semantickernel.semanticfunctions.PromptTemplateFactory;
-import com.microsoft.semantickernel.util.EmbeddedResourceLoader;
-import com.microsoft.semantickernel.util.EmbeddedResourceLoader.ResourceLocation;
-
+/**
+ * Factory for creating {@link KernelPlugin} instances. {@code KernelPlugin}s can be
+ * created from a Java object, from loading a directory of plugins, or from loading plugins
+ * from a resource. 
+ */
 public class KernelPluginFactory {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(KernelPluginFactory.class);
     private static final String CONFIG_FILE = "config.json";
     private static final String PROMPT_FILE = "skprompt.txt";
 
-    /// <summary>Creates a plugin that wraps the specified target object.</summary>
-    /// <param name="target">The instance of the class to be wrapped.</param>
-    /// <param name="pluginName">
-    /// Name of the plugin for function collection and prompt templates. If the value is null, a plugin name is derived from the type of the <paramref name="target"/>.
-    /// </param>
-    /// <param name="loggerFactory">The <see cref="ILoggerFactory"/> to use for logging. If null, no logging will be performed.</param>
-    /// <remarks>
-    /// Public methods decorated with <see cref="KernelFunctionAttribute"/> will be included in the plugin.
-    /// Attributed methods must all have different names; overloads are not supported.
-    /// </remarks>
+    /**
+     * Creates a plugin that wraps the specified target object. Methods decorated with 
+     * {@code {@literal @}DefineSKFunction} will be included in the plugin.
+     * 
+     * @param target The instance of the class to be wrapped.
+     * @param pluginName Name of the plugin for function collection and prompt templates. If the value is {@code null}, a plugin name is derived from the type of the target.
+     * @return The new plugin.
+     */
     public static KernelPlugin createFromObject(Object target, String pluginName) {
         List<KernelFunction<?>> methods = Arrays.stream(target.getClass().getMethods())
             .filter(method -> method.isAnnotationPresent(DefineKernelFunction.class))
@@ -110,27 +113,25 @@ public class KernelPluginFactory {
         return returnType;
     }
 
-    /// <summary>Initializes the new plugin from the provided name and function collection.</summary>
-    /// <param name="pluginName">The name for the plugin.</param>
-    /// <param name="functions">The initial functions to be available as part of the plugin.</param>
-    /// <exception cref="ArgumentException"><paramref name="pluginName"/> is null.</exception>
-    /// <exception cref="ArgumentException"><paramref name="pluginName"/> is an invalid plugin name.</exception>
-    /// <exception cref="ArgumentNullException"><paramref name="functions"/> contains a null function.</exception>
-    /// <exception cref="ArgumentException"><paramref name="functions"/> contains two functions with the same name.</exception>
+    /**
+     * Creates a plugin from the provided name and function collection.
+     * @param pluginName The name for the plugin.
+     * @param functions The initial functions to be available as part of the plugin.
+     * @return The new plugin.
+     */
     public static KernelPlugin createFromFunctions(
         String pluginName,
         @Nullable List<KernelFunction<?>> functions) {
         return createFromFunctions(pluginName, null, functions);
     }
 
-    /// <summary>Initializes the new plugin from the provided name, description, and function collection.</summary>
-    /// <param name="pluginName">The name for the plugin.</param>
-    /// <param name="description">A description of the plugin.</param>
-    /// <param name="functions">The initial functions to be available as part of the plugin.</param>
-    /// <exception cref="ArgumentException"><paramref name="pluginName"/> is null.</exception>
-    /// <exception cref="ArgumentException"><paramref name="pluginName"/> is an invalid plugin name.</exception>
-    /// <exception cref="ArgumentNullException"><paramref name="functions"/> contains a null function.</exception>
-    /// <exception cref="ArgumentException"><paramref name="functions"/> contains two functions with the same name.</exception>
+    /**
+     * Initializes the new plugin from the provided name, description, and function collection.
+     * @param pluginName The name for the plugin.
+     * @param description A description of the plugin.
+     * @param functions The initial functions to be available as part of the plugin.
+     * @return The new plugin.
+     */
     public static KernelPlugin createFromFunctions(String pluginName, @Nullable String description,
         @Nullable List<KernelFunction<?>> functions) {
         Map<String, KernelFunction<?>> funcs = new HashMap<>();
@@ -157,7 +158,15 @@ public class KernelPluginFactory {
             }).collect(Collectors.toList());
     }
 
-
+    /**
+     * Imports a plugin from a directory. The directory should contain subdirectories, each of which
+     * contains a prompt template and a configuration file. The configuration file should be named
+     * "config.json" and the prompt template should be named "skprompt.txt".
+     * @param parentDirectory The parent directory containing the plugin directories.
+     * @param pluginDirectoryName The name of the plugin directory.
+     * @param promptTemplateFactory The factory to use for creating prompt templates.
+     * @return The imported plugin.
+     */
     public static KernelPlugin importPluginFromDirectory(Path parentDirectory,
         String pluginDirectoryName, PromptTemplateFactory promptTemplateFactory) {
 
@@ -252,6 +261,18 @@ public class KernelPluginFactory {
             .build();
     }
 
+    /**
+     * Imports a plugin from a resource directory, which may be on the classpath or filesystem. 
+     * The directory should contain subdirectories, each of which
+     * contains a prompt template and a configuration file. The configuration file should be named
+     * "config.json" and the prompt template should be named "skprompt.txt".
+     * @param parentDirectory The parent directory containing the plugin directories.
+     * @param pluginDirectoryName The name of the plugin directory.
+     * @param functionName The name of the function to import.
+     * @param promptTemplateFactory The factory to use for creating prompt templates.
+     * @param clazz The class to use for loading resources.
+     * @return The imported plugin.
+     */
     @Nullable
     public static KernelPlugin importPluginFromResourcesDirectory(
         String parentDirectory,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/KernelReturnParameterMetadata.java

@@ -2,12 +2,23 @@ package com.microsoft.semantickernel.plugin;
 
 import javax.annotation.Nullable;
 
+/**
+ * Metadata for a return parameter of a {@link com.microsoft.semantickernel.orchestration.KernelFunction}.
+ *
+ * @param <T> the type of the return parameter
+ */
 public class KernelReturnParameterMetadata<T> {
 
     @Nullable
     private final String description;
     private final Class<T> parameterType;
 
+    /**
+     * Creates a new instance of {@link KernelReturnParameterMetadata}.
+     *
+     * @param description the description of the return parameter
+     * @param parameterType the type of the return parameter
+     */
     public KernelReturnParameterMetadata(
         @Nullable
         String description,
@@ -16,11 +27,21 @@ public class KernelReturnParameterMetadata<T> {
         this.parameterType = parameterType;
     }
 
+    /**
+     * Gets the description of the return parameter.
+     *
+     * @return the description of the return parameter
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
+    /**
+     * Gets the type of the return parameter.
+     *
+     * @return the type of the return parameter
+     */
     public Class<T> getParameterType() {
         return parameterType;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/Plugin.java

@@ -2,31 +2,57 @@
 package com.microsoft.semantickernel.plugin;
 
 import com.microsoft.semantickernel.orchestration.KernelFunction;
+
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * A plugin contains one or more {@link KernelFunction}s.
+ */
 public class Plugin {
 
     private final String name;
-    private final List<KernelFunction> functions;
+    private final List<KernelFunction<?>> functions;
 
-    public Plugin(String name, KernelFunction... functions) {
+    /**
+     * Creates a new instance of {@link Plugin}.
+     *
+     * @param name the name of the plugin
+     * @param functions the functions of the plugin
+     */
+    public Plugin(String name, KernelFunction<?>... functions) {
         this.name = name;
         this.functions = functions != null ? Collections.unmodifiableList(Arrays.asList(functions))
             : Collections.emptyList();
     }
 
-    public Plugin(String name, List<KernelFunction> functions) {
+    /**
+     * Creates a new instance of {@link Plugin}.
+     *
+     * @param name the name of the plugin
+     * @param functions the functions of the plugin
+     */
+    public Plugin(String name, List<KernelFunction<?>> functions) {
         this(name,
             functions != null ? functions.toArray(new KernelFunction[0]) : new KernelFunction[0]);
     }
 
+    /**
+     * Gets the name of the plugin.
+     *
+     * @return the name of the plugin
+     */
     public String name() {
         return name;
     }
 
-    public List<KernelFunction> functions() {
+    /**
+     * Gets the functions of the plugin.
+     *
+     * @return the functions of the plugin
+     */
+    public List<KernelFunction<?>> functions() {
         return Collections.unmodifiableList(functions);
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/annotations/DefineKernelFunction.java

@@ -10,13 +10,41 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface DefineKernelFunction {
+
+    /**
+     * The description of what the function does. The description should 
+     * be short and concise. The model uses the description to
+     * determine whether the function is a good match for use to 
+     * complete a prompt. If the model is not selecting a function
+     * when it should be, consider adding more detail to the description.
+     * @return the description of the function, or an empty string if no description is provided. 
+     */
     String description() default "";
 
+    /**
+     * The name of the function. 
+     * @return the name of the function, or an empty string if no name is provided.
+     */
     String name() default "";
 
+    /**
+     * The fully qualified class name of the return value of the function, for example, "java.lang.String".
+     * If this parameter is not provided, the model will attempt to infer the return type from the method signature.
+     * @return the fully qualified class name of the return value of the function
+     */
     String returnType() default "";
 
+    /**
+     * The description of the return value of the function. The description should be short and concise. 
+     * @return the description of the return value of the function, or an empty string if no description is provided.
+     */
     String returnDescription() default "";
 
+    /**
+     * Examples of how to use the function. The examples should be short and concise. The Semantic Kernel
+     * can use the examples to help the model understand how the function is used.
+     * @return Examples of how to use the function, or an empty array if no examples are provided.
+     */
+
     SKSample[] samples() default {};
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/annotations/KernelFunctionParameter.java

@@ -11,19 +11,44 @@ import java.lang.annotation.Target;
 @Target(ElementType.PARAMETER)
 public @interface KernelFunctionParameter {
 
+    /**
+     *  A special value that is used to indicate that no default value is provided.
+     */
     String NO_DEFAULT_VALUE = "SKFunctionParameters__NO_INPUT_PROVIDED";
 
+    /**
+     * The description of the parameter. The description should be short and concise. 
+     * The model uses the description to determine what value to pass to the function.
+     * 
+     * @return the description of the parameter, or an empty string if no description is provided.
+     */
     String description() default "";
 
+    /**
+     * The name of the parameter. This element is required. 
+     * @return the name of the parameter, or an empty string if no name is provided.
+     */
     String name();
 
+    /**
+     * The default value of the parameter. If no value is set, {@code null} will be passed as the value to this argument.
+     * @return the default value of the parameter, or {@link NO_DEFAULT_VALUE} if no default value is provided.
+     */
     String defaultValue() default NO_DEFAULT_VALUE;
 
     /**
-     * If required is false, no value is set, and no default value is provided, null will be passed
-     * as this argument.
+     * Whether a value is required for this argument. If required is false, the model is free to choose 
+     * whether or not to provide a value. If the model does not provide a value, the default value is used.
+     * @return whether a value is required for this argument.
      */
     boolean required() default true;
 
+    /**
+     * The type of the parameter. The Semantic Kernel will use the type to find a 
+     * {@link com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableType}
+     * to convert the value from a prompt string to the correct argument type. The type defaults to
+     * {@link String} if not provided.
+     * @return the type of the parameter
+     */
     Class<?> type() default String.class;
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/plugin/annotations/SKSample.java

@@ -7,12 +7,39 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * @since 1.0.0
+ * Annotation that decorates an {@link DefineKernelFunction} annotation to provide examples of how to use the function.
+ * For example:
+ * <pre><code>
+ * {@literal @}DefineSKFunction(
+ *    name = "add",
+ *    description = "Adds two numbers together",
+ *    returnType = "java.lang.Integer",
+ *    returnDescription = "The sum of the two numbers",
+ *    samples = {
+ *        {@literal @}SKSample(inputs = "{\"number1\":1, \"number2\":2", output = "3")
+ *     }
+ *  )
+ * public static double add(
+ *       {@literal @}SKFunctionParameters(description="The first number to add", name="number1") double number1,
+ *       {@literal @}SKFunctionParameters(description="The second number to add", name="number2") double number2
+ *   )
+ *   {
+ *       return number1 + number2;
+ *   }
+ * </code></pre>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface SKSample {
+    /**
+     * An example of inputs to the function.
+     * @return An example of inputs to the function.
+     */
     String inputs();
 
+    /**
+     * An example output of the function given the inputs.
+     * @return An example output of the function given the inputs.
+     */
     String output();
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/AggregatorPromptTemplateFactory.java

@@ -2,12 +2,23 @@ package com.microsoft.semantickernel.semanticfunctions;
 
 import java.util.ArrayList;
 import java.util.List;
+
 import reactor.util.annotation.NonNull;
 
+/**
+ * An collection of {@link PromptTemplateFactory} instances. The 
+ * factory will try to create a {@link PromptTemplate} using each
+ * factory in the collection until one is successful.
+ */
 public class AggregatorPromptTemplateFactory implements PromptTemplateFactory {
 
     private final List<PromptTemplateFactory> templateFactories;
 
+    /**
+     * Creates a new instance of {@link AggregatorPromptTemplateFactory}.
+     *
+     * @param templateFactories the factories to aggregate
+     */
     public AggregatorPromptTemplateFactory(List<PromptTemplateFactory> templateFactories) {
         this.templateFactories = new ArrayList<>(templateFactories);
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/HandlebarsPromptTemplateFactory.java

@@ -1,11 +1,20 @@
 package com.microsoft.semantickernel.semanticfunctions;
 
 import com.microsoft.semantickernel.templateengine.handlebars.HandlebarsPromptTemplate;
+
 import java.util.Locale;
+
 import reactor.util.annotation.NonNull;
 
+/**
+ * A factory for creating a {@link HandlebarsPromptTemplate} instance for 
+ * a {@code PromptTemplateConfig} that uses the handlebars template format.
+ */
 public class HandlebarsPromptTemplateFactory implements PromptTemplateFactory {
 
+    /**
+     * The handlebars template format.
+     */
     public static final String HANDLEBARS_TEMPLATE_FORMAT = "handlebars";
 
     @Override

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/InputVariable.java

@@ -3,8 +3,12 @@ package com.microsoft.semantickernel.semanticfunctions;
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.microsoft.semantickernel.exceptions.SKException;
+
 import javax.annotation.Nullable;
 
+/**
+ * Metadata for an input variable of a {@link com.microsoft.semantickernel.orchestration.KernelFunction}.
+ */
 public class InputVariable {
 
     private String name;
@@ -15,6 +19,11 @@ public class InputVariable {
     private String defaultValue;
     private boolean isRequired;
 
+    /**
+     * Creates a new instance of {@link InputVariable}.
+     *
+     * @param name the name of the input variable
+     */
     public InputVariable(String name) {
         this.name = name;
         this.type = String.class.getName();
@@ -23,6 +32,15 @@ public class InputVariable {
         this.isRequired = true;
     }
 
+    /**
+     * Creates a new instance of {@link InputVariable}.
+     *
+     * @param name the name of the input variable
+     * @param type the type of the input variable
+     * @param description the description of the input variable
+     * @param defaultValue the default value of the input variable
+     * @param isRequired whether the input variable is required
+     */
     @JsonCreator
     public InputVariable(
         @JsonProperty("name")
@@ -48,55 +66,58 @@ public class InputVariable {
         this.isRequired = isRequired;
     }
 
+    /**
+     * Gets the name of the input variable.
+     * @return the name of the input variable
+     */
     public String getName() {
         return name;
     }
 
-    public void setName(String name) {
-        this.name = name;
-    }
-
+    /**
+     * Gets the type of the input variable.
+     * @return the type of the input variable
+     */
     public String getType() {
         return type;
     }
 
-    public void setType(String type) {
-        this.type = type;
-    }
-
+    /**
+     * Gets the description of the input variable.
+     * @return the description of the input variable
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
-    public void setDescription(String description) {
-        this.description = description;
-    }
-
+    /**
+     * Gets the default value of the input variable.
+     * @return the default value of the input variable
+     */
     @Nullable
     public String getDefaultValue() {
         return defaultValue;
     }
-
-    public void setDefaultValue(String defaultValue) {
-        this.defaultValue = defaultValue;
-    }
-
+    /**
+     * Gets whether the input variable is required.
+     * @return whether the input variable is required
+     */
     public boolean isRequired() {
         return isRequired;
     }
 
-    public void setRequired(boolean required) {
-        isRequired = required;
-    }
-
+    /**
+     * Gets the class of the type of the input variable.
+     * @return the class of the type of the input variable
+     */
     public Class<?> getTypeClass() {
         try {
             return Thread.currentThread().getContextClassLoader().loadClass(type);
         } catch (ClassNotFoundException e) {
             throw new SKException(
-                "Could not load class for type: " + type + " when for input variable " + name +
-                    ", note this needs to be a fully qualified class name, i.e 'java.lang.String'.");
+                "Could not load class for type: " + type + " for input variable " + name +
+                    ". This needs to be a fully qualified class name, e.g. 'java.lang.String'.");
         }
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromMethod.java

@@ -1,5 +1,27 @@
 package com.microsoft.semantickernel.semanticfunctions;
 
+import com.microsoft.semantickernel.Kernel;
+import com.microsoft.semantickernel.exceptions.AIException;
+import com.microsoft.semantickernel.exceptions.AIException.ErrorCodes;
+import com.microsoft.semantickernel.exceptions.SKException;
+import com.microsoft.semantickernel.hooks.FunctionInvokedEvent;
+import com.microsoft.semantickernel.hooks.FunctionInvokingEvent;
+import com.microsoft.semantickernel.hooks.KernelHooks;
+import com.microsoft.semantickernel.orchestration.FunctionResult;
+import com.microsoft.semantickernel.orchestration.InvocationContext;
+import com.microsoft.semantickernel.orchestration.KernelFunction;
+import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
+import com.microsoft.semantickernel.orchestration.KernelFunctionMetadata;
+import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
+import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableType;
+import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
+import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter.NoopConverter;
+import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
+import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
+import com.microsoft.semantickernel.plugin.annotations.DefineKernelFunction;
+import com.microsoft.semantickernel.plugin.annotations.KernelFunctionParameter;
+import static com.microsoft.semantickernel.plugin.annotations.KernelFunctionParameter.NO_DEFAULT_VALUE;
+
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.lang.reflect.Parameter;
@@ -15,32 +37,16 @@ import javax.annotation.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.microsoft.semantickernel.Kernel;
-import com.microsoft.semantickernel.exceptions.AIException;
-import com.microsoft.semantickernel.exceptions.AIException.ErrorCodes;
-import com.microsoft.semantickernel.exceptions.SKException;
-import com.microsoft.semantickernel.hooks.FunctionInvokedEvent;
-import com.microsoft.semantickernel.hooks.FunctionInvokingEvent;
-import com.microsoft.semantickernel.hooks.KernelHooks;
-import com.microsoft.semantickernel.orchestration.FunctionResult;
-import com.microsoft.semantickernel.orchestration.InvocationContext;
-import com.microsoft.semantickernel.orchestration.KernelFunction;
-import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
-import com.microsoft.semantickernel.orchestration.KernelFunctionMetadata;
-import com.microsoft.semantickernel.orchestration.MethodDetails;
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariable;
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableType;
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter;
-import com.microsoft.semantickernel.orchestration.contextvariables.ContextVariableTypeConverter.NoopConverter;
-import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
-import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
-import com.microsoft.semantickernel.plugin.annotations.DefineKernelFunction;
-import com.microsoft.semantickernel.plugin.annotations.KernelFunctionParameter;
-import static com.microsoft.semantickernel.plugin.annotations.KernelFunctionParameter.NO_DEFAULT_VALUE;
-
 import reactor.core.publisher.Mono;
 import reactor.core.scheduler.Schedulers;
 
+/**
+ * A {@link KernelFunction} that is created from a method. This class is used to create a
+ * {@link KernelFunction} from a method that is annotated with {@link DefineKernelFunction}
+ * and {@link KernelFunctionParameter}.
+ *
+ * @param <T> the return type of the function
+ */
 public class KernelFunctionFromMethod<T> extends KernelFunction<T> {
 
     private final static Logger LOGGER = LoggerFactory.getLogger(KernelFunctionFromMethod.class);
@@ -79,7 +85,21 @@ public class KernelFunctionFromMethod<T> extends KernelFunction<T> {
         return function.invoke(kernel, this, arguments, variableType, invocationContext);
     }
 
+    /**
+     * Concrete implementation of the abstract method in KernelFunction. {@inheritDoc}
+     */
     public interface ImplementationFunc<T> {
+
+        /**
+         * Invokes the function.
+         *
+         * @param kernel the kernel to invoke the function on
+         * @param function the function to invoke
+         * @param arguments the arguments to the function
+         * @param variableType the variable type of the function
+         * @param invocationContext the invocation context
+         * @return a {@link Mono} that emits the result of the function invocation
+         */
         Mono<FunctionResult<T>> invoke(
             Kernel kernel,
             KernelFunction<T> function,
@@ -89,6 +109,18 @@ public class KernelFunctionFromMethod<T> extends KernelFunction<T> {
     }
 
 
+    /**
+     * Creates a new instance of {@link KernelFunctionFromMethod} from a method.
+     *
+     * @param method the method to create the function from
+     * @param target the instance of the class that the method is a member of
+     * @param functionName the name of the function
+     * @param description the description of the function
+     * @param parameters the parameters of the function
+     * @param returnParameter the return parameter of the function
+     * @param <T> the return type of the function
+     * @return a new instance of {@link KernelFunctionFromMethod}
+     */
     @SuppressWarnings("unchecked")
     public static <T> KernelFunction<T> create(
         Method method,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelFunctionFromPrompt.java

@@ -42,19 +42,31 @@ import org.slf4j.LoggerFactory;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
+/**
+ * A {@link KernelFunction} implementation that is created from a prompt template.
+ *
+ * @param <T> the type of the return value of the function
+ */
 public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(KernelFunctionFromPrompt.class);
 
     private final PromptTemplate template;
 
+    /**
+     * Creates a new instance of {@link KernelFunctionFromPrompt}.
+     *
+     * @param template the prompt template to use for the function
+     * @param promptConfig the configuration for the prompt
+     * @param executionSettings the execution settings to use when invoking the function
+     */
     public KernelFunctionFromPrompt(
         PromptTemplate template,
         PromptTemplateConfig promptConfig,
         @Nullable
         Map<String, PromptExecutionSettings> executionSettings) {
         super(
-            new KernelFunctionMetadata(
+            new KernelFunctionMetadata<>(
                 getName(promptConfig),
                 promptConfig.getDescription(),
                 promptConfig.getKernelParametersMetadata(),
@@ -73,20 +85,37 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
         }
     }
 
+    /**
+     * Creates a new instance of {@link KernelFunctionFromPrompt} from a 
+     * {@code PromptTemplateConfig}.
+     *
+     * @param promptConfig the configuration for the prompt
+     * @param <T> the type of the return value of the function
+     * @return a new instance of {@link KernelFunction}
+     */
     public static <T> KernelFunction<T> create(
-        PromptTemplateConfig promptConfig
-    ) {
+        PromptTemplateConfig promptConfig) {
         return create(
             promptConfig,
             null
         );
     }
 
+    /**
+     * Creates a new instance of {@link KernelFunctionFromPrompt} from a
+     * {@code PromptTemplateConfig}, using the {@code PropmptTemplateFactory}
+     * to create the prompt template. If {@code promptTemplateFactory} is {@code null},
+     * a default factory will be used.
+     *
+     * @param promptConfig the configuration for the prompt
+     * @param promptTemplateFactory the prompt template factory to use for creating the prompt template
+     * @param <T> the type of the return value of the function
+     * @return a new instance of {@link KernelFunction}
+     */
     public static <T> KernelFunction<T> create(
         PromptTemplateConfig promptConfig,
         @Nullable
-        PromptTemplateFactory promptTemplateFactory
-    ) {
+        PromptTemplateFactory promptTemplateFactory) {
         if (promptTemplateFactory == null) {
             promptTemplateFactory = new KernelPromptTemplateFactory();
         }
@@ -94,7 +123,15 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
         return create(promptTemplateFactory.tryCreate(promptConfig), promptConfig);
     }
 
-
+    /**
+     * Creates a new instance of {@link KernelFunctionFromPrompt} from a
+     * {@code PromptTemplateConfig}, using the provided prompt template.
+     *
+     * @param promptTemplate the prompt template to use for the function
+     * @param promptConfig the configuration for the prompt
+     * @param <T> the type of the return value of the function
+     * @return a new instance of {@link KernelFunction}
+     */
     public static <T> KernelFunction<T> create(
         PromptTemplate promptTemplate,
         PromptTemplateConfig promptConfig) {
@@ -391,22 +428,29 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
         return Mono.empty();
     }
 
+    /**
+     * Creates a {@link KernelFunction} instance for a prompt specified via a prompt template.
+     * @param <T> the type of the return value of the function
+     * @param promptTemplate the prompt template for the function
+     * @return a new instance of {@link KernelFunction}
+     */
     public static <T> KernelFunction<T> create(
         String promptTemplate) {
         return create(promptTemplate, null, null, null, null, null);
     }
 
-    /// <summary>
-    /// Creates a <see cref="KernelFunction"/> instance for a prompt specified via a prompt template.
-    /// </summary>
-    /// <param name="promptTemplate">Prompt template for the function, defined using the <see cref="PromptTemplateConfig.SemanticKernelTemplateFormat"/> template format.</param>
-    /// <param name="executionSettings">Default execution settings to use when invoking this prompt function.</param>
-    /// <param name="functionName">A name for the given function. The name can be referenced in templates and used by the pipeline planner.</param>
-    /// <param name="description">The description to use for the function.</param>
-    /// <param name="templateFormat">Optional format of the template. Must be provided if a prompt template factory is provided</param>
-    /// <param name="promptTemplateFactory">Optional: Prompt template factory</param>
-    /// <param name="loggerFactory">Logger factory</param>
-    /// <returns>A function ready to use</returns>
+    /**
+     * Creates a {@link KernelFunction} instance for a prompt specified via a prompt template.
+     * If any of the optional parameters are {@code null}, default values will be used.
+     * @param promptTemplate the prompt template for the function
+     * @param executionSettings the default execution settings to use when invoking this prompt function
+     * @param functionName the name of the function
+     * @param description the description of the function
+     * @param templateFormat the format of the template
+     * @param promptTemplateFactory the prompt template factory to use for creating the prompt template
+     * @param <T> the type of the return value of the function
+     * @return a new instance of {@link KernelFunction}
+     */
     @SuppressWarnings("unchecked")
     public static <T> KernelFunction<T> create(
         String promptTemplate,
@@ -434,10 +478,19 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
             .build();
     }
 
+    /**
+     * Creates a new instance of {@link Builder}.
+     * @param <T> The type of the return value of the function
+     * @return a new instance of {@link Builder}
+     */
     public static <T> Builder<T> builder() {
         return new Builder<>();
     }
 
+    /**
+     * A builder for creating a {@link KernelFunction} from a prompt template.
+     * @param <T> the type of the return value of the function
+     */
     public static final class Builder<T> implements FromPromptBuilder<T> {
 
         @Nullable
@@ -457,6 +510,8 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
         private OutputVariable outputVariable;
         @Nullable
         private PromptTemplateFactory promptTemplateFactory;
+        @Nullable
+        private PromptTemplateConfig functionModel;
 
 
         @Override
@@ -554,9 +609,27 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
             return this;
         }
 
+        @Override
+        public FromPromptBuilder<T> withPromptTemplateConfig(
+            @Nullable
+            PromptTemplateConfig functionModel) {
+            this.functionModel = functionModel;
+            return this;
+        }
+
         @Override
         public KernelFunction<T> build() {
 
+            if (functionModel != null) {
+                if (promptTemplate == null) {
+                    throw new IllegalStateException("A PromptTemplate must be provided when building with a PromptTemplateConfig");
+                }
+                return new KernelFunctionFromPrompt<>(
+                    promptTemplate, 
+                    functionModel, 
+                    executionSettings);
+            }
+
             if (template == null) {
                 throw new IllegalStateException("Template must be provided");
             }
@@ -584,17 +657,5 @@ public class KernelFunctionFromPrompt<T> extends KernelFunction<T> {
 
         }
 
-        public KernelFunction<T> build(PromptTemplateConfig functionModel) {
-
-            if (promptTemplate == null) {
-                throw new IllegalStateException("Template must be provided");
-            }
-
-            return new KernelFunctionFromPrompt<>(
-                promptTemplate,
-                functionModel,
-                executionSettings
-            );
-        }
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/KernelPromptTemplateFactory.java

@@ -2,12 +2,17 @@ package com.microsoft.semantickernel.semanticfunctions;
 
 import static com.microsoft.semantickernel.semanticfunctions.HandlebarsPromptTemplateFactory.HANDLEBARS_TEMPLATE_FORMAT;
 import static com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig.SEMANTIC_KERNEL_TEMPLATE_FORMAT;
-
 import com.microsoft.semantickernel.templateengine.handlebars.HandlebarsPromptTemplate;
 import com.microsoft.semantickernel.templateengine.semantickernel.DefaultPromptTemplate;
+
 import java.util.Locale;
+
 import javax.annotation.Nonnull;
 
+/**
+ * Factory for creating prompt templates. This factory creates the appropriate 
+ * prompt template based on the template format.
+ */
 public class KernelPromptTemplateFactory implements PromptTemplateFactory {
 
     @Override

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/MethodDetails.java

@@ -1,4 +1,8 @@
-package com.microsoft.semantickernel.orchestration;
+package com.microsoft.semantickernel.semanticfunctions;
+
+import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
+import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
+import com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromMethod.ImplementationFunc;
 
 import java.util.ArrayList;
 import java.util.Collections;
@@ -6,24 +10,32 @@ import java.util.List;
 
 import javax.annotation.Nullable;
 
-import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
-import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
-import com.microsoft.semantickernel.semanticfunctions.KernelFunctionFromMethod.ImplementationFunc;
-
+/**
+ * Metadata for a method that can be used as a kernel function.
+ */
 public class MethodDetails {
 
     private final String name;
     @Nullable
     private final String description;
-    private final ImplementationFunc function;
+    private final ImplementationFunc<?> function;
     private final List<KernelParameterMetadata<?>> parameters;
     private final KernelReturnParameterMetadata<?> returnParameter;
 
+    /**
+     * Constructor.
+     *
+     * @param name            The name of the method.
+     * @param description     The description of the method.
+     * @param function        The function that implements the method.
+     * @param parameters      The parameters of the method.
+     * @param returnParameter The return parameter of the method.
+     */
     public MethodDetails(
         String name,
         @Nullable
         String description,
-        ImplementationFunc function,
+        ImplementationFunc<?> function,
         List<KernelParameterMetadata<?>> parameters,
         KernelReturnParameterMetadata<?> returnParameter) {
         this.name = name;
@@ -33,23 +45,43 @@ public class MethodDetails {
         this.returnParameter = returnParameter;
     }
 
+    /**
+     * Get the name of the method.
+     * @return The name of the method.
+     */
     public String getName() {
         return name;
     }
 
+    /**
+     * Get the description of the method.
+     * @return The description of the method.
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
-    public ImplementationFunc getFunction() {
+    /**
+     * Get the function that implements the method. This is an internal detail.
+     * @return The function that implements the method.
+     */
+    public ImplementationFunc<?> getFunction() {
         return function;
     }
 
+    /**
+     * Get the parameters of the method.
+     * @return The parameters of the method.
+     */
     public List<KernelParameterMetadata<?>> getParameters() {
         return Collections.unmodifiableList(parameters);
     }
 
+    /**
+     * Get the return parameter of the method.
+     * @return The return parameter of the method.
+     */
     public KernelReturnParameterMetadata<?> getReturnParameter() {
         return returnParameter;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/OutputVariable.java

@@ -3,8 +3,12 @@ package com.microsoft.semantickernel.semanticfunctions;
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.microsoft.semantickernel.exceptions.SKException;
+
 import javax.annotation.Nullable;
 
+/**
+ * Metadata for an output variable of a kernel function.
+ */
 public class OutputVariable {
 
     @Nullable
@@ -12,6 +16,12 @@ public class OutputVariable {
 
     private final String type;
 
+    /**
+     * Constructor.
+     *
+     * @param description The description of the output variable.
+     * @param type        The type of the output variable.
+     */
     @JsonCreator
     public OutputVariable(
         @Nullable
@@ -24,17 +34,25 @@ public class OutputVariable {
         this.type = type;
     }
 
+    /**
+     * Get the description of the output variable.
+     * @return The description of the output variable.
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
+    /**
+     * Get the type of the output variable.
+     * @return The type of the output variable.
+     */
     public Class<?> getType() {
         try {
             return this.getClass().getClassLoader().loadClass(type);
         } catch (ClassNotFoundException e) {
             throw new SKException("Requested output type could not be found: " + type
-                + ", note this needs to be a fully qualified class name, i.e 'java.lang.String'.");
+                + ". This needs to be a fully qualified class name, e.g. 'java.lang.String'.");
         }
     }
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplate.java

@@ -1,25 +1,28 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.semanticfunctions;
 
+
 import com.microsoft.semantickernel.Kernel;
 import com.microsoft.semantickernel.builders.Buildable;
 import com.microsoft.semantickernel.orchestration.InvocationContext;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
+
 import javax.annotation.Nullable;
+
 import reactor.core.publisher.Mono;
 
 /**
- * Interface for prompt template
+ * Represents a prompt template that can be rendered to a string.
  */
 public interface PromptTemplate extends Buildable {
 
-    /// <summary>
-    /// Render the template using the information in the context
-    /// </summary>
-    /// <param name="kernel">The <see cref="Kernel"/> containing services, plugins, and other state for use throughout the operation.</param>
-    /// <param name="arguments">The arguments.</param>
-    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>Prompt rendered to string</returns>
+    /**
+     *  Renders the template using the supplied {@code Kernel}, {@code KernelFunctionArguments}, and {@code InvocationContext}. 
+     * @param kernel The {@link Kernel} containing services, plugins, and other state for use throughout the operation.
+     * @param arguments The arguments to use to satisfy any input variables in the prompt template.
+     * @param context The {@link InvocationContext} which carries optional information for the prompt rendering.
+     * @return The rendered prompt.
+     */
     Mono<String> renderAsync(
         Kernel kernel,
         @Nullable KernelFunctionArguments arguments,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateConfig.java

@@ -10,19 +10,37 @@ import com.microsoft.semantickernel.exceptions.SKException;
 import com.microsoft.semantickernel.orchestration.PromptExecutionSettings;
 import com.microsoft.semantickernel.plugin.KernelParameterMetadata;
 import com.microsoft.semantickernel.plugin.KernelReturnParameterMetadata;
+
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
+
 import javax.annotation.Nullable;
 
+/**
+ * Metadata for a prompt template.
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public class PromptTemplateConfig {
 
+    /**
+     * The current prompt template config schema version.
+     */
     public static final int CURRENT_SCHEMA = 1;
+
+    /**
+     * The default name for a prompt template config.
+     */
     public static final String DEFAULT_CONFIG_NAME = "default";
+
+    /**
+     * The default template format for a prompt template config.
+     */
+    public static final String SEMANTIC_KERNEL_TEMPLATE_FORMAT = "semantic-kernel";
+
     @Nullable
     private String name;
     private String template;
@@ -34,8 +52,11 @@ public class PromptTemplateConfig {
     private OutputVariable outputVariable;
     private Map<String, PromptExecutionSettings> executionSettings;
 
-    public static final String SEMANTIC_KERNEL_TEMPLATE_FORMAT = "semantic-kernel";
-
+    /**
+     * Constructor for a prompt template config
+     *
+     * @param template Template string
+     */
     public PromptTemplateConfig(String template) {
         this(
             CURRENT_SCHEMA,
@@ -49,6 +70,18 @@ public class PromptTemplateConfig {
         );
     }
 
+    /**
+     * Constructor for a prompt template config
+     *
+     * @param schema           Schema version
+     * @param name             Name of the template
+     * @param template         Template string
+     * @param templateFormat   Template format
+     * @param description      Description of the template
+     * @param inputVariables   Input variables
+     * @param outputVariable   Output variable
+     * @param executionSettings Execution settings
+     */
     @JsonCreator
     public PromptTemplateConfig(
         @JsonProperty("schema")
@@ -132,6 +165,11 @@ public class PromptTemplateConfig {
         );
     }
 
+    /**
+     * Copy constructor.
+     *
+     * @param promptTemplate The prompt template to copy.
+     */
     public PromptTemplateConfig(PromptTemplateConfig promptTemplate) {
         this(
             promptTemplate.name,
@@ -144,6 +182,11 @@ public class PromptTemplateConfig {
         );
     }
 
+    /**
+     * Get the parameters metadata.
+     *
+     * @return The parameters metadata.
+     */
     public List<KernelParameterMetadata<?>> getKernelParametersMetadata() {
         if (inputVariables == null) {
             return Collections.emptyList();
@@ -159,6 +202,11 @@ public class PromptTemplateConfig {
             .collect(Collectors.toList());
     }
 
+    /**
+     * Get the return parameter metadata.
+     *
+     * @return The return parameter metadata.
+     */
     public KernelReturnParameterMetadata<?> getKernelReturnParameterMetadata() {
         if (outputVariable == null) {
             return new KernelReturnParameterMetadata<>("", String.class);
@@ -170,62 +218,132 @@ public class PromptTemplateConfig {
         );
     }
 
-    public void addInputVariable(InputVariable inputVariable) {
+    /**
+     * Add an input variable to the prompt template config.
+     *
+     * @param inputVariable The input variable to add.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig addInputVariable(InputVariable inputVariable) {
         inputVariables.add(inputVariable);
+        return this;
     }
 
+    /**
+     * Get the name of the prompt template config.
+     * @return The name of the prompt template config.
+     */
     @Nullable
     public String getName() {
         return name;
     }
 
+    /**
+     * Set the name of the prompt template config.
+     * @param name The name of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
     public PromptTemplateConfig setName(String name) {
         this.name = name;
         return this;
     }
 
+    /**
+     * Get the template of the prompt template config.
+     * @return The template of the prompt template config.
+     */
     public String getTemplate() {
         return template;
     }
 
-    public void setTemplate(String template) {
+    /**
+     * Set the template of the prompt template config.
+     * @param template The template of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig setTemplate(String template) {
         this.template = template;
+        return this;
     }
 
+    /**
+     * Get the template format of the prompt template config.
+     * @return The template format of the prompt template config.
+     */
     public String getTemplateFormat() {
         return templateFormat;
     }
 
-    public void setTemplateFormat(String templateFormat) {
+    /**
+     * Set the template format of the prompt template config.
+     * @param templateFormat The template format of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig setTemplateFormat(String templateFormat) {
         this.templateFormat = templateFormat;
+        return this;
     }
 
+    /**
+     * Get the description of the prompt template config.
+     * @return The description of the prompt template config.
+     */
     @Nullable
     public String getDescription() {
         return description;
     }
 
-    public void setDescription(String description) {
+    /**
+     * Set the description of the prompt template config.
+     * @param description The description of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig setDescription(String description) {
         this.description = description;
+        return this;
     }
 
+    /**
+     * Get the inputVariables of the prompt template config.
+     * @return The input variables of the prompt template config.
+     */
     public List<InputVariable> getInputVariables() {
         return Collections.unmodifiableList(inputVariables);
     }
 
-    public void setInputVariables(List<InputVariable> inputVariables) {
+    /**
+     * Set the inputVariables of the prompt template config.
+     * @param inputVariables The input variables of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig setInputVariables(List<InputVariable> inputVariables) {
         this.inputVariables = new ArrayList<>(inputVariables);
+        return this;
     }
 
+    /**
+     * Get the output variable of the prompt template config.
+     * @return The output variable of the prompt template config.
+     */
     @Nullable
     public OutputVariable getOutputVariable() {
         return outputVariable;
     }
 
-    public void setOutputVariable(OutputVariable outputVariable) {
+    /**
+     * Set the output variable of the prompt template config.
+     * @param outputVariable The output variable of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig setOutputVariable(OutputVariable outputVariable) {
         this.outputVariable = outputVariable;
+        return this;
     }
 
+    /**
+     * Get the prompt execution settings of the prompt template config.
+     * @return The prompt execution settings of the prompt template config.
+     */
     @Nullable
     public Map<String, PromptExecutionSettings> getExecutionSettings() {
         if (executionSettings != null) {
@@ -235,10 +353,22 @@ public class PromptTemplateConfig {
     }
 
 
-    public void setExecutionSettings(Map<String, PromptExecutionSettings> executionSettings) {
+    /**
+     * Set the prompt execution settings of the prompt template config.
+     * @param executionSettings The prompt execution settings of the prompt template config.
+     * @return {@code this} prompt template config.
+     */
+    public PromptTemplateConfig setExecutionSettings(Map<String, PromptExecutionSettings> executionSettings) {
         this.executionSettings = new HashMap<>(executionSettings);
+        return this;
     }
 
+    /**
+     * Deserialize the JSON string to a PromptTemplateConfig.
+     * @param json The JSON string to parse
+     * @return The PromptTemplateConfig object
+     * @throws SKException If the prompt template config cannot be deserialized.
+     */
     public static PromptTemplateConfig parseFromJson(String json) throws SKException {
         try {
             return new ObjectMapper().readValue(json, PromptTemplateConfig.class);

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/semanticfunctions/PromptTemplateFactory.java

@@ -2,16 +2,49 @@ package com.microsoft.semantickernel.semanticfunctions;
 
 import javax.annotation.Nullable;
 
+/**
+ * The interface that a {@code PromptTemplateFactory} implementation must provide. 
+ */
 public interface PromptTemplateFactory {
 
+    /**
+     * Create a prompt template, if possible, from the given configuration.
+     * If the {@code PromptTemplateConfig} is not supported, the method should throw an
+     * {@code UnknownTemplateFormatException}.
+     *
+     * @param templateConfig The configuration for the prompt template.
+     * @return The prompt template.
+     * @throws UnknownTemplateFormatException If the template format is not supported.
+     * @see PromptTemplateConfig#getTemplateFormat()
+     */
     PromptTemplate tryCreate(PromptTemplateConfig templateConfig);
 
+    /**
+     * Create a prompt template, if possible, from the given configuration.
+     * This is a convenience method that wraps the 
+     * {@link KernelPromptTemplateFactory#tryCreate(PromptTemplateConfig)} 
+     * method.
+     *
+     * @param templateConfig The configuration for the prompt template.
+     * @return The prompt template.
+     * @throws UnknownTemplateFormatException If the template format is not supported.
+     * @see PromptTemplateConfig#getTemplateFormat()
+     */
     static PromptTemplate build(PromptTemplateConfig templateConfig) {
         return new KernelPromptTemplateFactory().tryCreate(templateConfig);
     }
 
+    /**
+     * Exception thrown when the template format is not supported.
+     * @see PromptTemplateConfig#getTemplateFormat()
+     */
     class UnknownTemplateFormatException extends IllegalArgumentException {
 
+        /**
+         * Constructor.
+         *
+         * @param templateFormat The template format that is not supported.
+         */
         public UnknownTemplateFormatException(@Nullable String templateFormat) {
             super("Unknown template format: " + templateFormat);
         }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/AIServiceSelection.java

@@ -19,7 +19,7 @@ public class AIServiceSelection<T extends AIService> {
      * Creates a new AI service selection.
      *
      * @param service  The selected AI service.
-     * @param settings The settings associated with the selected service. This may be null even if a
+     * @param settings The settings associated with the selected service. This may be {@code null} even if a
      *                 service is selected..
      */
     public AIServiceSelection(T service, @Nullable PromptExecutionSettings settings) {
@@ -39,7 +39,7 @@ public class AIServiceSelection<T extends AIService> {
     /**
      * Gets the settings associated with the selected service.
      *
-     * @return The settings associated with the selected service. This may be null even if a service
+     * @return The settings associated with the selected service. This may be {@code null} even if a service
      * is selected.
      */
     @Nullable

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/AIServiceSelector.java

@@ -16,22 +16,21 @@ public interface AIServiceSelector {
 
     /**
      * Resolves an {@link AIService} and associated and
-     * {@link com.microsoft.semantickernel.orchestration.PromptExecutionSettings} from the specified
-     * {@link com.microsoft.semantickernel.Kernel} based on the associated {@link KernelFunction}
-     * and {@link KernelFunctionArguments}.
+     * {@link com.microsoft.semantickernel.orchestration.PromptExecutionSettings} based on the 
+     * associated {@link KernelFunction} and {@link KernelFunctionArguments}.
      *
      * @param serviceType The type of service to select.  This must be the same type with which the
      *                    service was registered in the {@link AIServiceSelection}
-     * @param function
-     * @param arguments
-     * @return
+     * @param function The KernelFunction to use to select the service, or {@code null}.
+     * @param arguments The KernelFunctionArguments to use to select the service, or {@code null}.
+     * @param <T> The type of service to select.
+     * @return An {@code AIServiceSelection} containing the selected service and associated PromptExecutionSettings.
      */
     @Nullable
     <T extends AIService> AIServiceSelection<T> trySelectAIService(
         Class<T> serviceType,
         @Nullable
         KernelFunction<?> function,
-
         @Nullable
         KernelFunctionArguments arguments
     );

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/BaseAIServiceSelector.java

@@ -5,16 +5,25 @@ import com.microsoft.semantickernel.orchestration.KernelFunction;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
 
 import java.util.Map;
+
 import javax.annotation.Nullable;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
+/**
+ * Base class for {@link AIServiceSelector} implementations which provides a 
+ * {@code Map} based collection from which an {@link AIService} can be selected.
+ * The {@link #trySelectAIService(Class, KernelFunction, KernelFunctionArguments)}
+ * method has been implemented. Child classes must implement the method
+ * {@link #trySelectAIService(Class, KernelFunction, KernelFunctionArguments, Map)}.
+ */
 public abstract class BaseAIServiceSelector implements AIServiceSelector {
 
-    private static final Logger LOGGER = LoggerFactory.getLogger(BaseAIServiceSelector.class);
-
     protected final Map<Class<? extends AIService>, AIService> services;
 
+    /**
+     * Initializes a new instance of the {@link BaseAIServiceSelector} class.
+     *
+     * @param services The services to select from.
+     */
     protected BaseAIServiceSelector(Map<Class<? extends AIService>, AIService> services) {
         this.services = services;
     }
@@ -25,20 +34,29 @@ public abstract class BaseAIServiceSelector implements AIServiceSelector {
         Class<T> serviceType,
         @Nullable
         KernelFunction<?> function,
-
         @Nullable
         KernelFunctionArguments arguments
     ) {
         return trySelectAIService(serviceType, function, arguments, services);
     }
 
+    /**
+     * Resolves an {@link AIService} from the {@code services} argument using
+     * the specified {@code function} and {@code arguments} for selection.
+     *
+     * @param serviceType The type of service to select.  This must be the same type with which the
+     *                    service was registered in the {@link AIServiceSelection}
+     * @param function The KernelFunction to use to select the service, or {@code null}.
+     * @param arguments The KernelFunctionArguments to use to select the service, or {@code null}.
+     * @param services The services to select from.
+     * @param <T> The type of service to select.
+     * @return
+     */
     @Nullable
-    public abstract <T extends AIService> AIServiceSelection<T> trySelectAIService(
+    protected abstract <T extends AIService> AIServiceSelection<T> trySelectAIService(
         Class<T> serviceType,
-
         @Nullable
         KernelFunction<?> function,
-
         @Nullable
         KernelFunctionArguments arguments,
         Map<Class<? extends AIService>, AIService> services);

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/NamedServiceProvider.java

@@ -9,12 +9,12 @@ import javax.annotation.Nullable;
  */
 public interface NamedServiceProvider<T> {
     /**
-     * Gets the service of the specified type and name, or null if not found.
+     * Gets the service of the specified type and name, or {@code null} if not found.
      *
-     * @param name The name of the service, or null for the default service.
+     * @param name The name of the service, or {@code null} for the default service.
      * @param clazz The type of the service.
      * @param <U> The specific type of the service
-     * @return The service instance, or null if not found.
+     * @return The service instance, or {@code null} if not found.
      */
     @Nullable
     public <U extends T> U getService(@Nullable String name, Class<U> clazz);

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/OrderedAIServiceSelector.java

@@ -1,5 +1,13 @@
 package com.microsoft.semantickernel.services;
 
+import com.microsoft.semantickernel.AIService;
+import com.microsoft.semantickernel.Verify;
+import com.microsoft.semantickernel.chatcompletion.ChatCompletionService;
+import com.microsoft.semantickernel.orchestration.KernelFunction;
+import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
+import com.microsoft.semantickernel.orchestration.PromptExecutionSettings;
+import com.microsoft.semantickernel.textcompletion.TextGenerationService;
+
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -11,22 +19,30 @@ import javax.annotation.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import com.microsoft.semantickernel.AIService;
-import com.microsoft.semantickernel.Verify;
-import com.microsoft.semantickernel.chatcompletion.ChatCompletionService;
-import com.microsoft.semantickernel.orchestration.KernelFunction;
-import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
-import com.microsoft.semantickernel.orchestration.PromptExecutionSettings;
-import com.microsoft.semantickernel.textcompletion.TextGenerationService;
-
+/**
+ * Implementation of {@link com.microsoft.semantickernel.services.AIServiceSelector} that 
+ * selects the AI service based on the order of the execution settings.
+ * Uses the service id or model id to select the preferred service provider and then 
+ * returns the service and associated execution settings.
+ */
 public class OrderedAIServiceSelector extends BaseAIServiceSelector {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(OrderedAIServiceSelector.class);
 
+    /**
+     * Initializes a new instance of the {@link OrderedAIServiceSelector} 
+     * class with an empty collection of services.
+     */
     public OrderedAIServiceSelector() {
         super(new HashMap<>());
     }
 
+    /**
+     * Initializes a new instance of the {@link OrderedAIServiceSelector} 
+     * class with the specified services.
+     *
+     * @param services The services to select from.
+     */
     public OrderedAIServiceSelector(Map<Class<? extends AIService>, AIService> services) {
         super(services);
     }
@@ -35,10 +51,8 @@ public class OrderedAIServiceSelector extends BaseAIServiceSelector {
     @Override
     public <T extends AIService> AIServiceSelection<T> trySelectAIService(
         Class<T> serviceType,
-
         @Nullable
         KernelFunction<?> function,
-
         @Nullable
         KernelFunctionArguments arguments,
         Map<Class<? extends AIService>, AIService> services) {
@@ -159,6 +173,13 @@ public class OrderedAIServiceSelector extends BaseAIServiceSelector {
     }
 
 
+    /**
+     * Gets the service with the specified service id.
+     *
+     * @param serviceId The service id.
+     * @return The service with the specified service id, or {@code null} if no such service exists.
+     * @see AIService#getServiceId()
+     */
     @Nullable
     public AIService getService(String serviceId) {
         return services
@@ -169,8 +190,16 @@ public class OrderedAIServiceSelector extends BaseAIServiceSelector {
             .orElseGet(() -> null);
     }
 
+    /**
+     * Gets the service of the specified type.
+     *
+     * @param clazz The type of service to get.
+     * @param <T> The type of service to get.
+     * @return The service of the specified type, or {@code null} if no such service exists.
+     */
     @Nullable
-    public <T> T getService(Class<T> clazz) {
+    @SuppressWarnings("unchecked")
+    public <T extends AIService> T getService(Class<T> clazz) {
         T service = (T) services.get(clazz);
 
         if (service == null) {
@@ -194,13 +223,19 @@ public class OrderedAIServiceSelector extends BaseAIServiceSelector {
         return service;
     }
 
+    /**
+     * Gets the first service of the specified type, or that is an instance of the specified type.
+     *
+     * @param serviceType The type of service to get.
+     * @return The first service of the specified type, or {@code null} if no such service exists.
+     */
     @Nullable
     AIService getAnyService(Class<? extends AIService> serviceType) {
-        List<AIService> services = getServices(serviceType);
-        if (services.isEmpty()) {
+        List<AIService> matchingServices = getServices(serviceType);
+        if (matchingServices.isEmpty()) {
             return null;
         }
-        return services.get(0);
+        return matchingServices.get(0);
     }
 
     private List<AIService> getServices(Class<? extends AIService> serviceType) {

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/services/ServiceNotFoundException.java

@@ -0,0 +1,17 @@
+package com.microsoft.semantickernel.services;
+
+import com.microsoft.semantickernel.exceptions.SKCheckedException;
+
+/**
+ * Exception thrown when a service is not found.
+ */
+public class ServiceNotFoundException extends SKCheckedException {
+
+    /**
+     * Initializes a new instance of the {@link ServiceNotFoundException} class.
+     * @param s A message which describes the service that could not be found.
+     */
+    public ServiceNotFoundException(String s) {
+        super(s);
+    }
+}

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/handlebars/HandlebarsPromptTemplate.java

@@ -31,10 +31,18 @@ import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import reactor.core.publisher.Mono;
 
+/**
+ * A prompt template that uses the Handlebars template engine to render prompts.
+ */
 public class HandlebarsPromptTemplate implements PromptTemplate {
 
     private final PromptTemplateConfig promptTemplate;
 
+    /**
+     * Initializes a new instance of the {@link HandlebarsPromptTemplate} class.
+     *
+     * @param promptTemplate The prompt template configuration.
+     */
     public HandlebarsPromptTemplate(
         @Nonnull PromptTemplateConfig promptTemplate) {
         this.promptTemplate = new PromptTemplateConfig(promptTemplate);
@@ -160,7 +168,7 @@ public class HandlebarsPromptTemplate implements PromptTemplate {
         }
     }
 
-    public static class HandleBarsPromptTemplateHandler {
+    private static class HandleBarsPromptTemplateHandler {
 
         private final String template;
         private final Handlebars handlebars;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/CodeTokenizer.java

@@ -9,36 +9,37 @@ import com.microsoft.semantickernel.templateengine.semantickernel.blocks.NamedAr
 import com.microsoft.semantickernel.templateengine.semantickernel.blocks.Symbols;
 import com.microsoft.semantickernel.templateengine.semantickernel.blocks.ValBlock;
 import com.microsoft.semantickernel.templateengine.semantickernel.blocks.VarBlock;
+
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+
 import javax.annotation.Nullable;
 
-/// <summary>
-/// Simple tokenizer used for default SK template code language.
-///
-/// BNF parsed by TemplateTokenizer:
-/// [template]       ::= "" | [block] | [block] [template]
-/// [block]          ::= [sk-block] | [text-block]
-/// [sk-block]       ::= "{{" [variable] "}}" | "{{" [value] "}}" | "{{" [function-call] "}}"
-/// [text-block]     ::= [any-char] | [any-char] [text-block]
-/// [any-char]       ::= any char
-///
-/// BNF parsed by CodeTokenizer:
-/// [template]       ::= "" | [variable] " " [template] | [value] " " [template] | [function-call] "
-// " [template]
-/// [variable]       ::= "$" [valid-name]
-/// [value]          ::= "'" [text] "'" | '"' [text] '"'
-/// [function-call]  ::= [function-id] | [function-id] [parameter]
-/// [parameter]      ::= [variable] | [value]
-///
-/// BNF parsed by dedicated blocks
-/// [function-id]    ::= [valid-name] | [valid-name] "." [valid-name]
-/// [valid-name]     ::= [valid-symbol] | [valid-symbol] [valid-name]
-/// [valid-symbol]   ::= [letter] | [digit] | "_"
-/// [letter]         ::= "a" | "b" ... | "z" | "A" | "B" ... | "Z"
-/// [digit]          ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
-/// </summary>
+/**
+ * Simple tokenizer used for default SK template code language.
+ *
+ * BNF parsed by TemplateTokenizer:
+ * [template]       ::= "" | [block] | [block] [template]
+ * [block]          ::= [sk-block] | [text-block]
+ * [sk-block]       ::= "{{" [variable] "}}" | "{{" [value] "}}" | "{{" [function-call] "}}"
+ * [text-block]     ::= [any-char] | [any-char] [text-block]
+ * [any-char]       ::= any char
+ *
+ * BNF parsed by CodeTokenizer:
+ * [template]       ::= "" | [variable] " " [template] | [value] " " [template] | [function-call] "
+ * [variable]       ::= "$" [valid-name]
+ * [value]          ::= "'" [text] "'" | '"' [text] '"'
+ * [function-call]  ::= [function-id] | [function-id] [parameter]
+ * [parameter]      ::= [variable] | [value]
+ *
+ * BNF parsed by dedicated blocks
+ * [function-id]    ::= [valid-name] | [valid-name] "." [valid-name]
+ * [valid-name]     ::= [valid-symbol] | [valid-symbol] [valid-name]
+ * [valid-symbol]   ::= [letter] | [digit] | "_"
+ * [letter]         ::= "a" | "b" ... | "z" | "A" | "B" ... | "Z"
+ * [digit]          ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+ */
 public class CodeTokenizer {
 
     private enum TokenTypes {
@@ -52,14 +53,17 @@ public class CodeTokenizer {
         }
     }
 
+    /**
+     * Initializes a new instance of the {@link CodeTokenizer} class.
+     */
     public CodeTokenizer() {
     }
 
-    /// <summary>
-    /// Tokenize a code block, without checking for syntax errors
-    /// </summary>
-    /// <param name="text">Text to parse</param>
-    /// <returns>A list of blocks</returns>
+    /**
+     * Tokenize a code block, without checking for syntax errors
+     * @param text Text to parse
+     * @return A list of blocks
+     */
     public List<Block> tokenize(String text) {
         if (text == null) {
             return new ArrayList<>();

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/DefaultPromptTemplate.java

@@ -15,32 +15,39 @@ import com.microsoft.semantickernel.templateengine.semantickernel.blocks.CodeRen
 import com.microsoft.semantickernel.templateengine.semantickernel.blocks.NamedArgBlock;
 import com.microsoft.semantickernel.templateengine.semantickernel.blocks.TextRendering;
 import com.microsoft.semantickernel.templateengine.semantickernel.blocks.VarBlock;
+
 import java.util.HashSet;
 import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 import java.util.stream.Collectors;
+
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
+
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
-/// <summary>
-/// Prompt template.
-/// </summary>
+/**
+ * The default prompt template.
+ */
 public class DefaultPromptTemplate implements PromptTemplate {
 
     private final PromptTemplateConfig promptTemplate;
 
+    /**
+     * Create a new prompt template.
+     * @param promptTemplateConfig The prompt template configuration.
+     */
     public DefaultPromptTemplate(
-        @Nonnull PromptTemplateConfig promptTemplate) {
-        this.promptTemplate = new PromptTemplateConfig(promptTemplate);
+        @Nonnull PromptTemplateConfig promptTemplateConfig) {
+        this.promptTemplate = new PromptTemplateConfig(promptTemplateConfig);
     }
 
-    /// <summary>
-    /// Given a prompt template string, extract all the blocks (text, variables, function calls)
-    /// </summary>
-    /// <returns>A list of all the blocks, ie the template tokenized in text, variables and function calls</returns>
+    /*
+     * Given a prompt template string, extract all the blocks (text, variables, function calls)
+     * @return A list of all the blocks, ie the template tokenized in text, variables and function calls
+     */
     private List<Block> extractBlocks() {
         String templateText = promptTemplate.getTemplate();
 
@@ -60,10 +67,11 @@ public class DefaultPromptTemplate implements PromptTemplate {
     }
 
 
-    /// <summary>
-    /// Augments <paramref name="config"/>'s <see cref="PromptTemplateConfig.InputVariables"/> with any variables
-    /// not already contained there but that are referenced in the prompt template.
-    /// </summary>
+    /**
+     * Augments the prompt template with any variables
+     * not already contained there but that are referenced in the prompt template.
+     * @param blocks The blocks to search for input variables.
+     */
     @SuppressWarnings("NullAway")
     private void addMissingInputVariables(List<Block> blocks) {
         // Add all of the existing input variables to our known set. We'll avoid adding any

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/TemplateException.java

@@ -2,9 +2,13 @@
 package com.microsoft.semantickernel.templateengine.semantickernel;
 
 import com.microsoft.semantickernel.exceptions.SKException;
+
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
+/**
+ * Exception thrown when a template error occurs.
+ */
 public class TemplateException extends SKException {
 
     @Nonnull
@@ -50,9 +54,8 @@ public class TemplateException extends SKException {
     // spotless:off
 
     /**
-     * <p>
      * Gets the error code for this exception.
-     * </p>
+     * @return The error code.
      */
     //spotless:on
     public ErrorCodes getErrorCode() {
@@ -62,53 +65,41 @@ public class TemplateException extends SKException {
     // spotless:off
 
     /**
-     * <p>
      * Error codes for {@code TemplateException}.
-     * </p>
      */
     //spotless:on
     public enum ErrorCodes {
 
         // spotless:off
         /**
-         * <p>
          * Unknown error.
-         * </p>
          */
         //spotless:on
         UNKNOWN_ERROR("Unknown error"),
 
         // spotless:off
         /**
-         * <p>
          * Syntax error, the template syntax used is not valid.
-         * </p>
          */
         //spotless:on
         SYNTAX_ERROR("Syntax error, the template syntax used is not valid"),
 
         // spotless:off
         /**
-         * <p>
          * The block type produced be the tokenizer was not expected.
-         * </p>
          */
         UNEXPECTED_BLOCK_TYPE("The block type produced be the tokenizer was not expected"),
 
         //spotless:off
         /**
-         * <p>
          * The template requires an unknown function.
-         * </p>
          */
         //spotless:on
         FUNCTION_NOT_FOUND("The template requires an unknown function"),
 
         // spotless:off
         /**
-         * <p>
          * The template execution failed, e.g. a function call threw an exception.
-         * </p>
          */
         //spotless:on
         RUNTIME_ERROR("The template execution failed, e.g. a function call threw an exception");
@@ -119,6 +110,12 @@ public class TemplateException extends SKException {
             this.message = message;
         }
 
+        // spotless:off
+        /**
+         * Gets the message for the error code.
+         * @return The error code message
+         */
+        //spotless:on
         public String getMessage() {
             return message;
         }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/TemplateTokenizer.java

@@ -9,48 +9,38 @@ import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
-/// <summary>
-/// Simple tokenizer used for default SK template language.
-///
-/// BNF parsed by TemplateTokenizer:
-/// [template]       ::= "" | [block] | [block] [template]
-/// [block]          ::= [sk-block] | [text-block]
-/// [sk-block]       ::= "{{" [variable] "}}" | "{{" [value] "}}" | "{{" [function-call] "}}"
-/// [text-block]     ::= [any-char] | [any-char] [text-block]
-/// [any-char]       ::= any char
-///
-/// BNF parsed by CodeTokenizer:
-/// [template]       ::= "" | [variable] " " [template] | [value] " " [template] | [function-call] "
-// " [template]
-/// [variable]       ::= "$" [valid-name]
-/// [value]          ::= "'" [text] "'" | '"' [text] '"'
-/// [function-call]  ::= [function-id] | [function-id] [parameter]
-/// [parameter]      ::= [variable] | [value]
-///
-/// BNF parsed by dedicated blocks
-/// [function-id]    ::= [valid-name] | [valid-name] "." [valid-name]
-/// [valid-name]     ::= [valid-symbol] | [valid-symbol] [valid-name]
-/// [valid-symbol]   ::= [letter] | [digit] | "_"
-/// [letter]         ::= "a" | "b" ... | "z" | "A" | "B" ... | "Z"
-/// [digit]          ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
-/// </summary>
+/**
+ *  Simple tokenizer used for default SK template language.
+ * 
+ *  BNF parsed by TemplateTokenizer:
+ *  [template]       ::= "" | [block] | [block] [template]
+ *  [block]          ::= [sk-block] | [text-block]
+ *  [sk-block]       ::= "{{" [variable] "}}" | "{{" [value] "}}" | "{{" [function-call] "}}"
+ *  [text-block]     ::= [any-char] | [any-char] [text-block]
+ *  [any-char]       ::= any char
+ * 
+ *  BNF parsed by CodeTokenizer:
+ *  [template]       ::= "" | [variable] " " [template] | [value] " " [template] | [function-call] "
+ * 
+ *  [variable]       ::= "$" [valid-name]
+ *  [value]          ::= "'" [text] "'" | '"' [text] '"'
+ *  [function-call]  ::= [function-id] | [function-id] [parameter]
+ *  [parameter]      ::= [variable] | [value]
+ * 
+ *  BNF parsed by dedicated blocks
+ *  [function-id]    ::= [valid-name] | [valid-name] "." [valid-name]
+ *  [valid-name]     ::= [valid-symbol] | [valid-symbol] [valid-name]
+ *  [valid-symbol]   ::= [letter] | [digit] | "_"
+ *  [letter]         ::= "a" | "b" ... | "z" | "A" | "B" ... | "Z"
+ *  [digit]          ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+ */
 public class TemplateTokenizer {
-    /*
-        /// <summary>
-        /// Create a new instance of SK tokenizer
-        /// </summary>
-        /// <param name="log"></param>
-        public TemplateTokenizer(ILogger? log = null)
-        {
-            this._log = log ?? NullLogger.Instance;
-            this._codeTokenizer = new CodeTokenizer(this._log);
-        }
-    */
-    /// <summary>
-    /// Extract blocks from the given text
-    /// </summary>
-    /// <param name="text">Text to parse</param>
-    /// <returns>List of blocks found in the text</returns>
+
+    /**
+     *  Extract blocks from the given text
+     * @param text Text to parse
+     * @return List of blocks found in the text
+     */
     public List<Block> tokenize(String text) {
         // An empty block consists of 4 chars: "{{}}"
         int EMPTY_CODE_BLOCK_LENGTH = 4;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/blocks/BlockTypes.java

@@ -1,6 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.templateengine.semantickernel.blocks;
 
+/**
+ * Block types
+ */
 public enum BlockTypes {
     /**
      * Undefined block type
@@ -26,6 +29,9 @@ public enum BlockTypes {
      * Function block type
      */
     FunctionId(5),
+    /**
+     * Named argument block type
+     */
     NamedArg(6);
 
     BlockTypes(int i) {

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/blocks/CodeBlock.java

@@ -24,11 +24,20 @@ import org.slf4j.LoggerFactory;
 
 import reactor.core.publisher.Mono;
 
+/**
+ * Represents a code block.
+ */
 public final class CodeBlock extends Block implements CodeRendering {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(CodeBlock.class);
     private final List<Block> tokens;
 
+    /**
+     * Initializes a new instance of the {@link CodeBlock} class.
+     *
+     * @param tokens  The tokens.
+     * @param content The content.
+     */
     public CodeBlock(List<Block> tokens, String content) {
         super(content, BlockTypes.Code);
         this.tokens = Collections.unmodifiableList(tokens);

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/blocks/CodeRendering.java

@@ -4,7 +4,9 @@ package com.microsoft.semantickernel.templateengine.semantickernel.blocks;
 import com.microsoft.semantickernel.Kernel;
 import com.microsoft.semantickernel.orchestration.InvocationContext;
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
+
 import javax.annotation.Nullable;
+
 import reactor.core.publisher.Mono;
 
 /**
@@ -17,7 +19,10 @@ public interface CodeRendering {
      *
      * @param kernel    Kernel to use for rendering
      * @param arguments Optional arguments used to render the block
+     * @param context   Optional context used to render the block, 
+     *                  typically used to pass {code KernelHooks} to the render method.
      * @return Rendered content
+     * @see com.microsoft.semantickernel.hooks.KernelHooks
      */
     Mono<String> renderCodeAsync(
         Kernel kernel,

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/blocks/FunctionIdBlock.java

@@ -1,15 +1,23 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.templateengine.semantickernel.blocks;
 
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
 
+import javax.annotation.Nullable;
+
+/**
+ * Represents a function identifier block.
+ */
 public final class FunctionIdBlock extends Block implements TextRendering {
     private final String skillName;
 
     private final String functionName;
 
+    /**
+     * Initializes a new instance of the {@link FunctionIdBlock} class.
+     *
+     * @param content The content.
+     */
     public FunctionIdBlock(String content) {
         super(content, BlockTypes.FunctionId);
 
@@ -61,10 +69,20 @@ public final class FunctionIdBlock extends Block implements TextRendering {
         return value.matches("^.*\\..*\\..*$");
     }
 
+    /**
+     * Get the plugin name.
+     *
+     * @return The plugin name.
+     */
     public String getPluginName() {
         return skillName;
     }
 
+    /**
+     * Get the function name.
+     *
+     * @return The function name.
+     */
     public String getFunctionName() {
         return functionName;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/templateengine/semantickernel/blocks/TextRendering.java

@@ -1,19 +1,20 @@
 // Copyright (c) Microsoft. All rights reserved.
 package com.microsoft.semantickernel.templateengine.semantickernel.blocks;
 
-import javax.annotation.Nullable;
-
 import com.microsoft.semantickernel.orchestration.KernelFunctionArguments;
 
-/// <summary>
-/// Interface of static blocks that don't need async IO to be rendered.
-/// </summary>
+import javax.annotation.Nullable;
+
+/**
+ * Interface of static blocks that don't need async IO to be rendered.
+ */
 public interface TextRendering {
-    /// <summary>
-    /// Render the block using only the given variables.
-    /// </summary>
-    /// <param name="variables">Optional variables used to render the block</param>
-    /// <returns>Rendered content</returns>
+
+    /**
+     * Render the block using only the given variables.
+     * @param variables Optional variables used to render the block
+     * @return Rendered content
+     */
     @Nullable
     String render(@Nullable KernelFunctionArguments variables);
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/textcompletion/StreamingTextContent.java

@@ -2,10 +2,24 @@ package com.microsoft.semantickernel.textcompletion;
 
 import com.microsoft.semantickernel.StreamingKernelContent;
 
+/**
+ * StreamingTextContent is a wrapper for TextContent that allows for streaming.
+ */
 public class StreamingTextContent extends StreamingKernelContent<TextContent> {
 
+    /**
+     * Initializes a new instance of the {@code StreamingTextContent} class with a provided text content.
+     *
+     * @param content The text content.
+     */
     public StreamingTextContent(TextContent content) {
         super(content, 0, null, null);
     }
 
+
+    @Override
+    public String getContent() {
+        return ((TextContent)getInnerContent()).getContent();
+    }
+
 }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/textcompletion/TextContent.java

@@ -3,10 +3,20 @@ package com.microsoft.semantickernel.textcompletion;
 import com.microsoft.semantickernel.KernelContent;
 import com.microsoft.semantickernel.orchestration.FunctionResultMetadata;
 
+/**
+ * Content from a text completion service.
+ */
 public class TextContent extends KernelContent<TextContent> {
 
     private final String content;
 
+    /**
+     * Initializes a new instance of the {@code TextContent} class with a provided content, model ID, and metadata.
+     *
+     * @param content The content.
+     * @param modelId The model ID.
+     * @param metadata The metadata.
+     */
     public TextContent(
         String content,
         String modelId,
@@ -15,6 +25,10 @@ public class TextContent extends KernelContent<TextContent> {
         this.content = content;
     }
 
+    /**
+     * Gets the content.
+     * @return The content.
+     */
     public String getValue() {
         return content;
     }

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/textcompletion/TextGenerationService.java

@@ -8,8 +8,11 @@ import com.microsoft.semantickernel.builders.Buildable;
 import com.microsoft.semantickernel.builders.SemanticKernelBuilder;
 import com.microsoft.semantickernel.builders.ServiceLoadUtil;
 import com.microsoft.semantickernel.orchestration.PromptExecutionSettings;
+
 import java.util.List;
+
 import javax.annotation.Nullable;
+
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
@@ -23,6 +26,8 @@ public interface TextGenerationService extends Buildable, TextAIService {
      *
      * @param prompt            The prompt to complete.
      * @param executionSettings Request settings for the completion API
+     * @param kernel            The {@code Kernel} containing services, plugins, and other state for
+     *                         use throughout the operation.
      * @return Text generated by the remote model
      */
     Mono<List<TextContent>> getTextContentsAsync(
@@ -36,8 +41,8 @@ public interface TextGenerationService extends Buildable, TextAIService {
      *
      * @param prompt            The prompt to complete.
      * @param executionSettings The AI execution settings (optional).
-     * @param kernel            The <see cref="Kernel"/> containing services, plugins, and other
-     *                          state for use throughout the operation.
+     * @param kernel            The {@code Kernel} containing services, plugins, and other state for
+     *                         use throughout the operation.
      * @return Streaming list of different completion streaming string updates generated by the
      * remote model
      */
@@ -46,6 +51,10 @@ public interface TextGenerationService extends Buildable, TextAIService {
         @Nullable PromptExecutionSettings executionSettings,
         @Nullable Kernel kernel);
 
+    /**
+     * Get the builder for the TextGenerationService
+     * @return The builder
+     */
     static Builder builder() {
         return ServiceLoadUtil.findServiceLoader(Builder.class,
                 "com.microsoft.semantickernel.aiservices.openai.textcompletion.OpenAITextGenerationService$Builder")
@@ -65,16 +74,34 @@ public interface TextGenerationService extends Buildable, TextAIService {
         @Nullable
         protected String serviceId;
 
+        /**
+         * Sets the model ID for the service
+         *
+         * @param modelId The model ID
+         * @return The builder
+         */
         public Builder withModelId(String modelId) {
             this.modelId = modelId;
             return this;
         }
 
+        /**
+         * Sets the OpenAI client for the service
+         *
+         * @param client The OpenAI client
+         * @return The builder
+         */
         public Builder withOpenAIAsyncClient(OpenAIAsyncClient client) {
             this.client = client;
             return this;
         }
 
+        /**
+         * Sets the service ID for the service
+         *
+         * @param serviceId The service ID
+         * @return The builder
+         */
         public Builder withServiceId(String serviceId) {
             this.serviceId = serviceId;
             return this;

java/semantickernel-api/src/main/java/com/microsoft/semantickernel/util/EmbeddedResourceLoader.java

@@ -14,11 +14,26 @@ import java.util.Objects;
 import java.util.Optional;
 import java.util.stream.Collectors;
 
+/**
+ * Utility class for loading resources from the classpath or filesystem.
+ */
 public class EmbeddedResourceLoader {
 
+    /**
+     * Enum for specifying the location of the resource
+     */
     public enum ResourceLocation {
+        /**
+         * Load from the classpath
+         */
         CLASSPATH,
+        /**
+         * Load from the filesystem
+         */
         FILESYSTEM,
+        /**
+         * Load from the classpath root
+         */
         CLASSPATH_ROOT
     }
 
@@ -26,6 +41,7 @@ public class EmbeddedResourceLoader {
      * Loads a file to a string from the classpath using getResourceAsStream
      *
      * @param fileName Filename to read
+     * @param clazz Class to use for classpath loading
      * @return File content
      * @throws FileNotFoundException Error in case the file doesn't exist
      */
@@ -37,6 +53,8 @@ public class EmbeddedResourceLoader {
      * Loads a file to a string from the classpath, classpath root or filesystem
      *
      * @param fileName Filename to read
+     * @param clazz Class to use for classpath loading
+     * @param locations Locations to search for the file
      * @return File content
      * @throws FileNotFoundException Error in case the file doesn't exist
      */