Improve JavaDoc for annotations

Author: kazuki43zoo

src/main/java/org/apache/ibatis/annotations/Arg.java

@@ -27,6 +27,7 @@
 /**
  * The annotation that specify a mapping definition for the constructor argument.
  *
+ * @see ConstructorArgs
  * @author Clinton Begin
  */
 @Documented

src/main/java/org/apache/ibatis/annotations/AutomapConstructor.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2017 the original author or authors.
+ *    Copyright 2009-2019 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -24,6 +24,26 @@
 /**
  * The marker annotation that indicate a constructor for automatic mapping.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public class User {
+ *
+ *   private int id;
+ *   private String name;
+ *
+ *   public User(int id) {
+ *     this.id = id;
+ *   }
+ *
+ *   &#064;AutomapConstructor
+ *   public User(int id, String name) {
+ *     this.id = id;
+ *     this.name = name;
+ *   }
+ *   // ...
+ * }
+ * </pre>
  * @author Tim Chen
  * @since 3.4.3
  */

src/main/java/org/apache/ibatis/annotations/CacheNamespace.java

@@ -28,6 +28,18 @@
 /**
  * The annotation that specify to use cache on namespace(e.g. mapper interface).
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * &#064;acheNamespace(implementation = CustomCache.class, properties = {
+ *   &#064;Property(name = "host", value = "${mybatis.cache.host}"),
+ *   &#064;Property(name = "port", value = "${mybatis.cache.port}"),
+ *   &#064;Property(name = "name", value = "usersCache")
+ * })
+ * public interface UserMapper {
+ *   // ...
+ * }
+ * </pre>
  * @author Clinton Begin
  * @author Kazuki Shimizu
  */

src/main/java/org/apache/ibatis/annotations/CacheNamespaceRef.java

@@ -23,9 +23,17 @@
 
 /**
  * The annotation that reference a cache.
- * <p>
- * If you use this annotation, should be specified either {@link #value()} or {@link #name()} attribute.
- * </p>
+ *
+ * <p>If you use this annotation, should be specified either {@link #value()} or {@link #name()} attribute.
+ *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * &#064;CacheNamespaceRef(UserMapper.class)
+ * public interface AdminUserMapper {
+ *   // ...
+ * }
+ * </pre>
  * @author Clinton Begin
  * @author Kazuki Shimizu
  */
@@ -35,12 +43,16 @@
 public @interface CacheNamespaceRef {
 
   /**
-   * A namespace type to reference a cache (the namespace name become a FQCN of specified type).
+   * Returns the namespace type to reference a cache (the namespace name become a FQCN of specified type).
+   *
+   * @return the namespace type to reference a cache
    */
   Class<?> value() default void.class;
 
   /**
-   * A namespace name to reference a cache.
+   * Returns the namespace name to reference a cache.
+   *
+   * @return the namespace name
    * @since 3.4.2
    */
   String name() default "";

src/main/java/org/apache/ibatis/annotations/Case.java

@@ -23,6 +23,11 @@
 /**
  * The annotation that conditional mapping definition for {@link TypeDiscriminator}.
  *
+ * @see TypeDiscriminator
+ * @see Result
+ * @see Arg
+ * @see Results
+ * @see ConstructorArgs
  * @author Clinton Begin
  */
 @Documented

src/main/java/org/apache/ibatis/annotations/ConstructorArgs.java

@@ -24,6 +24,19 @@
 /**
  * The annotation that be grouping mapping definitions for constructor.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;ConstructorArgs({
+ *     &#064;Arg(column = "id", javaType = int.class, id = true),
+ *     &#064;Arg(column = "name", javaType = String.class),
+ *     &#064;Arg(javaType = UserEmail.class, select = "selectUserEmailById", column = "id")
+ *   })
+ *   &#064;Select("SELECT id, name FROM users WHERE id = #{id}")
+ *   User selectById(int id);
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

src/main/java/org/apache/ibatis/annotations/Delete.java

@@ -24,6 +24,14 @@
 /**
  * The annotation that specify an SQL for deleting record(s).
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Delete("DELETE FROM users WHERE id = #{id}")
+ *   boolean deleteById(int id);
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

src/main/java/org/apache/ibatis/annotations/DeleteProvider.java

@@ -24,6 +24,22 @@
 /**
  * The annotation that specify a method that provide an SQL for deleting record(s).
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *
+ *   &#064;DeleteProvider(type = SqlProvider.class, method = "deleteById")
+ *   boolean deleteById(int id);
+ *
+ *   public static class SqlProvider {
+ *     public static String deleteById() {
+ *       return "DELETE FROM users WHERE id = #{id}";
+ *     }
+ *   }
+ *
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

src/main/java/org/apache/ibatis/annotations/Flush.java

@@ -1,5 +1,5 @@
 /**
- *    Copyright 2009-2016 the original author or authors.
+ *    Copyright 2009-2019 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -24,6 +24,14 @@
 /**
  * The maker annotation that invoke a flush statements via Mapper interface.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Flush
+ *   List&lt;BatchResult&gt; flush();
+ * }
+ * </pre>
  * @since 3.3.0
  * @author Kazuki Shimizu
  */

src/main/java/org/apache/ibatis/annotations/Insert.java

@@ -24,6 +24,14 @@
 /**
  * The annotation that specify an SQL for inserting record(s).
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Insert("INSERT INTO users (id, name) VALUES(#{id}, #{name})")
+ *   void insert(User user);
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented