javadoc updates for the interfaces

fixes MorphiaOrg#618  (mostly)

config/checkstyle-exclude.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+
+<!--
+  ~ Copyright (c) 2008-2014 MongoDB, Inc.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~   http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<!DOCTYPE suppressions PUBLIC
+        "-//Puppy Crawl//DTD Suppressions 1.1//EN"
+        "http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
+
+<suppressions>
+    <!--Do not check test classes -->
+    <suppress checks="Javadoc*" files=".*test.*"/>
+
+</suppressions>

config/checkstyle.xml

@@ -51,17 +51,14 @@
         <!-- Checks for Javadoc comments.                     -->
         <!-- See http://checkstyle.sf.net/config_javadoc.html -->
         <!-- TODO: This has to be enabled at some point before we release -->
-<!--
         <module name="JavadocType">
             <property name="scope" value="public"/>
             <property name="tokens" value="INTERFACE_DEF"/>
         </module>
         <module name="JavadocMethod">
             <property name="scope" value="public"/>
-            <property name="allowMissingPropertyJavadoc" value="true"/>
             <property name="tokens" value="INTERFACE_DEF"/>
         </module>
--->
         <!--<module name="JavadocVariable"/>-->
         <!--<module name="JavadocStyle"/>-->
 
@@ -194,5 +191,8 @@
         </module>
     </module>
     <module name="SuppressionCommentFilter"/>
+    <module name="SuppressionFilter">
+        <property name="file" value="config/checkstyle-exclude.xml"/>
+    </module>
 
 </module>

morphia/src/main/java/org/mongodb/morphia/ObjectFactory.java

@@ -8,16 +8,39 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * The ObjectFactory is used by morphia to create instances of classes which can be customized to fit a particular applications needs.
+ */
 public interface ObjectFactory {
+    /**
+     * Creates an instance of the given class.
+     */
     <T> T createInstance(Class<T> clazz);
 
+    /**
+     * Creates an instance of the class defined in the {@link Mapper#CLASS_NAME_FIELDNAME} field in the dbObject passed in.  If that field
+     * is missing, the given Class is used instead.
+     */
     <T> T createInstance(Class<T> clazz, DBObject dbObj);
 
+    /**
+     * Creates an instance of the class defined in the {@link Mapper#CLASS_NAME_FIELDNAME} field in the dbObject passed in.  If that field
+     * is missing, morphia attempts to the MappedField to determine which concrete class to instantiate.
+     */
     Object createInstance(Mapper mapper, MappedField mf, DBObject dbObj);
 
+    /**
+     * Defines how morphia creates a Map object. 
+     */
     Map createMap(MappedField mf);
 
+    /**
+     * Defines how morphia creates a List object. 
+     */
     List createList(MappedField mf);
 
+    /**
+     * Defines how morphia creates a Set object. 
+     */
     Set createSet(MappedField mf);
 }

morphia/src/main/java/org/mongodb/morphia/aggregation/AggregationPipeline.java

@@ -8,23 +8,85 @@
 
 import java.util.List;
 
