Documented Criteria DSL operators.

guide/criteria.md

@@ -4,6 +4,8 @@ Criteria
 Adds a Criteria DSL for creating [ReactiveMongo](https://github.com/ReactiveMongo/ReactiveMongo) queries
 
 
+## Overview
+
 ### Original Query Syntax
 
 The `reactivemongo.api.collections.GenericCollection` type provides the `find` method used to find documents matching a criteria.  It is this interaction which the DSL targets.  Originally, providing a selector to `find` had an interaction similar to:
@@ -38,3 +40,114 @@ This section details the functionality either currently or planned to be support
 - Ability to ''type check'' query constraints by specifying a Scala type. *TBD*
 - Define and add support for an [EDSL](http://scalamacros.org/usecases/advanced-domain-specific-languages.html) specific to [projections](https://github.com/ReactiveMongo/ReactiveMongo/blob/master/driver/src/test/scala/CommonUseCases.scala). *TBD*
 
+
+## Operators
+
+When using the Criteria DSL, the fact that the operators adhere to the expectations of both programmers and Scala precedences, most uses will "just work."  For example, explicitly defining grouping is done with parentheses, just as you would do with any other bit of Scala code.
+
+For the purposes of the operator API reference, assume the following code is in scope:
+
+```scala
+import reactivemongo.extensions.dsl.criteria.Untyped._
+```
+
+### Comparison Operators
+
+With the majority of comparison operators, keep in mind that the definition of their ordering is dependent on the type involved.  For example, strings will use lexigraphical ordering whereas numbers use natural ordering.
+
+* **===**, **@==** Matches properties based on value equality.
+
+```scala
+criteria.aProperty === "value"
+```
+
+* **<>**, **=/=** Matches properties which do not have the given value.
+
+```scala
+criteria.aProperty <> "value"
+```
+
+* **<** Matches properties which compare "less than" a given value.
+
+```scala
+criteria.aNumber < 99
+```
+
+* **<=** Matches properties which compare "less than or equal to" a given value.
+
+```scala
+criteria.aNumber <= 99
+```
+
+* **>** Matches properties which compare "greater than" a given value.
+
+```scala
+criteria.aProperty > "Alice"
+```
+
+* **>=** Matches properties which compare "greater than or equal to" a given value.
+
+```scala
+criteria.aNumber >= 100
+```
+
+### Existence Operators
+
+* **exists** Matches any document which has the specified field.
+
+```scala
+criteria.aProperty.exists
+```
+
+* **in** Matches properties which are arrays and have one of the given values.
+
+```scala
+criteria.anArray.in (1, 2, 3, 4, 5)
+```
+
+* **all** Matches array properties which contain all of the given values.
+
+```scala
+criteria.strings.all ("hello", "world")
+```
+
+### String Operators
+
+* **=~** Matches a string property which satisfies the given regular expression `String`.
+
+```scala
+criteria.aProperty =~ """^(value)|(someting\s+else)"""
+```
+
+* **!~** Matches a string property which does _not_ satisfy the given regular expression `String`.
+
+```scala
+criteria.aProperty !~ """\d+"""
+```
+
+### Logical Operators
+
+* **!** The unary not operator provides logical negation of an `Expression`.
+
+```scala
+!(criteria.aProperty === "value")
+```
+
+* **&&** Defines logical conjunction (''AND'').
+
+```scala
+criteria.aProperty === "value" && criteria.another > 0
+```
+
+* **!&&** Defines negation of conjunction (''NOR'').
+
+```scala
+criteria.aProperty === "value" !&& criteria.aProperty @== "other value"
+```
+
+* **||** Defines logical disjunction (''OR'').
+
+```scala
+criteria.aProperty === "value" || criteria.aProperty === "other value"
+```
+