Merge pull request #1339 from querydsl/jdo-javadocs

Improve javadocs for querydsl-jdo

querydsl-jdo/src/main/java/com/querydsl/jdo/AbstractJDOQuery.java

@@ -18,6 +18,7 @@ import java.io.IOException;
 import java.util.*;
 
 import javax.annotation.Nullable;
+import javax.jdo.JDOUserException;
 import javax.jdo.PersistenceManager;
 import javax.jdo.Query;
 
@@ -31,14 +32,14 @@ import com.mysema.commons.lang.IteratorAdapter;
 import com.querydsl.core.*;
 import com.querydsl.core.support.FetchableSubQueryBase;
 import com.querydsl.core.types.*;
-import com.querydsl.core.types.dsl.CollectionPath;
 
 /**
- * Abstract base class for custom implementations of the JDOCommonQuery interface.
+ * Abstract base class for custom implementations of the {@link JDOQLQuery} interface.
  *
  * @author tiwe
  *
- * @param <Q>
+ * @param <T> result type
+ * @param <Q> concrete subclass
  */
 public abstract class AbstractJDOQuery<T, Q extends AbstractJDOQuery<T, Q>> extends FetchableSubQueryBase<T, Q> implements JDOQLQuery<T> {
 
@@ -89,8 +90,8 @@ public abstract class AbstractJDOQuery<T, Q extends AbstractJDOQuery<T, Q>> exte
     /**
      * Add the fetch group to the set of active fetch groups.
      *
-     * @param fetchGroupName
-     * @return
+     * @param fetchGroupName fetch group name
+     * @return the current object
      */
     @Override
     public Q addFetchGroup(String fetchGroupName) {
@@ -278,13 +279,13 @@ public abstract class AbstractJDOQuery<T, Q extends AbstractJDOQuery<T, Q>> exte
 
     /**
      * Set the maximum fetch depth when fetching.
-     * A value of 0 has no meaning and will throw a JDOUserException.
+     * A value of 0 has no meaning and will throw a {@link JDOUserException}.
      * A value of -1 means that no limit is placed on fetching.
      * A positive integer will result in that number of references from the
      * initial object to be fetched.
      *
-     * @param depth
-     * @return
+     * @param depth fetch depth
+     * @return the current object
      */
     @Override
     public Q setMaxFetchDepth(int depth) {

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOExpressions.java

@@ -24,70 +24,72 @@ import com.querydsl.core.types.dsl.Expressions;
 public final class JDOExpressions {
 
     /**
-     * Create a new detached JDOQuery instance with the given projection
+     * Create a new detached {@link JDOQuery} instance with the given projection
      *
-     * @param expr
+     * @param expr projection
      * @param <T>
-     * @return
+     * @return select(expr)
      */
     public static <T> JDOQuery<T> select(Expression<T> expr) {
         return new JDOQuery<Void>().select(expr);
     }
 
     /**
-     * Create a new detached JDOQuery instance with the given projection
+     * Create a new detached {@link JDOQuery} instance with the given projection
      *
-     * @param exprs
-     * @return
+     * @param exprs projection
+     * @return select(exprs)
      */
     public static JDOQuery<Tuple> select(Expression<?>... exprs) {
         return new JDOQuery<Void>().select(exprs);
     }
 
     /**
-     * Create a new detached JDOQuery instance with the given projection
+     * Create a new detached {@link JDOQuery} instance with the given projection
      *
-     * @param expr
+     * @param expr projection
      * @param <T>
-     * @return
+     * @return select(distinct expr)
      */
     public static <T> JDOQuery<T> selectDistinct(Expression<T> expr) {
-        return new JDOQuery<Void>().select(expr).distinct();
+        return select(expr).distinct();
     }
 
     /**
-     * Create a new detached JDOQuery instance with the given projection
+     * Create a new detached {@link JDOQuery} instance with the given projection
      *
-     * @param exprs
-     * @return
+     * @param exprs projection
+     * @return select(distinct exprs)
      */
     public static JDOQuery<Tuple> selectDistinct(Expression<?>... exprs) {
-        return new JDOQuery<Void>().select(exprs).distinct();
+        return select(exprs).distinct();
     }
 
 
     /**
+     * Create a new detached {@link JDOQuery} instance with the given projection 0
      *
-     * @return
+     * @return select(0)
      */
     public static JDOQuery<Integer> selectZero() {
         return select(Expressions.ZERO);
     }
 
     /**
+     * Create a new detached {@link JDOQuery} instance with the projection 1
      *
-     * @return
+     * @return select(1)
      */
     public static JDOQuery<Integer> selectOne() {
         return select(Expressions.ONE);
     }
 
     /**
-     * Create a new detached JDOQuery instance with the given projection
+     * Create a new detached {@link JDOQuery} instance with the given projection
      *
-     * @param expr
+     * @param expr projection and source
      * @param <T>
-     * @return
+     * @return select(expr).from(expr)
      */
     public static <T> JDOQuery<T> selectFrom(EntityPath<T> expr) {
         return select(expr).from(expr);

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOQLQuery.java

@@ -29,40 +29,41 @@ import com.querydsl.core.types.Path;
  *
  * @author tiwe
  *
+ * @param <T> result type
  */
 public interface JDOQLQuery<T> extends FetchableQuery<T, JDOQLQuery<T>>, Query<JDOQLQuery<T>>, ExtendedSubQuery<T>, Closeable {
 
     /**
      * Add query sources
      *
-     * @param sources
-     * @return
+     * @param sources sources
+     * @return the current object
      */
     JDOQLQuery<T> from(EntityPath<?>... sources);
 
     /**
      * Add query sources
      *
-     * @param path
-     * @param alias
+     * @param path source
+     * @param alias alias
      * @param <U>
-     * @return
+     * @return the current object
      */
     <U> JDOQLQuery<T> from(CollectionExpression<?, U> path, Path<U> alias);
 
     /**
      * Clone the state of the query for the given PersistenceManager
      *
-     * @param persistenceManager
-     * @return
+     * @param persistenceManager persistence manager
+     * @return cloned query
      */
     JDOQLQuery<T> clone(PersistenceManager persistenceManager);
 
     /**
      * Add the fetch group to the set of active fetch groups.
      * 
-     * @param fetchGroupName
-     * @return
+     * @param fetchGroupName fetch group name
+     * @return the current object
      */
     JDOQLQuery<T> addFetchGroup(String fetchGroupName);
 
@@ -73,8 +74,8 @@ public interface JDOQLQuery<T> extends FetchableQuery<T, JDOQLQuery<T>>, Query<J
      * A positive integer will result in that number of references from the
      * initial object to be fetched.
      * 
-     * @param maxFetchDepth
-     * @return
+     * @param maxFetchDepth max fetch depth
+     * @return the current object
      */
     JDOQLQuery<T> setMaxFetchDepth(int maxFetchDepth);
     

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOQLSerializer.java

@@ -27,7 +27,7 @@ import com.querydsl.core.types.*;
 import com.querydsl.core.types.dsl.Param;
 
 /**
- * JDOQLSerializer serializes Querydsl queries and expressions into JDOQL strings
+ * {@code JDOQLSerializer} serializes Querydsl queries and expressions into JDOQL strings
  *
  * @author tiwe
  *
@@ -273,7 +273,6 @@ public final class JDOQLSerializer extends SerializerBase<JDOQLSerializer> {
         return null;
     }
 
-//    @SuppressWarnings({ "unchecked", "rawtypes" })
     @Override
     protected void visitOperation(Class<?> type, Operator operator, List<? extends Expression<?>> args) {
         if (operator == Ops.INSTANCE_OF) {

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOQLTemplates.java

@@ -17,7 +17,7 @@ import com.querydsl.core.types.JavaTemplates;
 import com.querydsl.core.types.Ops;
 
 /**
- * JDOQLTemplates provides patterns for JDOQL serialization
+ * {@code JDOQLTemplates} provides patterns for JDOQL serialization
  *
  * @author tiwe
  *

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOQuery.java

@@ -21,15 +21,16 @@ import com.querydsl.core.Tuple;
 import com.querydsl.core.types.Expression;
 
 /**
- * JDOQuery is the default implementation of the JDOQLQuery interface
+ * {@code JDOQuery} is the default implementation of the {@link JDOQLQuery} interface
  *
  * @author tiwe
  *
+ * @param <T> result type
  */
 public class JDOQuery<T> extends AbstractJDOQuery<T, JDOQuery<T>> {
 
     /**
-     * Create a detached JDOQuery instance
+     * Create a detached {@link JDOQuery} instance
      * The query can be attached via the clone method
      *
      */
@@ -38,7 +39,7 @@ public class JDOQuery<T> extends AbstractJDOQuery<T, JDOQuery<T>> {
     }
 
     /**
-     * Create a new JDOQuery instance
+     * Create a new {@link JDOQuery} instance
      *
      * @param persistenceManager PersistenceManager instance to use
      * @param templates JDOQLTemplates to use
@@ -49,7 +50,7 @@ public class JDOQuery<T> extends AbstractJDOQuery<T, JDOQuery<T>> {
     }
 
     /**
-     * Create a new JDOQuery instance
+     * Create a new {@link JDOQuery} instance
      *
      * @param persistenceManager PersistenceManager instance to use
      * @param detach detached results or not
@@ -59,7 +60,7 @@ public class JDOQuery<T> extends AbstractJDOQuery<T, JDOQuery<T>> {
     }
 
     /**
-     * Create a new JDOQuery instance
+     * Create a new {@link JDOQuery} instance
      *
      * @param persistenceManager PersistenceManager instance to use
      */
@@ -68,12 +69,12 @@ public class JDOQuery<T> extends AbstractJDOQuery<T, JDOQuery<T>> {
     }
 
     /**
-     * Create a new JDOQuery instance
+     * Create a new {@link JDOQuery} instance
      * 
-     * @param persistenceManager
-     * @param templates
-     * @param metadata
-     * @param detach
+     * @param persistenceManager PersistenceManager instance to use
+     * @param templates templates to use
+     * @param metadata query metadata
+     * @param detach detached results or not
      */
     protected JDOQuery(PersistenceManager persistenceManager, JDOQLTemplates templates, 
             QueryMetadata metadata, boolean detach) {
@@ -81,10 +82,10 @@ public class JDOQuery<T> extends AbstractJDOQuery<T, JDOQuery<T>> {
     }
 
     /**
-     * Clone the state of this query to a new JDOQuery instance with the given PersistenceManager
+     * Clone the state of this query to a new {@link JDOQuery} instance with the given {@link PersistenceManager}
      *
-     * @param persistenceManager
-     * @return
+     * @param persistenceManager PersistenceManager instance to use
+     * @return cloned query
      */
     public JDOQuery<T> clone(PersistenceManager persistenceManager) {
         JDOQuery<T> query = new JDOQuery<T>(persistenceManager, getTemplates(),

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOQueryFactory.java

@@ -42,69 +42,71 @@ public class JDOQueryFactory implements QueryFactory<JDOQuery<?>> {
     }
 
     /**
-     * Create a new JDOQuery instance with the given projection
+     * Create a new {@link JDOQuery} instance with the given projection
      *
-     * @param expr
+     * @param expr projection
      * @param <T>
-     * @return
+     * @return select(expr)
      */
     public <T> JDOQuery<T> select(Expression<T> expr) {
         return query().select(expr);
     }
 
     /**
-     * Create a new JDOQuery instance with the given projection
+     * Create a new {@link JDOQuery} instance with the given projection
      *
-     * @param exprs
-     * @return
+     * @param exprs projection
+     * @return select(exprs)
      */
     public JDOQuery<Tuple> select(Expression<?>... exprs) {
         return query().select(exprs);
     }
 
     /**
-     * Create a new JDOQuery instance with the given projection
+     * Create a new {@link JDOQuery} instance with the given projection
      *
-     * @param expr
+     * @param expr projection
      * @param <T>
-     * @return
+     * @return select(distinct expr)
      */
     public <T> JDOQuery<T> selectDistinct(Expression<T> expr) {
         return query().select(expr).distinct();
     }
 
     /**
-     * Create a new JDOQuery instance with the given projection
+     * Create a new {@link JDOQuery} instance with the given projection
      *
-     * @param exprs
-     * @return
+     * @param exprs projection
+     * @return select(distinct exprs)
      */
     public JDOQuery<Tuple> selectDistinct(Expression<?>... exprs) {
         return query().select(exprs).distinct();
     }
 
     /**
+     * Create a new {@link JDOQuery} instance with the projection 0
      *
-     * @return
+     * @return select(0)
      */
     public JDOQuery<Integer> selectZero() {
         return select(Expressions.ZERO);
     }
 
     /**
+     * Create a new {@link JDOQuery} instance with the projection 1
      *
-     * @return
+     * @return select(1)
      */
     public JDOQuery<Integer> selectOne() {
         return select(Expressions.ONE);
     }
 
     /**
-     * Create a new JDOQuery instance with the given projection
+     * Create a new {@link JDOQuery} instance with the given projection
      *
-     * @param expr
+     * @param expr projection and source
      * @param <T>
-     * @return
+     * @return select(expr).from(expr)
      */
     public <T> JDOQuery<T> selectFrom(EntityPath<T> expr) {
         return select(expr).from(expr);

querydsl-jdo/src/main/java/com/querydsl/jdo/JDOQueryMixin.java

@@ -19,7 +19,7 @@ import com.querydsl.core.support.QueryMixin;
 import com.querydsl.core.types.*;
 
 /**
- * JDOQueryMixin extends {@link QueryMixin} to provide module specific extensions 
+ * {@code JDOQueryMixin} extends {@link QueryMixin} to provide module-specific extensions
  * 
  * @author tiwe
  *

querydsl-jdo/src/main/java/com/querydsl/jdo/dml/JDODeleteClause.java

@@ -30,7 +30,7 @@ import com.querydsl.core.types.EntityPath;
 import com.querydsl.core.types.Predicate;
 
 /**
- * DeleteClause implementation for JDO
+ * {@link DeleteClause} implementation for JDO
  *
  * @author tiwe
  *

querydsl-jdo/src/main/java/com/querydsl/jdo/dml/JDOUpdateClause.java

@@ -26,7 +26,7 @@ import com.querydsl.core.types.Path;
 import com.querydsl.core.types.Predicate;
 
 /**
- * UpdateClause implementation for JDO
+ * {@link UpdateClause} implementation for JDO
  *
  * @author tiwe
  *

querydsl-jdo/src/main/java/com/querydsl/jdo/sql/AbstractSQLQuery.java

@@ -36,14 +36,16 @@ import com.querydsl.core.types.Expression;
 import com.querydsl.core.types.FactoryExpression;
 import com.querydsl.sql.Configuration;
 import com.querydsl.sql.ProjectableSQLQuery;
+import com.querydsl.sql.SQLQuery;
 import com.querydsl.sql.SQLSerializer;
 
 /**
- * Base class for JDO based SQLQuery implementations
+ * Base class for JDO-based {@link SQLQuery} implementations
  *
  * @author tiwe
  *
- * @param <T>
+ * @param <T> result type
+ * @param <Q> concrete subclass
  */
 @SuppressWarnings("rawtypes")
 public abstract class AbstractSQLQuery<T, Q extends AbstractSQLQuery<T, Q>> extends ProjectableSQLQuery<T, Q> {
@@ -81,6 +83,9 @@ public abstract class AbstractSQLQuery<T, Q extends AbstractSQLQuery<T, Q>> exte
         this.detach = detach;
     }
 
+    /**
+     * Close the query and related resources
+     */
     public void close() {
         for (Query query : queries) {
             query.closeAll();
@@ -113,7 +118,7 @@ public abstract class AbstractSQLQuery<T, Q extends AbstractSQLQuery<T, Q>> exte
         if (logger.isDebugEnabled()) {
             logger.debug(serializer.toString());
         }
-        Query query = persistenceManager.newQuery("javax.jdo.query.SQL",serializer.toString());
+        Query query = persistenceManager.newQuery("javax.jdo.query.SQL", serializer.toString());
         orderedConstants = serializer.getConstants();
         queries.add(query);
 
@@ -144,7 +149,7 @@ public abstract class AbstractSQLQuery<T, Q extends AbstractSQLQuery<T, Q>> exte
         } else if (row.getClass().isArray()) {
             return expr.newInstance((Object[])row);
         } else {
-            return expr.newInstance(new Object[]{row});
+            return expr.newInstance(row);
         }
     }
 

querydsl-jdo/src/main/java/com/querydsl/jdo/sql/JDOSQLQuery.java

@@ -21,15 +21,18 @@ import com.querydsl.core.QueryMetadata;
 import com.querydsl.core.Tuple;
 import com.querydsl.core.types.Expression;
 import com.querydsl.sql.Configuration;
+import com.querydsl.sql.SQLQuery;
 import com.querydsl.sql.SQLSerializer;
 import com.querydsl.sql.SQLTemplates;
 
 /**
- * JDOSQLQuery is an SQLQuery implementation that uses JDO's SQL query functionality
+ * {@code JDOSQLQuery} is a {@link SQLQuery} implementation that uses JDO's SQL query functionality
  * to execute queries
  *
  * @author tiwe
  *
+ * @param <T> result type
+ *
  */
 public final class JDOSQLQuery<T> extends AbstractSQLQuery<T, JDOSQLQuery<T>> {