+/**
+ * This defines the pipeline used in aggregation operations
+ *
+ * @see <a href="http://docs.mongodb.org/manual/core/aggregation-pipeline/">Aggregation Pipeline</a>
+ * 
+ * @param <T> The input type of the aggregation
+ * @param <U> The output type of the aggregation
+ */
 public interface AggregationPipeline<T, U> {
+    /**
+     * Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one
+     * document.
+     *
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/project/#pipe._S_project">$project</a>
+     */
     AggregationPipeline<T, U> project(Projection... projections);
 
+    /**
+     * Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group .
+     * Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field
+     * and, if specified, accumulated fields.
+     *
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/group/#pipe._S_group">$group</a>
+     */
     AggregationPipeline<T, U> group(String id, Group... groupings);
 
+    /**
+     * @see #group(String, Group...}
+     */
     AggregationPipeline<T, U> group(List<Group> id, Group... groupings);
 
+    /**
+     * Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard
+     * MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).
+     *
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/match/#pipe._S_match">$match</a>
+     */
     AggregationPipeline<T, U> match(Query query);
 
+    /**
+     * Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input
+     * document, outputs one document.
+     * 
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/sort/#pipe._S_sort">$sort</a>
+     */
     AggregationPipeline<T, U> sort(Sort... sorts);
 
+    /**
+     * Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either 
+     * one document (for the first n documents) or zero documents (after the first n documents).
+     * 
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/limit/#pipe._S_limit">$limit</a>
+     */
     AggregationPipeline<T, U> limit(int count);
 
+    /**
+     * Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. 
+     * For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).
+     * 
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/skip/#pipe._S_skip">$skip</a>
+     */
     AggregationPipeline<T, U> skip(int count);
 
+    /**
+     * Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the 
+     * array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero 
+     * for an empty array.
+     * 
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/unwind/#pipe._S_unwind">$unwind</a>
+     */
     AggregationPipeline<T, U> unwind(String field);
 
+    /**
+     * Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, 
+     * $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location 
+     * identifier field.
+     * 
+     * @see <a href="http://docs.mongodb.org/manual/reference/operator/aggregation/geoNear/#pipe._S_geoNear">$geoNear</a>
+     */
     AggregationPipeline<T, U> geoNear(GeoNear geoNear);
 
     /**

morphia/src/main/java/org/mongodb/morphia/annotations/Reference.java

@@ -64,3 +64,25 @@
    */
   boolean idOnly() default false;
 }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

morphia/src/main/java/org/mongodb/morphia/dao/DAO.java

@@ -14,6 +14,12 @@
 import java.util.List;
 
 
