fix(comment): Error generating Java docs

Author: codeboyzhou

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

@@ -21,8 +21,9 @@
 /**
  * This class is a singleton that provides methods to start MCP servers.
  *
- * @apiNote Example usage:
- *     <pre>{@code
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * McpServerInfo serverInfo = McpServerInfo.builder().build();
  * McpServers.run(MyApplication.class, args).startStdioServer(serverInfo);
  *

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

@@ -15,8 +15,9 @@
  *
  * <p>Note: This annotation is only applicable to the main class of the MCP server application.
  *
- * @apiNote Example usage:
- *     <pre>{@code
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpI18nEnabled
  * public class MyMcpServerApplication {
  *     // Application logic...

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

@@ -20,19 +20,26 @@
 @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. */
+  /**
+   * The name of the JSON schema property. If not specified, the field name will be used.
+   *
+   * @return the name of the JSON schema property
+   */
   String name() default StringHelper.EMPTY;
 
   /**
    * The description of the JSON schema property. If not specified, the default value {@code "Not
    * specified"} will be used.
+   *
+   * @return the description of the JSON schema property
    */
   String description() default StringHelper.EMPTY;
 
   /**
    * Whether the JSON schema property is required. If not specified, the default value {@code false}
    * will be used.
+   *
+   * @return whether the JSON schema property is required
    */
   boolean required() default false;
 }

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

