chore(comment): Add Java doc comments

Author: codeboyzhou

src/main/java/com/github/codeboyzhou/mcp/declarative/McpServers.java

@@ -18,18 +18,51 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-public class McpServers {
+/**
+ * This class is a singleton that provides methods to start MCP servers.
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * McpServerInfo serverInfo = McpServerInfo.builder().build();
+ * McpServers.run(MyApplication.class, args).startStdioServer(serverInfo);
+ *
+ * McpSseServerInfo sseServerInfo = McpSseServerInfo.builder().build();
+ * McpServers.run(MyApplication.class, args).startSseServer(sseServerInfo);
+ *
+ * McpStreamableServerInfo streamableServerInfo = McpStreamableServerInfo.builder().build();
+ * McpServers.run(MyApplication.class, args).startStreamableServer(streamableServerInfo);
+ *
+ * McpServers.run(MyApplication.class, args).startServer("mcp-server-config.yml");
+ *
+ * McpServers.run(MyApplication.class, args).startServer();
+ * }</pre>
+ *
+ * @see <a href="https://codeboyzhou.github.io/mcp-declarative-java-sdk/getting-started">MCP
+ *     Declarative Java SDK Documentation</a>
+ * @author codeboyzhou
+ */
+public final class McpServers {
 
   private static final Logger log = LoggerFactory.getLogger(McpServers.class);
 
+  /** The singleton instance of McpServers. */
   private static final McpServers INSTANCE = new McpServers();
 
+  /** The dependency injector used to inject server components. */
   private static DependencyInjector injector;
 
-  private McpServers() {
-    // Using singleton design pattern should have private constructor
-  }
+  /**
+   * The constructor of McpServers. Using singleton design pattern should have private constructor.
+   */
+  private McpServers() {}
 
+  /**
+   * Initializes the McpServers instance with the specified application main class and arguments.
+   *
+   * @param applicationMainClass the main class of the application
+   * @param args the arguments passed to the application
+   * @return the singleton instance of McpServers
+   */
   public static McpServers run(Class<?> applicationMainClass, String[] args) {
     GuiceInjectorModule module = new GuiceInjectorModule(applicationMainClass);
     DependencyInjector injector = new GuiceDependencyInjector(Guice.createInjector(module));
@@ -38,29 +71,55 @@ public static McpServers run(Class<?> applicationMainClass, String[] args) {
     return INSTANCE;
   }
 
+  /**
+   * Starts a standard input/output (stdio) server with the specified server info.
+   *
+   * @param serverInfo the server info for the stdio server
+   */
   public void startStdioServer(McpServerInfo serverInfo) {
     injector.getInstance(McpStdioServer.class).start(serverInfo);
   }
 
+  /**
+   * Starts a http server-sent events (sse) server with the specified server info.
+   *
+   * @param serverInfo the server info for the sse server
+   */
   public void startSseServer(McpSseServerInfo serverInfo) {
     injector.getInstance(McpSseServer.class).start(serverInfo);
   }
 
+  /**
+   * Starts a streamable http server with the specified server info.
+   *
+   * @param serverInfo the server info for the streamable server
+   */
   public void startStreamableServer(McpStreamableServerInfo serverInfo) {
     injector.getInstance(McpStreamableServer.class).start(serverInfo);
   }
 
+  /**
+   * Starts a server with the specified configuration file name.
+   *
+   * @param configFileName the name of the configuration file
+   */
   public void startServer(String configFileName) {
     Assert.notNull(configFileName, "configFileName must not be null");
     YAMLConfigurationLoader configLoader = new YAMLConfigurationLoader(configFileName);
     doStartServer(configLoader.loadConfig());
   }
 
+  /** Starts a server with the default configuration file name. */
   public void startServer() {
     YAMLConfigurationLoader configLoader = new YAMLConfigurationLoader();
     doStartServer(configLoader.loadConfig());
   }
 
+  /**
+   * Starts a server with the specified server configuration.
+   *
+   * @param configuration the server configuration
+   */
   private void doStartServer(McpServerConfiguration configuration) {
     if (configuration.enabled()) {
       ConfigurableMcpServerFactory.getServer(configuration).startServer();

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpI18nEnabled.java

@@ -5,6 +5,26 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to mark a class as i18n enabled.
+ *
+ * <p>When the main class of MCP (Model Context Protocol) server application is annotated with
+ * {@code @McpI18nEnabled}, it indicates that the server application supports internationalization
+ * (i18n) for tool/prompt/resource methods. This allows for the translation of tool/prompt/resource
+ * titles and descriptions into different languages.
+ *
+ * <p>Note: This annotation is only applicable to the main class of the MCP server application.
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * @McpI18nEnabled
+ * public class MyMcpServerApplication {
+ *     // Application logic...
+ * }
+ * }</pre>
+ *
+ * @author codeboyzhou
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpI18nEnabled {}

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaDefinition.java

@@ -5,6 +5,17 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to define the complex JSON schema type (such as custom Java data classes)
+ * for an MCP (Model Context Protocol) server.
+ *
+ * <p>By using this annotation, you can define custom JSON schema types that are not natively
+ * supported by the MCP protocol. This allows you to use more complex data models in your MCP
+ * server.
+ *
+ * @see McpJsonSchemaDefinitionProperty
+ * @author codeboyzhou
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpJsonSchemaDefinition {}

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpJsonSchemaDefinitionProperty.java

@@ -6,12 +6,33 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to define the property of a complex JSON schema type (such as custom Java
+ * data classes) for an MCP (Model Context Protocol) server.
+ *
+ * <p>By using this annotation, you can define custom JSON schema properties that are not natively
+ * supported by the MCP protocol. This allows you to use more complex data models in your MCP
+ * server.
+ *
+ * @see McpJsonSchemaDefinition
+ * @author codeboyzhou
+ */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpJsonSchemaDefinitionProperty {
+
+  /** The name of the JSON schema property. If not specified, the field name will be used. */
   String name() default StringHelper.EMPTY;
 
+  /**
+   * The description of the JSON schema property. If not specified, the default value {@code "Not
+   * specified"} will be used.
+   */
   String description() default StringHelper.EMPTY;
 
+  /**
+   * Whether the JSON schema property is required. If not specified, the default value {@code false}
+   * will be used.
+   */
   boolean required() default false;
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPrompt.java

@@ -6,13 +6,35 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to mark a method as an MCP (Model Context Protocol) prompt method.
+ *
+ * <p>The prompt's name defaults to the name of the annotated method. Prompt metadata such as title
+ * and description can be specified via the corresponding attributes. If omitted, these metadata
+ * fields will default to the literal string "Not specified".
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * @McpPrompt
+ * public String getWeather(String city) {
+ *     // Method implementation...
+ * }
+ * }</pre>
+ *
+ * @see <a
+ *     href="https://modelcontextprotocol.io/docs/learn/server-concepts#core-server-features">MCP
+ *     Protocol Documentation</a>
+ * @author codeboyzhou
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpPrompt {
-
+  /** The name of the prompt. Defaults to the name of the annotated method. */
   String name() default StringHelper.EMPTY;
 
+  /** The title of the prompt. Defaults to the literal string "Not specified". */
   String title() default StringHelper.EMPTY;
 
+  /** The description of the prompt. Defaults to the literal string "Not specified". */
   String description() default StringHelper.EMPTY;
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPromptParam.java

@@ -6,15 +6,39 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to mark a method parameter as an MCP (Model Context Protocol) prompt
+ * parameter.
+ *
+ * <p>The parameter's name must be specified explicitly. Parameter metadata such as title,
+ * description, and required can be specified via the corresponding attributes. If omitted, these
+ * metadata fields will default to the literal string "Not specified" and {@code false}.
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * @McpPrompt
+ * public String getWeather(@McpPromptParam(name = "city") String city) {
+ *     // Method implementation...
+ * }
+ * }</pre>
+ *
+ * @see <a
+ *     href="https://modelcontextprotocol.io/docs/learn/server-concepts#core-server-features">MCP
+ *     Protocol Documentation</a>
+ * @author codeboyzhou
+ */
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpPromptParam {
-
+  /** The name of the prompt parameter. */
   String name();
 
+  /** The title of the prompt parameter. Defaults to the literal string "Not specified". */
   String title() default StringHelper.EMPTY;
 
+  /** The description of the prompt parameter. Defaults to the literal string "Not specified". */
   String description() default StringHelper.EMPTY;
 
+  /** Whether the prompt parameter is required. Defaults to {@code false}. */
   boolean required() default false;
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpResource.java

@@ -7,20 +7,50 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to mark a method as an MCP (Model Context Protocol) resource method.
+ *
+ * <p>The resource's URI must be specified explicitly. Resource metadata such as name, title,
+ * description, and MIME type can be specified via the corresponding attributes. If omitted, these
+ * metadata fields will default to the literal string "Not specified" and "text/plain".
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * @McpResource(uri = "weather://forecast/{city}/{date}")
+ * public String getWeather() {
+ *     // Method implementation...
+ * }
+ * }</pre>
+ *
+ * @see <a
+ *     href="https://modelcontextprotocol.io/docs/learn/server-concepts#core-server-features">MCP
+ *     Protocol Documentation</a>
+ * @author codeboyzhou
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpResource {
+  /** The URI of the resource. */
   String uri();
 
+  /** The name of the resource. Defaults to the name of the annotated method. */
   String name() default StringHelper.EMPTY;
 
+  /** The title of the resource. Defaults to the literal string "Not specified". */
   String title() default StringHelper.EMPTY;
 
+  /** The description of the resource. Defaults to the literal string "Not specified". */
   String description() default StringHelper.EMPTY;
 
+  /** The MIME type of the resource. Defaults to "text/plain". */
   String mimeType() default "text/plain";
 
+  /**
+   * The roles required to access the resource. Defaults to {@link McpSchema.Role#ASSISTANT} and
+   * {@link McpSchema.Role#USER}.
+   */
   McpSchema.Role[] roles() default {McpSchema.Role.ASSISTANT, McpSchema.Role.USER};
 
+  /** The priority of the resource. Defaults to 1.0. */
   double priority() default 1.0;
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpServerApplication.java

@@ -6,10 +6,35 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to mark a class as an MCP (Model Context Protocol) server application.
+ *
+ * <p>The base package for component scanning can be specified via the {@code basePackage}
+ * attribute. If not specified, the package of the annotated class will be used.
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * @McpServerApplication(basePackage = "com.example.mcp")
+ * public class MyMcpServerApplication {
+ *     // Application logic...
+ * }
+ * }</pre>
+ *
+ * @see <a href="https://modelcontextprotocol.io/docs/learn/server-concepts">MCP Protocol
+ *     Documentation</a>
+ * @author codeboyzhou
+ */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpServerApplication {
+  /** The base package for component scanning. Defaults to the package of the annotated class. */
   String basePackage() default StringHelper.EMPTY;
 
+  /**
+   * The base package class for component scanning. Defaults to {@link Object.class}.
+   *
+   * <p>Note: This attribute is intended to be used when the base package cannot be determined
+   * statically. In most cases, {@link #basePackage()} should be used instead.
+   */
   Class<?> basePackageClass() default Object.class;
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpTool.java

@@ -6,13 +6,35 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * This annotation is used to mark a method as an MCP (Model Context Protocol) tool method.
+ *
+ * <p>The tool's name defaults to the name of the annotated method. Tool metadata such as title and
+ * description can be specified via the corresponding attributes. If omitted, these metadata fields
+ * will default to the literal string "Not specified".
+ *
+ * @apiNote Example usage:
+ *     <pre>{@code
+ * @McpTool
+ * public String getWeather(String city) {
+ *     // Method implementation...
+ * }
+ * }</pre>
+ *
+ * @see <a
+ *     href="https://modelcontextprotocol.io/docs/learn/server-concepts#core-server-features">MCP
+ *     Protocol Documentation</a>
+ * @author codeboyzhou
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpTool {
-
+  /** The name of the tool. Defaults to the name of the annotated method. */
   String name() default StringHelper.EMPTY;
 
+  /** The title of the tool. Defaults to the literal string "Not specified". */
   String title() default StringHelper.EMPTY;
 
+  /** The description of the tool. Defaults to the literal string "Not specified". */
   String description() default StringHelper.EMPTY;
 }