JAVA-2778: Add Javadoc for cursors indicating that they should be closed using, for example, try-with-resources.

Author: jyemin

driver/src/main/com/mongodb/DBCursor.java

@@ -36,13 +36,16 @@
 import static java.util.concurrent.TimeUnit.MILLISECONDS;
 
 /**
- * <p>An iterator over database results. Doing a {@code find()} query on a collection returns a {@code DBCursor} thus</p>
- * <pre>
- *    DBCursor cursor = collection.find(query);
- *    if(cursor.hasNext()) {
- *       DBObject obj = cursor.next();
+ * <p>An iterator over database results. Doing a {@code find()} query on a collection returns a {@code DBCursor}.</p>
+ * <p> An application should ensure that a cursor is closed in all circumstances, e.g. using a try-with-resources statement:</p>
+ * <blockquote><pre>
+ *    try (DBCursor cursor = collection.find(query)) {
+ *        while (cursor.hasNext()) {
+ *            System.out.println(cursor.next();
+ *        }
  *    }
- * </pre>
+ * </pre></blockquote>
+ *
  * <p><b>Warning:</b> Calling {@code toArray} or {@code length} on a DBCursor will irrevocably turn it into an array.  This means that, if
  * the cursor was iterating over ten million results (which it was lazily fetching from the database), suddenly there will be a ten-million
  * element array in memory.  Before converting to an array, make sure that there are a reasonable number of results using {@code skip()} and

driver/src/main/com/mongodb/client/MongoCursor.java

@@ -24,13 +24,24 @@
 import java.util.Iterator;
 
 /**
- * The Mongo Cursor interface implementing the iterator protocol
+ * The Mongo Cursor interface implementing the iterator protocol.
+ * <p>
+ * An application should ensure that a cursor is closed in all circumstances, e.g. using a try-with-resources statement:
+ *
+ * <blockquote><pre>
+ * try (MongoCursor&lt;Document&gt; cursor = collection.find().iterator()) {
+ *     while (cursor.hasNext()) {
+ *         System.out.println(cursor.next());
+ *     }
+ * }
+ * </pre></blockquote>
  *
  * @since 3.0
  * @param <TResult> The type of documents the cursor contains
  */
 @NotThreadSafe
 public interface MongoCursor<TResult> extends Iterator<TResult>, Closeable {
+
     @Override
     void close();