@@ -13,8 +13,9 @@
  * 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
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpPrompt
  * public String getWeather(String city) {
  *     // Method implementation...
@@ -29,12 +30,24 @@
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpPrompt {
-  /** The name of the prompt. Defaults to the name of the annotated method. */
+  /**
+   * The name of the prompt. Defaults to the name of the annotated method.
+   *
+   * @return the name of the prompt
+   */
   String name() default StringHelper.EMPTY;
 
-  /** The title of the prompt. Defaults to the literal string "Not specified". */
+  /**
+   * The title of the prompt. Defaults to the literal string "Not specified".
+   *
+   * @return the title of the prompt
+   */
   String title() default StringHelper.EMPTY;
 
-  /** The description of the prompt. Defaults to the literal string "Not specified". */
+  /**
+   * The description of the prompt. Defaults to the literal string "Not specified".
+   *
+   * @return the description of the prompt
+   */
   String description() default StringHelper.EMPTY;
 }

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

@@ -14,8 +14,9 @@
  * 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
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpPrompt
  * public String getWeather(@McpPromptParam(name = "city") String city) {
  *     // Method implementation...
@@ -30,15 +31,31 @@
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpPromptParam {
-  /** The name of the prompt parameter. */
+  /**
+   * The name of the prompt parameter.
+   *
+   * @return the name of the prompt parameter
+   */
   String name();
 
-  /** The title of the prompt parameter. Defaults to the literal string "Not specified". */
+  /**
+   * The title of the prompt parameter. Defaults to the literal string "Not specified".
+   *
+   * @return the title of the prompt parameter
+   */
   String title() default StringHelper.EMPTY;
 
-  /** The description of the prompt parameter. Defaults to the literal string "Not specified". */
+  /**
+   * The description of the prompt parameter. Defaults to the literal string "Not specified".
+   *
+   * @return the description of the prompt parameter
+   */
   String description() default StringHelper.EMPTY;
 
-  /** Whether the prompt parameter is required. Defaults to {@code false}. */
+  /**
+   * Whether the prompt parameter is required. Defaults to {@code false}.
+   *
+   * @return whether the prompt parameter is required
+   */
   boolean required() default false;
 }

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

@@ -14,8 +14,9 @@
  * 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
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpResource(uri = "weather://forecast/{city}/{date}")
  * public String getWeather() {
  *     // Method implementation...
@@ -30,27 +31,53 @@
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpResource {
-  /** The URI of the resource. */
+  /**
+   * The URI of the resource.
+   *
+   * @return the URI of the resource
+   */
   String uri();
 
-  /** The name of the resource. Defaults to the name of the annotated method. */
+  /**
+   * The name of the resource. Defaults to the name of the annotated method.
+   *
+   * @return the name of the resource
+   */
   String name() default StringHelper.EMPTY;
 
-  /** The title of the resource. Defaults to the literal string "Not specified". */
+  /**
+   * The title of the resource. Defaults to the literal string "Not specified".
+   *
+   * @return the title of the resource
+   */
   String title() default StringHelper.EMPTY;
 
-  /** The description of the resource. Defaults to the literal string "Not specified". */
+  /**
+   * The description of the resource. Defaults to the literal string "Not specified".
+   *
+   * @return the description of the resource
+   */
   String description() default StringHelper.EMPTY;
 
-  /** The MIME type of the resource. Defaults to "text/plain". */
+  /**
+   * The MIME type of the resource. Defaults to "text/plain".
+   *
+   * @return the MIME type of the resource
+   */
   String mimeType() default "text/plain";
 
   /**
    * The roles required to access the resource. Defaults to {@link McpSchema.Role#ASSISTANT} and
    * {@link McpSchema.Role#USER}.
+   *
+   * @return the roles required to access the resource
    */
   McpSchema.Role[] roles() default {McpSchema.Role.ASSISTANT, McpSchema.Role.USER};
 
-  /** The priority of the resource. Defaults to 1.0. */
+  /**
+   * The priority of the resource. Defaults to 1.0.
+   *
+   * @return the priority of the resource
+   */
   double priority() default 1.0;
 }

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

@@ -12,8 +12,9 @@
  * <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
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpServerApplication(basePackage = "com.example.mcp")
  * public class MyMcpServerApplication {
  *     // Application logic...
@@ -27,14 +28,20 @@
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpServerApplication {
-  /** The base package for component scanning. Defaults to the package of the annotated class. */
+  /**
+   * The base package for component scanning. Defaults to the package of the annotated class.
+   *
+   * @return the base package for component scanning
+   */
   String basePackage() default StringHelper.EMPTY;
 
   /**
-   * The base package class for component scanning. Defaults to {@link Object.class}.
+   * The base package class for component scanning. Defaults to {@code 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.
+   *
+   * @return the base package class for component scanning
    */
   Class<?> basePackageClass() default Object.class;
 }

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

@@ -13,8 +13,9 @@
  * 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
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpTool
  * public String getWeather(String city) {
  *     // Method implementation...
@@ -29,12 +30,24 @@
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpTool {
-  /** The name of the tool. Defaults to the name of the annotated method. */
+  /**
+   * The name of the tool. Defaults to the name of the annotated method.
+   *
+   * @return the name of the tool
+   */
   String name() default StringHelper.EMPTY;
 
-  /** The title of the tool. Defaults to the literal string "Not specified". */
+  /**
+   * The title of the tool. Defaults to the literal string "Not specified".
+   *
+   * @return the title of the tool
+   */
   String title() default StringHelper.EMPTY;
 
-  /** The description of the tool. Defaults to the literal string "Not specified". */
+  /**
+   * The description of the tool. Defaults to the literal string "Not specified".
+   *
+   * @return the description of the tool
+   */
   String description() default StringHelper.EMPTY;
 }

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

@@ -14,8 +14,9 @@
  * required status 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
+ * <p>Example usage:
+ *
+ * <pre>{@code
  * @McpTool
  * public String getWeather(@McpToolParam(name = "city") String city) {
  *     // Method implementation...
@@ -27,12 +28,24 @@
 @Target(ElementType.PARAMETER)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface McpToolParam {
-  /** The name of the tool parameter. */
+  /**
+   * The name of the tool parameter.
+   *
+   * @return the name of the tool parameter
+   */
   String name();
 
-  /** The description of the tool parameter. Defaults to the literal string "Not specified". */
+  /**
+   * The description of the tool parameter. Defaults to the literal string "Not specified".
+   *
+   * @return the description of the tool parameter
+   */
   String description() default StringHelper.EMPTY;
 
-  /** Whether the tool parameter is required. Defaults to {@code false}. */
+  /**
+   * Whether the tool parameter is required. Defaults to {@code false}.
+   *
+   * @return whether the tool parameter is required
+   */
   boolean required() default false;
 }

src/main/java/com/github/codeboyzhou/mcp/declarative/common/Immutable.java

@@ -13,6 +13,7 @@ public record Immutable<T>(T value) {
    * Creates a new instance of {@code Immutable} with the specified value.
    *
    * @param value the value to be wrapped
+   * @param <T> the type of the value
    * @return a new instance of {@code Immutable} with the specified value
    */
   public static <T> Immutable<T> of(T value) {