Merge pull request mybatis#1697 from kazuki43zoo/improve-javadoc-for-…

…annotations

Improve JavaDoc for annotations

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

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

@@ -24,6 +24,22 @@
 /**
  * The annotation that specify a method that provide an SQL for inserting record(s).
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *
+ *   &#064;InsertProvider(type = SqlProvider.class, method = "insert")
+ *   void insert(User user);
+ *
+ *   public static class SqlProvider {
+ *     public static String insert() {
+ *       return "INSERT INTO users (id, name) VALUES(#{id}, #{name})";
+ *     }
+ *   }
+ *
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

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

@@ -26,6 +26,15 @@
 /**
  * The annotation that specify a {@link LanguageDriver} to use.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Lang(MyXMLLanguageDriver.class)
+ *   &#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/Many.java

@@ -25,6 +25,8 @@
 /**
  * The annotation that specify the nested statement for retrieving collections.
  *
+ * @see Result
+ * @see Results
  * @author Clinton Begin
  */
 @Documented

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

@@ -24,6 +24,15 @@
 /**
  * The annotation that specify the property name(or column name) for a key value of {@link java.util.Map}.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;MapKey("id")
+ *   &#064;Select("SELECT id, name FROM users WHERE name LIKE #{name} || '%")
+ *   Map&lt;Integer, User&gt; selectByStartingWithName(String name);
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

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

@@ -23,8 +23,16 @@
 import java.lang.annotation.Target;
 
 /**
- * Marker interface for MyBatis mappers
+ * Marker interface for MyBatis mappers.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * &#064;Mapper
+ * public interface UserMapper {
+ *   // ...
+ * }
+ * </pre>
  * @author Frank David Martínez
  */
 @Documented

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

@@ -25,6 +25,8 @@
 /**
  * The annotation that specify the nested statement for retrieving single object.
  *
+ * @see Result
+ * @see Results
  * @author Clinton Begin
  */
 @Documented

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

@@ -27,6 +27,15 @@
 /**
  * The annotation that specify options for customizing default behaviors.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Option(useGeneratedKeys = true, keyProperty = "id")
+ *   &#064;Insert("INSERT INTO users (name) VALUES(#{name})")
+ *   boolean insert(User user);
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

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

@@ -24,6 +24,14 @@
 /**
  * The annotation that specify the parameter name.
  *
+ * <p><br>
+ * <b>How to use:</b>
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Select("SELECT id, name FROM users WHERE name = #{name}")
+ *   User selectById(&#064;Param("name") String value);
+ * }
+ * </pre>
  * @author Clinton Begin
  */
 @Documented

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

@@ -33,12 +33,16 @@
 public @interface Property {
 
   /**
-   * A target property name.
+   * Returns the property name.
+   *
+   * @return the property name
    */
   String name();
 
   /**
-   * A property value or placeholder.
+   * Returns the property value or placeholder.
+   *
+   * @return the property value or placeholder
    */
   String value();
-}
+}

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

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

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

@@ -24,6 +24,31 @@
 /**
  * The annotation that specify result map names to use.
  *
+ * <p><br>
+ * <b>How to use:</b><br>
+ * Mapper interface:
+ * <pre>
+ * public interface UserMapper {
+ *   &#064;Select("SELECT id, name FROM users WHERE id = #{id}")
+ *   &#064;ResultMap("userMap")
+ *   User selectById(int id);
+ *
+ *   &#064;Select("SELECT u.id, u.name FROM users u INNER JOIN users_email ue ON u.id = ue.id WHERE ue.email = #{email}")
+ *   &#064;ResultMap("userMap")
+ *   User selectByEmail(String email);
+ * }
+ * </pre>
+ * Mapper XML:
+ * <pre>{@code
+ * <mapper namespace="com.example.mapper.UserMapper">
+ *   <resultMap id="userMap" type="com.example.model.User">
+ *     <id property="id" column="id" />
+ *     <result property="name" column="name" />
+ *     <association property="email" select="selectUserEmailById" column="id" fetchType="lazy"/>
+ *   </resultMap>
+ * </mapper>
+ * }
+ * </pre>
  * @author Jeff Butler
  */
 @Documented