#704 - Update javadoc for @Cache and @Query.setUseCache()

src/main/java/com/avaje/ebean/Query.java

@@ -1304,10 +1304,16 @@ public interface Query<T> {
   Query<T> setMapKey(String mapKey);
 
   /**
-   * Set this to true to use the bean cache.
+   * Set this to false to not use the bean cache.
    * <p>
-   * If the query result is in cache then by default this same instance is
-   * returned. In this sense it should be treated as a read only object graph.
+   * By default "find by id" and "find by natural key" will use the bean cache
+   * when bean caching is enabled. Setting this to false means that the query
+   * will not use the bean cache and instead hit the database.
+   * </p>
+   * <p>
+   * In the case of other queries (findList(), findEach() etc) then setting this to
+   * false beans that the if lazy loading is invoked that lazy loading will not try
+   * to use the bean cache.
    * </p>
    */
   Query<T> setUseCache(boolean useCache);

src/main/java/com/avaje/ebean/annotation/Cache.java

@@ -28,6 +28,11 @@ public @interface Cache {
    * set this to false on a bean type that we want to use query caching but no
    * bean caching (and this is expected to be a rare case).
    * </p>
+   * <p>
+   * When bean caching is enabled by default "find by id" and "find by unique natural key"
+   * queries will try to use the bean cache. We use {@link com.avaje.ebean.Query#setUseCache(boolean)}
+   * with <code>false</code> for the case when we do NOT want to use the bean cache.
+   * </p>
    */
   boolean enableBeanCache() default true;