From df51419be20ef30c64df049082453cce44da8584 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Timo=20Westk=C3=A4mper?= <timo.westkamper@gmail.com>
Date: Sat, 2 May 2015 22:59:33 +0300
Subject: [PATCH] Improve javadocs for querydsl-mongodb

---
 .../mongodb/AbstractMongodbQuery.java         | 61 +++++++++++++++----
 .../querydsl/mongodb/AnyEmbeddedBuilder.java  |  2 +-
 .../com/querydsl/mongodb/JoinBuilder.java     |  2 +-
 .../querydsl/mongodb/MongodbExpressions.java  |  4 +-
 .../java/com/querydsl/mongodb/MongodbOps.java |  2 +
 .../main/java/com/querydsl/mongodb/Point.java |  4 +-
 .../mongodb/morphia/MorphiaQuery.java         | 12 +++-
 .../mongodb/morphia/MorphiaSerializer.java    |  2 +-
 8 files changed, 68 insertions(+), 21 deletions(-)

diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AbstractMongodbQuery.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AbstractMongodbQuery.java
index 232c19436..b9a06e5f5 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AbstractMongodbQuery.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AbstractMongodbQuery.java
@@ -31,7 +31,7 @@ import com.querydsl.core.types.*;
 import com.querydsl.core.types.dsl.CollectionPathBase;
 
 /**
- * AbstractMongodbQuery provides a base class for general Querydsl query implementation with a
+ * {@code AbstractMongodbQuery} provides a base class for general Querydsl query implementation with a
  * pluggable DBObject to Bean transformation
  *
  * @author laimw
@@ -57,9 +57,9 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
     /**
      * Create a new MongodbQuery instance
      *
-     * @param collection
-     * @param transformer
-     * @param serializer
+     * @param collection collection
+     * @param transformer result transformer
+     * @param serializer serializer
      */
     public AbstractMongodbQuery(DBCollection collection, Function<DBObject, K> transformer, MongodbSerializer serializer) {
         this.queryMixin = new QueryMixin<Q>((Q)this, new DefaultQueryMetadata(), false);
@@ -71,9 +71,9 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
     /**
      * Define a join
      *
-     * @param ref
-     * @param target
-     * @return
+     * @param ref reference
+     * @param target join target
+     * @return join builder
      */
     public <T> JoinBuilder<Q, K,T> join(Path<T> ref, Path<T> target) {
         return new JoinBuilder<Q, K,T>(queryMixin, ref, target);
@@ -82,9 +82,9 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
     /**
      * Define a join
      *
-     * @param ref
-     * @param target
-     * @return
+     * @param ref reference
+     * @param target join target
+     * @return join builder
      */
     public <T> JoinBuilder<Q, K,T> join(CollectionPathBase<?,T,?> ref, Path<T> target) {
         return new JoinBuilder<Q, K,T>(queryMixin, ref, target);
@@ -93,9 +93,9 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
     /**
      * Define a constraint for an embedded object
      *
-     * @param collection
-     * @param target
-     * @return
+     * @param collection collection
+     * @param target target
+     * @return builder
      */
     public <T> AnyEmbeddedBuilder<Q, K> anyEmbedded(Path<? extends Collection<T>> collection, Path<T> target) {
         return new AnyEmbeddedBuilder<Q, K>(queryMixin, collection);
@@ -198,6 +198,12 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
         return queryMixin.set(param, value);
     }
 
+    /**
+     * Iterate with the specific fields
+     *
+     * @param paths fields to return
+     * @return iterator
+     */
     public CloseableIterator<K> iterate(Path<?>... paths) {
         queryMixin.setProjection(paths);
         return iterate();
@@ -227,6 +233,12 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
         };
     }
 
+    /**
+     * Fetch with the specific fields
+     *
+     * @param paths fields to return
+     * @return results
+     */
     public List<K> fetch(Path<?>... paths) {
         queryMixin.setProjection(paths);
         return fetch();
@@ -285,6 +297,12 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
         return null;
     }
 
+    /**
+     * Fetch first with the specific fields
+     *
+     * @param paths fields to return
+     * @return first result
+     */
     public K fetchFirst(Path<?>...paths) {
         queryMixin.setProjection(paths);
         return fetchFirst();
@@ -304,6 +322,12 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
         }
     }
 
+    /**
+     * Fetch one with the specific fields
+     *
+     * @param paths fields to return
+     * @return first result
+     */
     public K fetchOne(Path<?>... paths) {
         queryMixin.setProjection(paths);
         return fetchOne();
@@ -331,6 +355,12 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
         }
     }
 
