Java: Docs (microsoft#3299)

### 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/README.md

@@ -14,7 +14,7 @@ and frameworks.
 
 To run the LLM prompts and semantic functions in this kernel, make sure you have
 an [Open AI API Key](https://openai.com/api/)
-or [Azure Open AI service key](https://learn.microsoft.com/azure/cognitive-services/openai/quickstart?pivots=rest-api).
+or [Azure Open AI service key](https://learn.microsoft.com/azure/cognitive-services/openai/).
 
 ### Requirements
 
@@ -27,7 +27,7 @@ To build the Semantic Kernel, you will need:
 
 1. Clone this repository
 
-        git clone -b experimental-java https://github.com/microsoft/semantic-kernel/
+        git clone -b java-development https://github.com/microsoft/semantic-kernel/
 
 2. Build the Semantic Kernel
 
@@ -86,7 +86,7 @@ Also ensure that:
 - All new code is covered by unit tests
 - All new code is covered by integration tests
 
-Once your proposal is ready, submit a pull request to the `main` branch. The pull request will be reviewed by the
+Once your proposal is ready, submit a pull request to the `java-development` branch. The pull request will be reviewed by the
 project maintainers.
 
 Make sure your pull request has an objective title and a clear description explaining the problem and solution.

java/samples/sample-code/README.md

@@ -34,12 +34,10 @@ They can then be run by:
 
 # Configuration
 
-By default, the samples will use the Open AI client, but you can also use the Azure Open AI client.
-
-## Open AI client type
-
-You can define the provider of Open AI (openai.com or Azure), this can be done by setting the `OPENAI_CLIENT_TYPE`
-property or environment variable to either `OPENAI` or `AZURE_OPEN_AI`, i.e.:
+You can define the provider of Open AI by setting the `OPENAI_CLIENT_TYPE`
+property or environment variable to either [`OPENAI`](https://openai.com/api/)
+or [`AZURE_OPEN_AI`](https://learn.microsoft.com/azure/cognitive-services/openai/).
+By default, the samples will use the Open AI client.
 
 ```shell
 OPENAI_CLIENT_TYPE=OPEN_AI ../../mvnw exec:java -Dsample=Example04_CombineLLMPromptsAndNativeCode
@@ -50,7 +48,7 @@ OR
 ```
 
 ## Client Settings
-The tests search for the client settings in the following order:
+The samples search for the client settings in the following order:
 1. Properties file whose location is defined by the `CONF_PROPERTIES` property or environment variable.
 1. System properties defined on the command line.
 1. Environment variables.

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

@@ -12,6 +12,15 @@
 
 import java.io.IOException;
 
+/**
+ * Code for Microsoft Developer Blog
+ * <a href="https://devblogs.microsoft.com/semantic-kernel/introducing-semantic-kernel-for-java/">
+ * Introducing Semantic Kernel for Java</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example99_BlogAnnouncement {
 
   static {

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

@@ -11,6 +11,13 @@
 import com.microsoft.semantickernel.skilldefinition.annotations.SKFunctionParameters;
 import com.microsoft.semantickernel.textcompletion.TextCompletion;
 
+/**
+ * Example of a planner which uses native functions.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example_PlanWithNativeFunctions {
 
     public static void main(String[] args) throws ConfigurationException {

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

@@ -8,6 +8,12 @@
 import java.io.File;
 import java.util.List;
 
+/**
+ * Helper for creating
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class SamplesConfig {
 
     public static final List<File> DEFAULT_PROPERTIES_LOCATIONS = List.of(

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

@@ -22,13 +22,14 @@
 /**
  * Getting started
  * <p>
- * Create a conf.properties file based on the examples files at the root of this
- * module.
- * <p>
  * <a href=
  * "https://learn.microsoft.com/en-us/azure/cognitive-services/openai/quickstart">Get
  * started with Azure OpenAI</a>
  * <a href="https://openai.com/product">Get started with OpenAI</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
  */
 public class Example00_GettingStarted {
 

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

@@ -28,6 +28,10 @@
  * The repository includes some examples under the <a href=
  * "https://github.com/microsoft/semantic-kernel/tree/main/samples">samples</a>
  * folder.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
  */
 public class Example02_RunningPromptsFromFile {
 

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

@@ -19,6 +19,10 @@
 
 /**
  * Define a Semantic Function inline with Java code.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
  */
 public class Example03_SemanticFunctionInline {
 

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

@@ -27,6 +27,10 @@
  * key-value store that you can use when running the kernel.
  * The context is local (i.e. in your computer's RAM) and not persisted anywhere
  * beyond the life of the JVM execution.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
  */
 public class Example04_ContextVariablesChat {
     public static void startChat(Kernel kernel)

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

@@ -11,9 +11,22 @@
 import com.microsoft.semantickernel.Kernel;
 import com.microsoft.semantickernel.connectors.ai.openai.util.OpenAIClientProvider;
 import com.microsoft.semantickernel.exceptions.ConfigurationException;
+import com.microsoft.semantickernel.orchestration.SKContext;
+import com.microsoft.semantickernel.planner.actionplanner.Plan;
 import com.microsoft.semantickernel.planner.sequentialplanner.SequentialPlanner;
 import com.microsoft.semantickernel.samples.syntaxexamples.SampleSkillsUtil;
 
+/**
+ * Sequential Planner
+ * <p>
+ * See <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-sequential-planner/">
+ * Semantic Kernel Planners: Sequential Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example05_UsingThePlanner {
 
     public static SequentialPlanner getPlanner(Kernel kernel) {

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

@@ -2,6 +2,9 @@
 
 import com.microsoft.semantickernel.coreskills.TextSkill;
 
+/**
+ * Demonstrates a native function from the {@code com.microsoft.semantickernel.coreskills} package.
+ */
 public class Example01_NativeFunctions {
 
     public static void main(String[] args) {

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

@@ -7,6 +7,9 @@
 import com.microsoft.semantickernel.skilldefinition.ReadOnlyFunctionCollection;
 import reactor.core.publisher.Mono;
 
+/**
+ * Demonstrates running a pipeline (a sequence of functions) over some input.
+ */
 public class Example02_Pipeline {
     public static void main(String[] args) {
         Kernel kernel = SKBuilders.kernel().build();

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

@@ -13,6 +13,10 @@
 
 import java.util.Locale;
 
+/**
+ * Demonstrates running a pipeline (a sequence of functions) on a
+ * {@code com.microsoft.semantickernel.orchestration.SKContext}
+ */
 public class Example03_Variables {
 
     public static class StaticTextSkill {

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

@@ -12,11 +12,18 @@
 import com.microsoft.semantickernel.textcompletion.TextCompletion;
 import reactor.core.publisher.Mono;
 
+/**
+ * Demonstrates using skill in combination with LLM prompts.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example04_CombineLLMPromptsAndNativeCode {
 
   public static class SearchEngineSkill {
 
-    @DefineSKFunction(description = "Append the day variable", name = "search")
+    @DefineSKFunction(description = "Search for answer", name = "search")
     public Mono<String> search(
         @SKFunctionInputAttribute(description = "Text to search")
         String input) {

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

@@ -14,6 +14,13 @@
 import java.time.format.DateTimeFormatter;
 import java.time.format.FormatStyle;
 
+/**
+ * Demonstrates using prompt templates to define functions.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example05_InlineFunctionDefinition {
   public static void main(String[] args) throws ConfigurationException {
     OpenAIAsyncClient client = SamplesConfig.getClient();

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

@@ -10,11 +10,15 @@
 import com.microsoft.semantickernel.orchestration.SKContext;
 import com.microsoft.semantickernel.semanticfunctions.PromptTemplateConfig;
 
+/**
+ * Show how to invoke a Native Function written in Java
+ * from a Semantic Function written in natural language
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example06_TemplateLanguage {
-    /// <summary>
-    /// Show how to invoke a Native Function written in C#
-    /// from a Semantic Function written in natural language
-    /// </summary>
 
     public static void main(String[] args) throws ConfigurationException {
         System.out.println("======== TemplateLanguage ========");

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

@@ -20,6 +20,13 @@
 
 import static com.microsoft.semantickernel.SamplesConfig.DEFAULT_PROPERTIES_LOCATIONS;
 
+/**
+ * Demonstrates customizing the configuration of the Open AI client.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for endpoint and credential configuration.
+ */
 public class Example08_RetryHandler {
 
     public static void main(String[] args) throws ConfigurationException {

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

@@ -14,6 +14,13 @@
 
 import java.time.Duration;
 
+/**
+ * Demonstrates how the Kernel uses functions loaded from skills.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example09_FunctionTypes {
     public static void main(String[] args) throws ConfigurationException {
         OpenAIAsyncClient client = SamplesConfig.getClient();

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

@@ -19,6 +19,15 @@
 
 import java.util.Set;
 
+/**
+ * Demonstrates the <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-sequential-planner/">
+ * Sequential Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example12_SequentialPlanner {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(Example12_SequentialPlanner.class);

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

@@ -13,6 +13,13 @@
 import com.microsoft.semantickernel.textcompletion.TextCompletion;
 import reactor.core.publisher.Mono;
 
+/**
+ * Demonstrate the {@code com.microsoft.semantickernel.coreskills.ConversationSummarySkill}
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example13_ConversationSummarySkill {
     private static final String ChatTranscript =
             """

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

@@ -14,16 +14,23 @@
 import java.util.stream.Collectors;
 
 
-/* The files contain two examples about SK Semantic Memory.
+/**
+ * Demonstrate two examples about SK Semantic Memory:
  *
  * 1. Memory using Azure Cognitive Search.
  * 2. Memory using a custom embedding generator and vector engine.
  *
  * Semantic Memory allows to store your data like traditional DBs,
  * adding the ability to query it using natural language.
+ * <p>
+ * You must <a href=
+ * "https://learn.microsoft.com/en-us/azure/search/search-create-service-portal">
+ * create an Azure Cognitive Search service in the portal</a> to run this example.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
  */
-
-// ReSharper disable once InconsistentNaming
 public class Example14_SemanticMemory {
     private static final String MEMORY_COLLECTION_NAME = "SKGitHub";
 

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

@@ -18,6 +18,13 @@
 import java.util.stream.Collectors;
 import reactor.core.publisher.Mono;
 
+/**
+ * Demonstrates saving and retrieving memories.
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example15_MemorySkill {
     private static final String MEMORY_COLLECTION_NAME = "aboutMe";
 

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

@@ -11,8 +11,11 @@
 import com.microsoft.semantickernel.exceptions.ConfigurationException;
 
 /**
- * The following example shows how to use Semantic Kernel with OpenAI ChatGPT
- * API
+ * Demonstrates the use of Semantic Kernel with OpenAI ChatGPT API
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
  */
 public class Example17_ChatGPT {
 

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

@@ -18,7 +18,7 @@
 import java.util.stream.Collectors;
 
 /**
- * This sample provides a custom implementation of {@code MemoryStore} that is read only.
+ * Demonstrates a custom implementation of {@code MemoryStore} that is read only.
  * In this sample, the data is stored in a JSON String and deserialized into an
  * {@code MemoryRecord[]}. For this specific sample, the implementation
  * of {@code MemoryStore}  has a single collection, and thus does not need to be named.

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

@@ -8,6 +8,15 @@
 import com.microsoft.semantickernel.exceptions.ConfigurationException;
 import com.microsoft.semantickernel.planner.actionplanner.ActionPlanner;
 
+/**
+ * Demonstrates the <a href=
+ * "https://devblogs.microsoft.com/semantic-kernel/semantic-kernel-planners-actionplanner/">
+ * Action Planner</a>
+ * <p>
+ * Refer to the <a href=
+ * "https://github.com/microsoft/semantic-kernel/blob/experimental-java/java/samples/sample-code/README.md">
+ * README</a> for configuring your environment to run the examples.
+ */
 public class Example28_ActionPlanner {
     public static void main(String[] args) throws ConfigurationException {
         OpenAIAsyncClient client = SamplesConfig.getClient();