Update documentation for pipeline stages

lib/Doctrine/MongoDB/Aggregation/Builder.php

@@ -215,7 +215,8 @@ function (Stage $stage) { return $stage->getExpression(); },
      *
      * @see https://docs.mongodb.org/manual/reference/operator/aggregation/graphLookup/
      *
-     * @param string $from
+     * @param string $from Target collection for the $graphLookup operation to
+     * search, recursively matching the connectFromField to the connectToField.
      * @return Stage\GraphLookup
      */
     public function graphLookup($from)
@@ -348,7 +349,8 @@ public function redact()
      * including the _id field. You can promote an existing embedded document to
      * the top level, or create a new document for promotion.
      *
-     * @param string $expression
+     * @param string|null $expression Optional. A replacement expression that
+     * resolves to a document.
      *
      * @return Stage\ReplaceRoot
      */

lib/Doctrine/MongoDB/Aggregation/Expr.php

@@ -285,7 +285,7 @@ public function cond($if, $then, $else)
      *
      * For expression objects, it calls getExpression on the expression object.
      * For arrays, it recursively calls itself for each array item. Other values
-     * are returned directly
+     * are returned directly.
      *
      * @param mixed|self $expression
      * @return string|array

lib/Doctrine/MongoDB/Aggregation/Stage.php

@@ -159,7 +159,8 @@ public function getPipeline()
      *
      * @see https://docs.mongodb.org/manual/reference/operator/aggregation/graphLookup/
      *
-     * @param string $from
+     * @param string $from Target collection for the $graphLookup operation to
+     * search, recursively matching the connectFromField to the connectToField.
      * @return Stage\GraphLookup
      */
     public function graphLookup($from)
@@ -282,7 +283,8 @@ public function redact()
      * including the _id field. You can promote an existing embedded document to
      * the top level, or create a new document for promotion.
      *
-     * @param string $expression
+     * @param string|null $expression Optional. A replacement expression that
+     * resolves to a document.
      *
      * @return Stage\ReplaceRoot
      */

lib/Doctrine/MongoDB/Aggregation/Stage/AbstractBucket.php

@@ -25,6 +25,9 @@ abstract class AbstractBucket extends Stage
     protected $groupBy;
 
     /**
+     * An expression to group documents by. To specify a field path, prefix the
+     * field name with a dollar sign $ and enclose it in quotes.
+     *
      * @param array|Expr $expression
      * @return $this
      */

lib/Doctrine/MongoDB/Aggregation/Stage/AddFields.php

