59 improve docstrings in stages and operators (#110)

* updated avg and count operators docstrings. * updated avg and count operators docstrings. * replaced ' statement' with ' operator' in avg.py. * fixed doc in accumulators/ . * fixed doc in arithmetic/ . * fixed formatting of the link to MongoDB documentation in avg class docstring in avg.py . * fixed docstrings in array/ * fixed doc in boolean/ * fixed docs in comparisons/. * fixed docstrings in conditional/. * fixed docstrings in objects/. * fixed doctrings in strings/. * fixed docstrings in type_/. * corrected a minor type in DollarDollar docstring. * replaced 'expression' with operator' in operators definition docstrings. fixed typo in Source links. fixed millisecond operator docstring. fixed other minor typos. * added online mongodb documentation section to millisecond.py docstring.
VianneyMI · Apr 17, 2024 · 43e536c · 43e536c
1 parent 9df5c18
commit 43e536c
Show file tree

Hide file tree

Showing 44 changed files with 900 additions and 62 deletions.
diff --git a/src/monggregate/dollar.py b/src/monggregate/dollar.py
@@ -469,7 +469,7 @@ class DollarDollar(Singleton):
     MongoDB double dollar sign ($$) abstraction in python.
 
     This class is a singleton class meant to be used as a namespace for all MongoDB aggregation variables.
-    Can also be used to refrence a user-defined variable.
+    Can also be used to reference a user-defined variable.
 
     Examples:
     ------------------------------

diff --git a/src/monggregate/operators/accumulators/avg.py b/src/monggregate/operators/accumulators/avg.py
@@ -12,7 +12,7 @@
 
 $avg
 Returns the average value of the numeric values.
-$avgignores non-numeric values.
+$avg ignores non-numeric values.
 
     * $avg is available in these stages:
     * $addFields (Available starting in MongoDB 3.4)
@@ -75,12 +75,31 @@
 
 class Average(Accumulator):
     """
-    Creates a $avg expression.
+    Abstration of MongoDB $avg operator that returns the average value of numeric values.
 
     Attributes
-    ------------------------
-        - expression : Any valid expression
-
+    ----------
+    expression : Any valid expression
+
+    Online MongoDB documentation:
+    -----------------------------
+    Returns the average value of the numeric values.
+    $avg ignores non-numeric values.
+    $avg is available in these stages:
+        * $addFields (Available starting in MongoDB 3.4)
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $match stage that includes an $expr expression
+        * $project
+        * $replaceRoot (Available starting in MongoDB 3.4)
+        * $replaceWith (Available starting in MongoDB 4.2)
+        * $set (Available starting in MongoDB 4.2)
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    In MongoDB 3.2 and earlier, $avg is available in the $group stage only.
+
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/avg/#mongodb-group-grp.-avg)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/accumulators/count.py b/src/monggregate/operators/accumulators/count.py
@@ -49,8 +49,22 @@
 
 class Count(Accumulator):
     """
-    Creates a $count expression.
-
+    Abstration of MongoDB $count operator that returns the number of documents in a group.
+
+    Online MongoDB documentation:
+    -----------------------------
+    Returns the number of documents in a group.
+    $count is available in these stages:
+
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $setWindowpyd.Fields (Available starting in MongoDB 5.0)
+
+    NOTE : Disambiguation
+    This page describes the $count aggregation accumulator. For the $count aggregation pipeline stage, [see $count (aggregation pipeline)](https://www.mongodb.com/docs/manual/reference/operator/aggregation/count/#mongodb-pipeline-pipe.-count)
+    
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/count-accumulator/#mongodb-group-grp.-count)
     """
 
 

diff --git a/src/monggregate/operators/accumulators/first.py b/src/monggregate/operators/accumulators/first.py
@@ -64,11 +64,28 @@
 
 class First(Accumulator):
     """
-    Creates a $first expression.
+    Abstration of MongoDB $first operator.
 
     Attributes
     ------------------------
         - expression, Expression : Any valid expression
+
+    Online MongoDB documentation:
+    ------------------------------
+    Returns the value that results from applying an expression to the first document in a group of documents. Only meaningful when documents are in a defined order.
+
+    $first is available in these stages:
+
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    NOTE: Disambiguation
+    This page describes the $first aggregation accumulator.
+    For the $first array operator, see $first (array operator)
+    
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/first/#mongodb-group-grp.-first)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/accumulators/last.py b/src/monggregate/operators/accumulators/last.py
@@ -56,12 +56,28 @@
 
 class Last(Accumulator):
     """
-    Creates a $last expression.
+    Abstraction of MongoDB $last operator.
 
     Attributes
     ------------------------
         - expression, Expression : Any valid expression
 
+    Online MongoDB documentation
+    ----------------------------
+    Returns the value that results from applying an expression to the last document in a group of documents. Only meaningful when documents are in a defined order.
+    
+    `$last` is available in these stages:
+
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    NOTE: Disambiguation
+    This page describes the $last aggregation accumulator.
+    For the `$last` array operator, see $last (array operator)
+
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/last/#mongodb-group-grp.-last)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/accumulators/max.py b/src/monggregate/operators/accumulators/max.py
@@ -81,11 +81,32 @@
 
 class Max(Accumulator):
     """
-    Creates a $max expression.
+    Abstraction of MongoDB $max operator.
 
     Attributes
     ---------------------
         - expression, Expression : Any valid expression
+
+    Online MongoDB documentation
+    ----------------------------
+    Returns the maximum value.
+    $max compares both value and type, using the specified BSON comparison order for values of different types.
+    
+    $max is available in these stages:
+        * $addFields (Available starting in MongoDB 3.4)
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $match stage that includes an $expr expression
+        * $project
+        * $replaceRoot (Available starting in MongoDB 3.4)
+        * $replaceWith (Available starting in MongoDB 4.2)
+        * $set (Available starting in MongoDB 4.2)
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    In MongoDB 3.2 and earlier, $max is available in the $group stage only.
+
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/max/#mongodb-group-grp.-max)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/accumulators/min.py b/src/monggregate/operators/accumulators/min.py
@@ -81,11 +81,32 @@
 
 class Min(Accumulator):
     """
-    Creates a $min expression.
+    Abstraction of MongoDB $min operator.
 
     Attributes
     ----------------------
         - expression, Expression : Any valid expression
+
+
+    Online MongoDB documentation
+    ----------------------------
+    Returns the minimum value.
+    $min compares both value and type, using the specified BSON comparison order for values of different types.
+
+    $min is available in these stages:
+        * $addFields (Available starting in MongoDB 3.4)
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $match stage that includes an $expr expression
+        * $project
+        * $replaceRoot (Available starting in MongoDB 3.4)
+        * $replaceWith (Available starting in MongoDB 4.2)
+        * $set (Available starting in MongoDB 4.2)
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    In MongoDB 3.2 and earlier, $min is available in the $group stage only.
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/min/#mongodb-group-grp.-min)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/accumulators/push.py b/src/monggregate/operators/accumulators/push.py
@@ -33,12 +33,23 @@
 
 class Push(Accumulator):
     """
-    Creates a $push expression.
+    Abstraction of MongoDB $push operator.
 
     Attributes
     -------------------
         - expression, Expression : Any valid expression
 
+    Online MongoDB documentation
+    ----------------------------
+    $push returns an array of all values that result from applying an expression to documents.
+
+    $push is available in these stages:
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/push/#mongodb-group-grp.-push)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/accumulators/sum.py b/src/monggregate/operators/accumulators/sum.py
@@ -90,12 +90,33 @@
 
 class Sum(Accumulator):
     """
-    Creates a $sum expression.
+    Abstraction of MongoDB $sum operator.
 
     Attributes
     -----------------------
         - operands, list[Expression] : Any valid list of expressions
         - operand, Expression : Any valid expression
+        
+    Online MongoDB documentation
+    ----------------------------
+    Calculates and returns the collective sum of numeric values.
+    $sum ignores non-numeric values.
+
+    $sum is available in these stages:
+        * $addFields (Available starting in MongoDB 3.4)
+        * $bucket
+        * $bucketAuto
+        * $group
+        * $match stage that includes an $expr expression
+        * $project
+        * $replaceRoot (Available starting in MongoDB 3.4)
+        * $replaceWith (Available starting in MongoDB 4.2)
+        * $set (Available starting in MongoDB 4.2)
+        * $setWindowFields (Available starting in MongoDB 5.0)
+
+    In MongoDB 3.2 and earlier, $sum is available in the $group stage only.
+    
+    [Source](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sum/#mongodb-group-grp.-sum)
     """
 
     expression : Any

diff --git a/src/monggregate/operators/arithmetic/add.py b/src/monggregate/operators/arithmetic/add.py
@@ -8,8 +8,7 @@
 
 Definition
 -------------------
-$add
-Adds numbers together or adds numbers and a date. If one of the arguments is a date, 
+$add adds numbers together or adds numbers and a date. If one of the arguments is a date, 
 $add treats the other arguments as milliseconds to add to the date.
 
 The $add expression has the following syntax:
@@ -26,15 +25,28 @@
 
 class Add(ArithmeticOperator):
     """
-    Creates a $add expression
+    Abstraction of MongoDB $add operator which adds numbers together of adds numbers and a date.
 
     Attributes
     -------------------
         - expressions, list[Any] : list of valid expressions,
                                    each expression must resolve to either 
                                    all numbers or to numbers and a date
             
+    Online MongoDB documentation
+    ----------------------------
+    $add adds numbers together or adds numbers and a date. If one of the 
+    arguments is a date, $add treats the other arguments as milliseconds 
+    to add to the date.
+
+    The $add expression has the following syntax:
+
+        >>> { $add: [ <expression1>, <expression2>, ... ] }
+
+    The arguments can be any valid expression 
+    as long as they resolve to either all numbers or to numbers and a date. For more information on expressions, see Expressions.
     
+    [Source](https://docs.mongodb.com/manual/reference/operator/aggregation/add/#mongodb-expression-exp.-add)
     """
 
 

diff --git a/src/monggregate/operators/arithmetic/divide.py b/src/monggregate/operators/arithmetic/divide.py
@@ -27,14 +27,29 @@
 
 class Divide(ArithmeticOperator):
     """
-    Creates a $divide expression
+    Abstraction of MongoDB $divide operator which divides one number by
+    another and returns the result.
 
     Attributes
     -------------------
         - numerator, Any : the numerator of the division
         - denominator, Any : the denominator of the division
-            
+
+    Online MongoDB documentation
+    ----------------------------
+    Divides one number by another and returns the result. Pass the arguments to 
+    $divide in an array.
+
+    The $divide expression has the following syntax:
+
+        >>> { $divide: [ <expression1>, <expression2>] }
+
+    The first argument is the dividend, and the second argument is the divisor; i.e. 
+    the first argument is divided by the second argument.
+
+    The arguments can be any valid expression as long as they resolve to numbers. For more information on expressions, see Expressions.
     
+    [Source](https://docs.mongodb.com/manual/reference/operator/aggregation/divide/#mongodb-expression-exp.-divide)
     """
 
 

diff --git a/src/monggregate/operators/arithmetic/multiply.py b/src/monggregate/operators/arithmetic/multiply.py
@@ -26,13 +26,26 @@
 
 class Multiply(ArithmeticOperator):
     """
-    Creates a $multiply expression
+    Abstraction of MongoDB $multiply operator which multiplies numbers 
+    together and returns the result.
 
     Attributes
     -------------------
         - expressions, list[Any] : list of valid expressions
-            
     
+    Online MongoDB documentation
+    ----------------------------
+    Multiplies numbers together and returns the result. Pass the arguments to 
+    $multiply in an array.
+
+    The $multiply expression has the following syntax:
+
+        >>> { $multiply: [ <expression1>, <expression2>] }
+
+    The arguments can be any valid expression as long as they resolve to numbers. 
+    For more information on expressions, see Expressions.
+    
+    [Source](https://docs.mongodb.com/manual/reference/operator/aggregation/multiply/#mongodb-expression-exp.-multiply)
     """
 
 

diff --git a/src/monggregate/operators/arithmetic/pow.py b/src/monggregate/operators/arithmetic/pow.py
@@ -44,14 +44,28 @@
 
 class Pow(ArithmeticOperator):
     """
-    Creates a $pow expression
+    Abstraction of MongoDB $pow operator which raises a number to the specified exponent.
 
     Attributes
     -------------------
         - number, Any : the numerator of the division
         - exponent, Any : the denominator of the division
             
-    
+    Online MongoDB documentation
+    ----------------------------
+    Raises a number to the specified exponent and returns the result. 
+    $pow has the following syntax:.
+
+    The $pow expression has the following syntax:
+
+        >>> { $pow: [ <expression1>, <expression2>] }
+
+    The <number> expression can be any valid expression as long as it resolves to a number.
+
+    The <exponent> expression can be any valid expression as long as it resolves to a number.
+
+    You cannot raise 0 to a negative exponent.
+    [Source](https://docs.mongodb.com/manual/reference/operator/aggregation/pow/#mongodb-expression-exp.-pow)
     """