+    /**
+     * Fetch results with the specific fields
+     *
+     * @param paths fields to return
+     * @return results
+     */
     public QueryResults<K> fetchResults(Path<?>... paths) {
         queryMixin.setProjection(paths);
         return fetchResults();
@@ -368,6 +398,11 @@ public abstract class AbstractMongodbQuery<K, Q extends AbstractMongodbQuery<K,
         }
     }
 
+    /**
+     * Sets the read preference for this query
+     *
+     * @param readPreference read preference
+     */
     public void setReadPreference(ReadPreference readPreference) {
         this.readPreference = readPreference;
     }
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AnyEmbeddedBuilder.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AnyEmbeddedBuilder.java
index 0aba8e6dc..84b757f06 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AnyEmbeddedBuilder.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/AnyEmbeddedBuilder.java
@@ -21,7 +21,7 @@ import com.querydsl.core.types.Path;
 import com.querydsl.core.types.Predicate;
 
 /**
- * AnyEmbeddedBuilder is a builder for constraints on embedded objects
+ * {@code AnyEmbeddedBuilder} is a builder for constraints on embedded objects
  *
  * @author tiwe
  *
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/JoinBuilder.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/JoinBuilder.java
index d78270d97..4dd852d5f 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/JoinBuilder.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/JoinBuilder.java
@@ -20,7 +20,7 @@ import com.querydsl.core.types.Path;
 import com.querydsl.core.types.Predicate;
 
 /**
- * JoinBuilder is a builder for join constraints
+ * {@code JoinBuilder} is a builder for join constraints
  *
  * @author tiwe
  *
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbExpressions.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbExpressions.java
index 34beedb76..d2e63a15e 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbExpressions.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbExpressions.java
@@ -31,10 +31,10 @@ public final class MongodbExpressions {
     /**
      * Finds the closest points relative to the given location and orders the results with decreasing proximity
      *
-     * @param expr
+     * @param expr location
      * @param latVal latitude
      * @param longVal longitude
-     * @return
+     * @return predicate
      */
     public static BooleanExpression near(Expression<Double[]> expr, double latVal, double longVal) {
         return Expressions.booleanOperation(MongodbOps.NEAR, expr, ConstantImpl.create(new Double[]{latVal, longVal}));
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbOps.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbOps.java
index 37c7f1a3e..47aea82ff 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbOps.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/MongodbOps.java
@@ -16,6 +16,8 @@ package com.querydsl.mongodb;
 import com.querydsl.core.types.Operator;
 
 /**
+ * MongoDB specific operators
+ *
  * @author tiwe
  *
  */
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/Point.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/Point.java
index d866938a1..c39452601 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/Point.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/Point.java
@@ -19,7 +19,7 @@ import com.querydsl.core.types.dsl.BooleanExpression;
 import com.querydsl.core.types.dsl.ArrayPath;
 
 /**
- * Point is an adapter type for Double[] arrays to use geo spatial querying features of Mongodb
+ * {@code Point} is an adapter type for Double[] arrays to use geo spatial querying features of Mongodb
  *
  * @author tiwe
  *
@@ -45,7 +45,7 @@ public class Point extends ArrayPath<Double[], Double> {
      *
      * @param latVal latitude
      * @param longVal longitude
-     * @return
+     * @return predicate
      */
     public BooleanExpression near(double latVal, double longVal) {
         return MongodbExpressions.near(this, latVal, longVal);
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaQuery.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaQuery.java
index 9a64fbd92..ca2771f05 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaQuery.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaQuery.java
@@ -26,7 +26,17 @@ import com.querydsl.mongodb.AbstractMongodbQuery;
 import com.querydsl.core.types.EntityPath;
 
 /**
- * MorphiaQuery extends {@link com.querydsl.mongodb.AbstractMongodbQuery} with Morphia specific transformations
+ * {@code MorphiaQuery} extends {@link AbstractMongodbQuery} with Morphia specific transformations
+ *
+ * <p>Example</p>
+ *
+ * <pre>{@code
+ * QUser user = QUser.user;
+ * MorphiaQuery<User> query = new MorphiaQuery<User>(morphia, datastore, user);
+ * List<User> list = query
+ *     .where(user.firstName.eq("Bob"))
+ *     .fetch();
+ * }</pre>
  *
  * @author laimw
  * @author tiwe
diff --git a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaSerializer.java b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaSerializer.java
index 19588c952..b2a89d28e 100644
--- a/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaSerializer.java
+++ b/querydsl-mongodb/src/main/java/com/querydsl/mongodb/morphia/MorphiaSerializer.java
@@ -26,7 +26,7 @@ import com.querydsl.core.types.PathType;
 import com.querydsl.mongodb.MongodbSerializer;
 
 /**
- * MorphiaSerializer extends {@link MongodbSerializer} with Morphia specific annotation handling
+ * {@code MorphiaSerializer} extends {@link MongodbSerializer} with Morphia specific annotation handling
  *
  * @author tiwe
  *