@@ -27,9 +27,7 @@
 class AddFields extends Operator
 {
     /**
-     * Assembles the aggregation stage
-     *
-     * @return array
+     * {@inheritdoc}
      */
     public function getExpression()
     {

lib/Doctrine/MongoDB/Aggregation/Stage/Bucket.php

@@ -41,6 +41,14 @@ class Bucket extends AbstractBucket
     private $default;
 
     /**
+     * An array of values based on the groupBy expression that specify the
+     * boundaries for each bucket.
+     *
+     * Each adjacent pair of values acts as the inclusive lower boundary and the
+     * exclusive upper boundary for the bucket. You must specify at least two
+     * boundaries. The specified values must be in ascending order and all of
+     * the same type. The exception is if the values are of mixed numeric types.
+     *
      * @param array ...$boundaries
      *
      * @return $this
@@ -52,6 +60,10 @@ public function boundaries(...$boundaries)
     }
 
     /**
+     * A literal that specifies the _id of an additional bucket that contains
+     * all documents whose groupBy expression result does not fall into a bucket
+     * specified by boundaries.
+     *
      * @param mixed $default
      *
      * @return $this
@@ -63,6 +75,10 @@ public function defaultBucket($default)
     }
 
     /**
+     * A document that specifies the fields to include in the output documents
+     * in addition to the _id field. To specify the field to include, you must
+     * use accumulator expressions.
+     *
      * @return Bucket\BucketOutput
      */
     public function output()

lib/Doctrine/MongoDB/Aggregation/Stage/Bucket/AbstractOutput.php

@@ -86,7 +86,7 @@ public function avg($expression)
     }
 
     /**
-     * Used to use an expression as field value. Can be any expression
+     * Used to use an expression as field value. Can be any expression.
      *
      * @see http://docs.mongodb.org/manual/meta/aggregation-quick-reference/#aggregation-expressions
      * @see Expr::expression

lib/Doctrine/MongoDB/Aggregation/Stage/Bucket/BucketAutoOutput.php

@@ -40,6 +40,9 @@ public function __construct(Builder $builder, Stage\BucketAuto $bucket)
     }
 
     /**
+     * An expression to group documents by. To specify a field path, prefix the
+     * field name with a dollar sign $ and enclose it in quotes.
+     *
      * @return Stage\BucketAuto
      */
     public function groupBy($expression)
@@ -48,6 +51,8 @@ public function groupBy($expression)
     }
 
     /**
+     * A positive 32-bit integer that specifies the number of buckets into which input documents are grouped.
+     *
      * @param int $buckets
      *
      * @return Stage\BucketAuto
@@ -58,6 +63,10 @@ public function buckets($buckets)
     }
 
     /**
+     * A string that specifies the preferred number series to use to ensure that
+     * the calculated boundary edges end on preferred round numbers or their
+     * powers of 10.
+     *
      * @param string $granularity
      *
      * @return Stage\BucketAuto

lib/Doctrine/MongoDB/Aggregation/Stage/Bucket/BucketOutput.php

@@ -20,6 +20,7 @@
 namespace Doctrine\MongoDB\Aggregation\Stage\Bucket;
 
 use Doctrine\MongoDB\Aggregation\Builder;
+use Doctrine\MongoDB\Aggregation\Expr;
 use Doctrine\MongoDB\Aggregation\Stage;
 
 /**
@@ -40,6 +41,10 @@ public function __construct(Builder $builder, Stage\Bucket $bucket)
     }
 
     /**
+     * An expression to group documents by. To specify a field path, prefix the
+     * field name with a dollar sign $ and enclose it in quotes.
+     *
+     * @param mixed|Expr $expression
      * @return Stage\Bucket
      */
     public function groupBy($expression)
@@ -48,6 +53,16 @@ public function groupBy($expression)
     }
 
     /**
+     * An array of values based on the groupBy expression that specify the
+     * boundaries for each bucket.
+     *
+     * Each adjacent pair of values acts as the inclusive lower boundary and the
+     * exclusive upper boundary for the bucket. You must specify at least two
+     * boundaries. The specified values must be in ascending order and all of
+     * the same type. The exception is if the values are of mixed numeric types.
+     *
+     * @param array ...$boundaries
+     *
      * @return Stage\Bucket
      */
     public function boundaries(...$boundaries)
@@ -56,6 +71,12 @@ public function boundaries(...$boundaries)
     }
 
     /**
+     * A literal that specifies the _id of an additional bucket that contains
+     * all documents whose groupBy expression result does not fall into a bucket
+     * specified by boundaries.
+     *
+     * @param mixed $default
+     *
      * @return Stage\Bucket
      */
     public function defaultBucket($default)

lib/Doctrine/MongoDB/Aggregation/Stage/BucketAuto.php

@@ -41,6 +41,9 @@ class BucketAuto extends AbstractBucket
     private $granularity;
 
     /**
+     * A positive 32-bit integer that specifies the number of buckets into which
+     * input documents are grouped.
+     *
      * @param int $buckets
      *
      * @return $this
@@ -51,13 +54,26 @@ public function buckets($buckets)
         return $this;
     }
 
+    /**
+     * A string that specifies the preferred number series to use to ensure that
+     * the calculated boundary edges end on preferred round numbers or their
+     * powers of 10.
+     *
+     * @param string $granularity
+     *
+     * @return $this
+     */
     public function granularity($granularity)
     {
         $this->granularity = $granularity;
         return $this;
     }
 
     /**
+     * A document that specifies the fields to include in the output documents
+     * in addition to the _id field. To specify the field to include, you must
+     * use accumulator expressions.
+     *
      * @return Bucket\BucketOutput
      */
     public function output()