+/**
+ * Defines a basic interface for use in applications
+ * 
+ * @param <T> The Java type serviced by this DAO
+ * @param <K> The Key type used by the entity
+ */
 public interface DAO<T, K> {
     /**
      * Starts a query for this DAO entities type

morphia/src/main/java/org/mongodb/morphia/logging/Logger.java

@@ -16,6 +16,10 @@
 
 package org.mongodb.morphia.logging;
 
+/**
+ * A generic logger interface used internally by Morphia.  At runtime the actual implementation used is chosen to match which logging
+ * framework (e.g., java.util.logging vs slf4j) is used in the application.
+ */
 public interface Logger {
     boolean isTraceEnabled();
 

morphia/src/main/java/org/mongodb/morphia/logging/LoggerFactory.java

@@ -16,6 +16,9 @@
 
 package org.mongodb.morphia.logging;
 
+/**
+ * A generic logger factory interface used internally by Morphia.  At runtime the actual implementation used is chosen to match which 
+ * logging framework (e.g., java.util.logging vs slf4j) is used in the application. */
 public interface LoggerFactory {
     Logger get(Class<?> c);
 }

morphia/src/main/java/org/mongodb/morphia/mapping/DefaultCreator.java

@@ -23,16 +23,10 @@
 public class DefaultCreator implements ObjectFactory {
     private static final Logger LOG = MorphiaLoggerFactory.get(DefaultCreator.class);
 
-    /* (non-Javadoc)
-     * @see org.mongodb.morphia.ObjectFactory#createInstance(java.lang.Class)
-     */
     public <T> T createInstance(final Class<T> clazz) {
         return createInst(clazz);
     }
 
-    /* (non-Javadoc)
-     * @see org.mongodb.morphia.ObjectFactory#createInstance(java.lang.Class, com.mongodb.DBObject)
-     */
     public <T> T createInstance(final Class<T> clazz, final DBObject dbObj) {
         Class<T> c = getClass(dbObj);
         if (c == null) {
@@ -41,9 +35,6 @@ public <T> T createInstance(final Class<T> clazz, final DBObject dbObj) {
         return createInstance(c);
     }
 
-    /**
-     * @see ObjectFactory#createInstance(Mapper, MappedField, DBObject)
-     */
     @SuppressWarnings("unchecked")
     public Object createInstance(final Mapper mapper, final MappedField mf, final DBObject dbObj) {
         Class c = getClass(dbObj);
@@ -100,23 +91,14 @@ protected ClassLoader getClassLoaderForClass() {
         return Thread.currentThread().getContextClassLoader();
     }
 
-    /* (non-Javadoc)
-     * @see org.mongodb.morphia.ObjectFactory#createMap(org.mongodb.morphia.mapping.MappedField)
-     */
     public Map createMap(final MappedField mf) {
         return (Map) newInstance(mf.getCTor(), HashMap.class);
     }
 
-    /* (non-Javadoc)
-     * @see org.mongodb.morphia.ObjectFactory#createList(org.mongodb.morphia.mapping.MappedField)
-     */
     public List createList(final MappedField mf) {
         return (List) newInstance(mf.getCTor(), ArrayList.class);
     }
 
-    /* (non-Javadoc)
-     * @see org.mongodb.morphia.ObjectFactory#createSet(org.mongodb.morphia.mapping.MappedField)
-     */
     public Set createSet(final MappedField mf) {
         return (Set) newInstance(mf.getCTor(), HashSet.class);
     }
@@ -137,7 +119,6 @@ public static <T> T createInst(final Class<T> clazz) {
     /**
      * creates an instance of testType (if it isn't Object.class or null) or fallbackType
      */
-    @SuppressWarnings("unchecked")
     private static Object newInstance(final Constructor tryMe, final Class fallbackType) {
         if (tryMe != null) {
             tryMe.setAccessible(true);

morphia/src/main/java/org/mongodb/morphia/mapping/cache/EntityCache.java

@@ -3,7 +3,10 @@
 
 import org.mongodb.morphia.Key;
 
-
+/**
+ * A primarily internal class used by MorphiaIterator to track entities loaded from mongo to prevent multiple loads of objects when keys
+ * are seen multiple times in a query result.
+ */
 public interface EntityCache {
   Boolean exists(Key<?> k);
 

morphia/src/main/java/org/mongodb/morphia/query/Criteria.java

@@ -4,6 +4,9 @@
 import com.mongodb.DBObject;
 
 
+/**
+ * Internal class for building up query documents.
+ */
 public interface Criteria {
   void addTo(DBObject obj);
 

morphia/src/main/java/org/mongodb/morphia/query/CriteriaContainer.java

@@ -1,6 +1,8 @@
 package org.mongodb.morphia.query;
 
-
+/**
+ * Internal class to represent groups of {@see Criteria} intances via $and and $or query clauses 
+ */
 public interface CriteriaContainer extends Criteria {
   void add(Criteria... criteria);
 

morphia/src/main/java/org/mongodb/morphia/query/FieldEnd.java

@@ -3,6 +3,10 @@
 
 import org.mongodb.morphia.geo.Point;
 
+/**
+ * Represents a document field in a query and presents the operations available to querying against that field.
+ * @param <T>
+ */
 public interface FieldEnd<T> {
 
     T contains(String string);

morphia/src/main/java/org/mongodb/morphia/query/Query.java

@@ -12,6 +12,8 @@
 
 /**
  * @author Scott Hernandez
+ * 
+ * @param <T> The java type to query against
  */
 public interface Query<T> extends QueryResults<T>, Cloneable {
   /**

morphia/src/main/java/org/mongodb/morphia/query/QueryResults.java

@@ -5,7 +5,10 @@
 
 import java.util.List;
 
-
+/**
+ * The results of a query.  These results aren't materialized until a method on this interface is called.
+ * @param <T>
+ */
 public interface QueryResults<T> extends Iterable<T> {
     /**
      * Gets the first entity in the result set.  Obeys the {@link Query} offset value.