Merge pull request #1333 from querydsl/collections-javadocs

Improve javadocs for querydsl-collections

querydsl-collections/src/main/java/com/querydsl/collections/AbstractCollQuery.java

@@ -25,8 +25,7 @@ import com.querydsl.core.support.FetchableQueryBase;
 import com.querydsl.core.types.*;
 
 /**
- * AbstractCollQuery provides a base class for Collection query implementations.
- *
+ * {@code AbstractCollQuery} provides a base class for {@link Collection} query implementations.
  *
  * @see CollQuery
  *
@@ -72,10 +71,10 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
     /**
      * Add a query source
      *
-     * @param <A>
+     * @param <A> type of expression
      * @param entity Path for the source
      * @param col content of the source
-     * @return
+     * @return current object
      */
     public <A> Q from(Path<A> entity, Iterable<? extends A> col) {
         iterables.put(entity, col);
@@ -86,10 +85,10 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
     /**
      * Bind the given collection to an already existing query source
      *
-     * @param <A>
+     * @param <A> type of expression
      * @param entity Path for the source
      * @param col content of the source
-     * @return
+     * @return current object
      */
     public <A> Q bind(Path<A> entity, Iterable<? extends A> col) {
         iterables.put(entity, col);
@@ -123,10 +122,10 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
     /**
      * Define an inner join from the Collection typed path to the alias
      *
-     * @param <P>
-     * @param target
-     * @param alias
-     * @return
+     * @param <P> type of expression
+     * @param target target of the join
+     * @param alias alias for the join target
+     * @return current object
      */
     public <P> Q innerJoin(Path<? extends Collection<P>> target, Path<P> alias) {
         getMetadata().addJoin(JoinType.INNERJOIN, createAlias(target, alias));
@@ -136,10 +135,10 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
     /**
      * Define an inner join from the Map typed path to the alias
      *
-     * @param <P>
-     * @param target
-     * @param alias
-     * @return
+     * @param <P> type of expression
+     * @param target target of the join
+     * @param alias alias for the join target
+     * @return current object
      */
     public <P> Q innerJoin(MapExpression<?,P> target, Path<P> alias) {
         getMetadata().addJoin(JoinType.INNERJOIN, createAlias(target, alias));
@@ -149,10 +148,10 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
     /**
      * Define a left join from the Collection typed path to the alias
      *
-     * @param <P>
-     * @param target
-     * @param alias
-     * @return
+     * @param <P> type of expression
+     * @param target target of the join
+     * @param alias alias for the join target
+     * @return current object
      */
     public <P> Q leftJoin(Path<? extends Collection<P>> target, Path<P> alias) {
         getMetadata().addJoin(JoinType.LEFTJOIN, createAlias(target, alias));
@@ -162,10 +161,10 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
     /**
      * Define a left join from the Map typed path to the alias
      *
-     * @param <P>
-     * @param target
-     * @param alias
-     * @return
+     * @param <P> type of expression
+     * @param target target of the join
+     * @param alias alias for the joint target
+     * @return current object
      */
     public <P> Q leftJoin(MapExpression<?,P> target, Path<P> alias) {
         getMetadata().addJoin(JoinType.LEFTJOIN, createAlias(target, alias));
@@ -204,7 +203,6 @@ public abstract class AbstractCollQuery<T, Q extends AbstractCollQuery<T, Q>> ex
             reset();
             return QueryResults.<T>emptyResults();
         }
-
     }
 
     @Override

querydsl-collections/src/main/java/com/querydsl/collections/CollDeleteClause.java

@@ -20,7 +20,7 @@ import com.querydsl.core.types.Path;
 import com.querydsl.core.types.Predicate;
 
 /**
- * CollDeleteClause is an implementation of the {@link DeleteClause} interface for the Querydsl 
+ * {@code CollDeleteClause} is an implementation of the {@link DeleteClause} interface for the Querydsl
  * Collections module
  *
  * @author tiwe
@@ -31,13 +31,10 @@ public class CollDeleteClause<T> implements DeleteClause<CollDeleteClause<T>> {
 
     private final Collection<? extends T> col;
 
-    private final Path<T> expr;
-
     private final CollQuery<T> query;
 
     public CollDeleteClause(QueryEngine qe, Path<T> expr, Collection<? extends T> col) {
         this.query = new CollQuery<Void>(qe).from(expr, col).select(expr);
-        this.expr = expr;
         this.col = col;
     }
 

querydsl-collections/src/main/java/com/querydsl/collections/CollQuery.java

@@ -17,7 +17,7 @@ import com.querydsl.core.*;
 import com.querydsl.core.types.Expression;
 
 /**
- * CollQuery is the default implementation of the {@link SimpleQuery} interface for collections
+ * {@code CollQuery} is the default implementation of the {@link FetchableQuery} interface for collections
  *
  * @author tiwe
  *
@@ -34,7 +34,7 @@ public class CollQuery<T> extends AbstractCollQuery<T, CollQuery<T>> implements
     /**
      * Creates a new CollQuery instance
      * 
-     * @param templates
+     * @param templates serialization templates
      */
     public CollQuery(CollQueryTemplates templates) {
         this(new DefaultQueryEngine(new DefaultEvaluatorFactory(templates)));
@@ -43,7 +43,7 @@ public class CollQuery<T> extends AbstractCollQuery<T, CollQuery<T>> implements
     /**
      * Create a new CollQuery instance
      *
-     * @param queryEngine
+     * @param queryEngine query engine for query execution
      */
     public CollQuery(QueryEngine queryEngine) {
         super(new DefaultQueryMetadata(), queryEngine);
@@ -53,7 +53,7 @@ public class CollQuery<T> extends AbstractCollQuery<T, CollQuery<T>> implements
     /**
      * Create a new CollQuery instance
      *
-     * @param metadata
+     * @param metadata query metadata
      */
     public CollQuery(QueryMetadata metadata) {
         super(metadata, DefaultQueryEngine.getDefault());
@@ -62,8 +62,8 @@ public class CollQuery<T> extends AbstractCollQuery<T, CollQuery<T>> implements
     /**
      * Create a new CollQuery instance
      *
-     * @param metadata
-     * @param queryEngine
+     * @param metadata query metadata
+     * @param queryEngine query engine for query execution
      */
     public CollQuery(QueryMetadata metadata, QueryEngine queryEngine) {
         super(metadata, queryEngine);

querydsl-collections/src/main/java/com/querydsl/collections/CollQueryFactory.java

@@ -20,7 +20,7 @@ import com.querydsl.core.alias.Alias;
 import com.querydsl.core.types.Path;
 
 /**
- * CollQueryFactory provides static convenience methods for query construction
+ * {@code CollQueryFactory} provides static convenience methods for query construction
  *
  * @author tiwe
  */
@@ -31,7 +31,7 @@ public final class CollQueryFactory {
      * 
      * @param path source expression
      * @param col source collection
-     * @return
+     * @return delete clause
      */
     public static <A> CollDeleteClause<A> delete(Path<A> path, Collection<A> col) {
         return new CollDeleteClause<A>(path, col);
@@ -42,7 +42,7 @@ public final class CollQueryFactory {
      * 
      * @param alias source alias
      * @param col source collection
-     * @return
+     * @return query
      */
     public static <A> CollQuery<A> from(A alias, Iterable<A> col) {
         Path<A> expr = Alias.$(alias);
@@ -54,7 +54,7 @@ public final class CollQueryFactory {
      * 
      * @param path source expression
      * @param arr source array
-     * @return
+     * @return query
      */
     public static <A> CollQuery<A> from(Path<A> path, A... arr) {
         return new CollQuery<Void>().from(path, ImmutableList.copyOf(arr)).select(path);
@@ -65,7 +65,7 @@ public final class CollQueryFactory {
      * 
      * @param path source expression
      * @param col source collection
-     * @return
+     * @return query
      */
     public static <A> CollQuery<A> from(Path<A> path, Iterable<A> col) {
         return new CollQuery<Void>().from(path, col).select(path);
@@ -76,7 +76,7 @@ public final class CollQueryFactory {
      * 
      * @param path source expression
      * @param col source collection
-     * @return
+     * @return query
      */
     public static <A> CollUpdateClause<A> update(Path<A> path, Iterable<A> col) {
         return new CollUpdateClause<A>(path, col);

querydsl-collections/src/main/java/com/querydsl/collections/CollQueryFunctions.java

@@ -27,7 +27,7 @@ import com.querydsl.core.util.MathUtils;
 import com.querydsl.core.util.ReflectionUtils;
 
 /**
- * CollQueryFunctions defines function implementation for use in ColQueryTemplates
+ * {@code CollQueryFunctions} defines function implementation for use in ColQueryTemplates
  *
  * @author tiwe
  *

querydsl-collections/src/main/java/com/querydsl/collections/CollQueryMixin.java

@@ -22,7 +22,7 @@ import com.querydsl.core.types.Predicate;
 import com.querydsl.core.types.dsl.Expressions;
 
 /**
- * CollQueryMixin extends {@link QueryMixin} to provide normalization logic specific to this module
+ * {@code CollQueryMixin} extends {@link QueryMixin} to provide normalization logic specific to this module
  *
  * @author tiwe
  *

querydsl-collections/src/main/java/com/querydsl/collections/CollQuerySerializer.java

@@ -42,7 +42,7 @@ import com.querydsl.core.types.SubQueryExpression;
 import com.querydsl.core.types.Template;
 
 /**
- * CollQuerySerializer is a {@link Serializer} implementation for the Java language
+ * {@code CollQuerySerializer} is a {@link Serializer} implementation for the Java language
  *
  * @author tiwe
  */

querydsl-collections/src/main/java/com/querydsl/collections/CollQueryTemplates.java

@@ -18,7 +18,7 @@ import com.querydsl.core.types.Ops;
 import com.querydsl.core.types.PathType;
 
 /**
- * CollQueryTemplates extends {@link JavaTemplates} to add module specific operation
+ * {@code CollQueryTemplates} extends {@link JavaTemplates} to add module specific operation
  * templates.
  *
  * @author tiwe

querydsl-collections/src/main/java/com/querydsl/collections/CollUpdateClause.java

@@ -24,7 +24,7 @@ import com.querydsl.core.types.Predicate;
 import com.querydsl.core.util.BeanMap;
 
 /**
- * CollUpdateClause is an implementation of the UpdateClause interface for Querydsl Collections
+ * {@code CollUpdateClause} is an implementation of the {@link UpdateClause} interface for Querydsl Collections
  *
  * @author tiwe
  *
@@ -32,15 +32,12 @@ import com.querydsl.core.util.BeanMap;
  */
 public class CollUpdateClause<T> implements UpdateClause<CollUpdateClause<T>> {
 
-    private final Path<T> expr;
-
     private final Map<Path<?>, Object> paths = new HashMap<Path<?>, Object>();
 
     private final CollQuery<T> query;
 
     public CollUpdateClause(QueryEngine qe, Path<T> expr, Iterable<? extends T> col) {
         this.query = new CollQuery<Void>(qe).from(expr, col).select(expr);
-        this.expr = expr;
     }
 
     public CollUpdateClause(Path<T> expr, Iterable<? extends T> col) {

querydsl-collections/src/main/java/com/querydsl/collections/DefaultEvaluatorFactory.java

@@ -43,7 +43,7 @@ import com.querydsl.core.types.ParamNotSetException;
 import com.querydsl.core.types.Predicate;
 
 /**
- * DefaultEvaluatorFactory provides Java source templates for evaluation of CollQuery queries
+ * {@code DefaultEvaluatorFactory} provides Java source templates for evaluation of {@link CollQuery} queries
  *
  * @author tiwe
  *
@@ -86,9 +86,10 @@ public class DefaultEvaluatorFactory {
      * Create an Evaluator for the given query sources and projection
      *
      * @param <T>
-     * @param sources
-     * @param projection
-     * @return
+     * @param metadata query metadata
+     * @param sources sources of the query
+     * @param projection projection of the query
+     * @return evaluator
      */
     public <T> Evaluator<T> create(QueryMetadata metadata, List<? extends Expression<?>> sources,
             Expression<T> projection) {
@@ -129,9 +130,9 @@ public class DefaultEvaluatorFactory {
      * Create an Evaluator for the given source and filter
      *
      * @param <T>
-     * @param source
-     * @param filter
-     * @return
+     * @param source source of the query
+     * @param filter filter of the query
+     * @return evaluator
      */
     public <T> Evaluator<List<T>> createEvaluator(QueryMetadata metadata,
             Expression<? extends T> source, Predicate filter) {
@@ -165,9 +166,10 @@ public class DefaultEvaluatorFactory {
     /**
      * Create an Evaluator for the given sources and the given optional filter
      *
-     * @param joins
-     * @param filter
-     * @return
+     * @param metadata query metadata
+     * @param joins joins
+     * @param filter where condition
+     * @return evaluator
      */
     public Evaluator<List<Object[]>> createEvaluator(QueryMetadata metadata,
             List<JoinExpression> joins, @Nullable Predicate filter) {

querydsl-collections/src/main/java/com/querydsl/collections/EvaluatorFunction.java

@@ -34,7 +34,7 @@ public class EvaluatorFunction<S, T> implements Function<S, T> {
         if (input.getClass().isArray()) {
             return ev.evaluate((Object[]) input);
         } else {
-            return ev.evaluate(new Object[]{input});
+            return ev.evaluate(input);
         }
     }
 }

querydsl-collections/src/main/java/com/querydsl/collections/GuavaHelpers.java

@@ -24,7 +24,7 @@ import com.querydsl.core.types.PathExtractor;
 import com.querydsl.core.types.Predicate;
 
 /**
- * GuavaHelpers provides functionality to wrap Querydsl {@link Predicate} instances to Guava predicates
+ * {@code GuavaHelpers} provides functionality to wrap Querydsl {@link Predicate} instances to Guava predicates
  * and Querydsl {@link Expression} instances to Guava functions 
  * 
  * @author tiwe
@@ -38,8 +38,8 @@ public final class GuavaHelpers {
     /**
      * Wrap a Querydsl predicate into a Guava predicate
      * 
-     * @param predicate
-     * @return
+     * @param predicate predicate to wrapped
+     * @return Guava predicate
      */
     public static <T> com.google.common.base.Predicate<T> wrap(Predicate predicate) {        
         Path<?> path = predicate.accept(PathExtractor.DEFAULT, null);
@@ -59,8 +59,8 @@ public final class GuavaHelpers {
     /**
      * Wrap a Querydsl expression into a Guava function
      * 
-     * @param projection
-     * @return
+     * @param projection projection to wrap
+     * @return Guava function
      */
     public static <F,T> Function<F,T> wrap(Expression<T> projection) {        
         Path<?> path = projection.accept(PathExtractor.DEFAULT, null);

querydsl-collections/src/main/java/com/querydsl/collections/MultiComparator.java

@@ -20,7 +20,7 @@ import com.mysema.codegen.Evaluator;
 import com.querydsl.core.util.NullSafeComparableComparator;
 
 /**
- * MultiComparator compares arrays
+ * {@code MultiComparator} compares arrays
  *
  * @author tiwe
  */

querydsl-collections/src/main/java/com/querydsl/collections/QueryEngine.java

@@ -20,7 +20,7 @@ import com.querydsl.core.QueryMetadata;
 import com.querydsl.core.types.Expression;
 
 /**
- * QueryEngine defines an interface for the evaluation of ColQuery queries
+ * {@code QueryEngine} defines an interface for the evaluation of ColQuery queries
  *
  * @author tiwe
  *
@@ -30,26 +30,28 @@ public interface QueryEngine {
     /**
      * Evaluate the given query and return the count of matched rows
      *
-     * @param metadata
-     * @param iterables
-     * @return
+     * @param metadata query metadata
+     * @param iterables source contents
+     * @return matching row count
      */
     long count(QueryMetadata metadata, Map<Expression<?>, Iterable<?>> iterables);
 
     /**
      * Evaluate the given query and return the projection as a list
      *
-     * @param metadata
-     * @param iterables
-     * @return
+     * @param metadata query metadata
+     * @param iterables source contents
+     * @return matching rows
      */
     <T> List<T> list(QueryMetadata metadata, Map<Expression<?>, Iterable<?>> iterables, 
             Expression<T> projection);
 
     /**
-     * @param metadata
-     * @param iterables
-     * @return
+     * Evaluate the given query return whether rows where matched
+     *
+     * @param metadata query metadata
+     * @param iterables source contents
+     * @return true, if at least one row was matched
      */
     boolean exists(QueryMetadata metadata, Map<Expression<?>, Iterable<?>> iterables);