lib/Doctrine/MongoDB/Aggregation/Stage/Facet.php

@@ -41,9 +41,7 @@ class Facet extends Stage
     private $fieldName;
 
     /**
-     * Assembles the aggregation stage
-     *
-     * @return array
+     * {@inheritdoc}
      */
     public function getExpression()
     {
@@ -53,7 +51,10 @@ public function getExpression()
     }
 
     /**
+     * Set the current field for building the pipeline stage.
+     *
      * @param string $fieldName
+     *
      * @return $this
      */
     public function field($fieldName)
@@ -63,6 +64,8 @@ public function field($fieldName)
     }
 
     /**
+     * Use the given pipeline for the current field.
+     *
      * @param Builder|Stage $builder
      * @return $this
      */

lib/Doctrine/MongoDB/Aggregation/Stage/GraphLookup.php

@@ -75,7 +75,8 @@ class GraphLookup extends Stage
      * Lookup constructor.
      *
      * @param Builder $builder
-     * @param string $from
+     * @param string $from Target collection for the $graphLookup operation to
+     * search, recursively matching the connectFromField to the connectToField.
      */
     public function __construct(Builder $builder, $from)
     {
@@ -85,12 +86,21 @@ public function __construct(Builder $builder, $from)
         $this->restrictSearchWithMatch = $this->createMatchObject();
     }
 
+    /**
+     * @return GraphLookup\Match
+     */
     protected function createMatchObject()
     {
         return new Stage\GraphLookup\Match($this->builder, $this);
     }
 
     /**
+     * Target collection for the $graphLookup operation to search, recursively
+     * matching the connectFromField to the connectToField.
+     *
+     * The from collection cannot be sharded and must be in the same database as
+     * any other collections used in the operation.
+     *
      * @param string $from
      *
      * @return $this
@@ -103,6 +113,12 @@ public function from($from)
     }
 
     /**
+     * Expression that specifies the value of the connectFromField with which to
+     * start the recursive search.
+     *
+     * Optionally, startWith may be array of values, each of which is
+     * individually followed through the traversal process.
+     *
      * @param string|array|Expr $expression
      *
      * @return $this
@@ -115,6 +131,12 @@ public function startWith($expression)
     }
 
     /**
+     * Field name whose value $graphLookup uses to recursively match against the
+     * connectToField of other documents in the collection.
+     *
+     * Optionally, connectFromField may be an array of field names, each of
+     * which is individually followed through the traversal process.
+     *
      * @param string $connectFromField
      *
      * @return $this
@@ -127,6 +149,9 @@ public function connectFromField($connectFromField)
     }
 
     /**
+     * Field name in other documents against which to match the value of the
+     * field specified by the connectFromField parameter.
+     *
      * @param string $connectToField
      *
      * @return $this
@@ -139,6 +164,11 @@ public function connectToField($connectToField)
     }
 
     /**
+     * Name of the array field added to each output document.
+     *
+     * Contains the documents traversed in the $graphLookup stage to reach the
+     * document.
+     *
      * @param string $alias
      *
      * @return $this
@@ -151,6 +181,8 @@ public function alias($alias)
     }
 
     /**
+     * Non-negative integral number specifying the maximum recursion depth.
+     *
      * @param int $maxDepth
      *
      * @return $this
@@ -163,6 +195,12 @@ public function maxDepth($maxDepth)
     }
 
     /**
+     * Name of the field to add to each traversed document in the search path.
+     *
+     * The value of this field is the recursion depth for the document,
+     * represented as a NumberLong. Recursion depth value starts at zero, so the
+     * first lookup corresponds to zero depth.
+     *
      * @param string $depthField
      *
      * @return $this
@@ -175,6 +213,8 @@ public function depthField($depthField)
     }
 
     /**
+     * A document specifying additional conditions for the recursive search.
+     *
      * @return GraphLookup\Match
      */
     public function restrictSearchWithMatch()