Improve the toCollection and related API documentation

JAVA-5833

Author: stIncMale

Diff for: driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/AggregatePublisher.java

@@ -17,15 +17,19 @@
 package com.mongodb.reactivestreams.client;
 
 import com.mongodb.ExplainVerbosity;
+import com.mongodb.MongoNamespace;
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.client.cursor.TimeoutMode;
+import com.mongodb.client.model.Aggregates;
 import com.mongodb.client.model.Collation;
+import com.mongodb.client.model.MergeOptions;
 import com.mongodb.lang.Nullable;
 import org.bson.BsonValue;
 import org.bson.Document;
 import org.bson.conversions.Bson;
 import org.reactivestreams.Publisher;
+import org.reactivestreams.Subscriber;
 
 import java.util.concurrent.TimeUnit;
 
@@ -83,13 +87,31 @@ public interface AggregatePublisher<TResult> extends Publisher<TResult> {
     AggregatePublisher<TResult> bypassDocumentValidation(@Nullable Boolean bypassDocumentValidation);
 
     /**
-     * Aggregates documents according to the specified aggregation pipeline, which must end with a $out stage.
+     * Aggregates documents according to the specified aggregation pipeline, which must end with an
+     * {@link Aggregates#out(String, String) $out} or {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage.
+     * Calling this method and then {@linkplain Publisher#subscribe(Subscriber) subscribing} to the returned {@link Publisher}
+     * is a preferred alternative to calling {@link #subscribe(Subscriber)} on this {@link AggregatePublisher}.
      *
+     * @throws IllegalStateException if the pipeline does not end with an {@code $out} or {@code $merge} stage
      * @return an empty publisher that indicates when the operation has completed
      * @mongodb.driver.manual aggregation/ Aggregation
      */
     Publisher<Void> toCollection();
 
+    /**
+     * Requests {@link AggregatePublisher} to start streaming data according to the specified aggregation pipeline.
+     * <ul>
+     *     <li>
+     *     If the aggregation pipeline ends with an {@link Aggregates#out(String, String) $out} or
+     *     {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage,
+     *     then {@linkplain MongoCollection#find() finds all} documents in the affected namespace and produces them.
+     *     You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise produces no elements.</li>
+     * </ul>
+     */
+    void subscribe(Subscriber<? super TResult> s);
+
     /**
      * Sets the collation options
      *

Diff for: driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MapReducePublisher.java

@@ -16,19 +16,22 @@
 
 package com.mongodb.reactivestreams.client;
 
-
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.client.cursor.TimeoutMode;
 import com.mongodb.client.model.Collation;
 import com.mongodb.lang.Nullable;
 import org.bson.conversions.Bson;
 import org.reactivestreams.Publisher;
+import org.reactivestreams.Subscriber;
 
 import java.util.concurrent.TimeUnit;
 
 /**
  * Publisher for map reduce.
+ * <p>
+ * By default, the {@code MapReducePublisher} produces the results inline. You can write map-reduce output to a collection by using the
+ * {@link #collectionName(String)} and {@link #toCollection()} methods.</p>
  *
  * @param <TResult> The type of the result.
  * @since 1.0
@@ -44,6 +47,7 @@ public interface MapReducePublisher<TResult> extends Publisher<TResult> {
      *
      * @param collectionName the name of the collection that you want the map-reduce operation to write its output.
      * @return this
+     * @see #toCollection()
      */
     MapReducePublisher<TResult> collectionName(String collectionName);
 
@@ -152,14 +156,29 @@ public interface MapReducePublisher<TResult> extends Publisher<TResult> {
     MapReducePublisher<TResult> bypassDocumentValidation(@Nullable Boolean bypassDocumentValidation);
 
     /**
-     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must specify a
-     * non-inline result.
+     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must not produce
+     * results inline. Calling this method and then {@linkplain Publisher#subscribe(Subscriber) subscribing} to the returned
+     * {@link Publisher} is a preferred alternative to {@linkplain #subscribe(Subscriber) subscribing} to this {@link MapReducePublisher}.
      *
      * @return an empty publisher that indicates when the operation has completed
+     * @throws IllegalStateException if a {@linkplain #collectionName(String) collection name} to write the results to has not been specified
+     * @see #collectionName(String)
      * @mongodb.driver.manual aggregation/ Aggregation
      */
     Publisher<Void> toCollection();
 
+    /**
+     * Requests {@link MapReducePublisher} to start streaming data according to the specified map-reduce function with the given options.
+     * <ul>
+     *     <li>
+     *     If the aggregation produces results inline, then {@linkplain MongoCollection#find() finds all} documents in the
+     *     affected namespace and produces them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise produces no elements.</li>
+     * </ul>
+     */
+    void subscribe(Subscriber<? super TResult> s);
+
     /**
      * Sets the collation options
      *

Diff for: driver-sync/src/main/com/mongodb/client/AggregateIterable.java

@@ -17,10 +17,13 @@
 package com.mongodb.client;
 
 import com.mongodb.ExplainVerbosity;
+import com.mongodb.MongoNamespace;
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.client.cursor.TimeoutMode;
+import com.mongodb.client.model.Aggregates;
 import com.mongodb.client.model.Collation;
+import com.mongodb.client.model.MergeOptions;
 import com.mongodb.lang.Nullable;
 import org.bson.BsonValue;
 import org.bson.Document;
@@ -38,15 +41,47 @@
 public interface AggregateIterable<TResult> extends MongoIterable<TResult> {
 
     /**
-     * Aggregates documents according to the specified aggregation pipeline, which must end with a $out or $merge stage.
+     * Aggregates documents according to the specified aggregation pipeline, which must end with an
+     * {@link Aggregates#out(String, String) $out} or {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage.
+     * This method is the preferred alternative to {@link #iterator()}, {@link #cursor()}.
      *
-     * @throws IllegalStateException if the pipeline does not end with a $out or $merge stage
+     * @throws IllegalStateException if the pipeline does not end with an {@code $out} or {@code $merge} stage
      * @mongodb.driver.manual reference/operator/aggregation/out/ $out stage
      * @mongodb.driver.manual reference/operator/aggregation/merge/ $merge stage
      * @since 3.4
      */
     void toCollection();
 
+    /**
+     * Aggregates documents according to the specified aggregation pipeline.
+     * <ul>
+     *     <li>
+     *     If the aggregation pipeline ends with an {@link Aggregates#out(String, String) $out} or
+     *     {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage,
+     *     then {@linkplain MongoCollection#find() finds all} documents in the affected namespace and returns a {@link MongoCursor}
+     *     over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> iterator();
+
+    /**
+     * Aggregates documents according to the specified aggregation pipeline.
+     * <ul>
+     *     <li>
+     *     If the aggregation pipeline ends with an {@link Aggregates#out(String, String) $out} or
+     *     {@link Aggregates#merge(MongoNamespace, MergeOptions) $merge} stage,
+     *     then {@linkplain MongoCollection#find() finds all} documents in the affected namespace and returns a {@link MongoCursor}
+     *     over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> cursor();
+
     /**
      * Enables writing to temporary files. A null value indicates that it's unspecified.
      *

Diff for: driver-sync/src/main/com/mongodb/client/MapReduceIterable.java

@@ -27,9 +27,9 @@
 
 /**
  * Iterable for map-reduce.
- *
- * <p>By default the {@code MapReduceIterable} returns the results inline. You can write map-reduce output to a collection by using the
- * {@link MapReduceIterable#collectionName(String)} method.</p>
+ * <p>
+ * By default, the {@code MapReduceIterable} produces the results inline. You can write map-reduce output to a collection by using the
+ * {@link #collectionName(String)} and {@link #toCollection()} methods.</p>
  *
  * @param <TResult> The type of the result.
  * @since 3.0
@@ -39,22 +39,49 @@
 public interface MapReduceIterable<TResult> extends MongoIterable<TResult> {
 
     /**
-     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must specify a
-     * non-inline result.
+     * Aggregates documents to a collection according to the specified map-reduce function with the given options, which must not produce
+     * results inline. This method is the preferred alternative to {@link #iterator()}, {@link #cursor()}.
      *
-     * @throws IllegalStateException if a collection name to write the results to has not been specified
+     * @throws IllegalStateException if a {@linkplain #collectionName(String) collection name} to write the results to has not been specified
      * @see #collectionName(String)
      * @since 3.4
      */
     void toCollection();
 
+    /**
+     * Aggregates documents according to the specified map-reduce function with the given options.
+     * <ul>
+     *     <li>
+     *     If the aggregation produces results inline, then {@linkplain MongoCollection#find() finds all} documents in the
+     *     affected namespace and returns a {@link MongoCursor} over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> iterator();
+
+    /**
+     * Aggregates documents according to the specified map-reduce function with the given options.
+     * <ul>
+     *     <li>
+     *     If the aggregation produces results inline, then {@linkplain MongoCollection#find() finds all} documents in the
+     *     affected namespace and returns a {@link MongoCursor} over them. You may want to use {@link #toCollection()} instead.</li>
+     *     <li>
+     *     Otherwise returns a {@link MongoCursor} producing no elements.</li>
+     * </ul>
+     */
+    @Override
+    MongoCursor<TResult> cursor();
+
     /**
      * Sets the collectionName for the output of the MapReduce
      *
      * <p>The default action is replace the collection if it exists, to change this use {@link #action}.</p>
      *
      * @param collectionName the name of the collection that you want the map-reduce operation to write its output.
      * @return this
+     * @see #toCollection()
      */
     MapReduceIterable<TResult> collectionName(String collectionName);
 

Diff for: driver-sync/src/main/com/mongodb/client/MongoIterable.java

@@ -35,7 +35,7 @@ public interface MongoIterable<TResult> extends Iterable<TResult> {
     /**
      * Returns a cursor used for iterating over elements of type {@code TResult}. The cursor is primarily used for change streams.
      *
-     * @return a cursor
+     * @return a cursor equivalent to that returned from {@link #iterator()}.
      * @since 3.11
      */
     MongoCursor<TResult> cursor();