From 5f89f92ab276100c631ae219091cd5872cfdad2f Mon Sep 17 00:00:00 2001
From: Julien Buret <jburet@gmail.com>
Date: Thu, 15 Aug 2019 00:47:19 +0200
Subject: [PATCH] update doc

---
 .../org/litote/kmongo/MongoIterables.kt       | 11 +++++++----
 kmongo-kdoc/docs/extensions-overview.md       | 19 +++++++++++++++++++
 kmongo-kdoc/docs/object-mapping.md            |  4 ++--
 kmongo-kdoc/docs/quick-start.md               | 16 ++++++++--------
 4 files changed, 36 insertions(+), 14 deletions(-)

diff --git a/kmongo-core/src/main/kotlin/org/litote/kmongo/MongoIterables.kt b/kmongo-core/src/main/kotlin/org/litote/kmongo/MongoIterables.kt
index 2bb7b28d..2cf96ef6 100644
--- a/kmongo-core/src/main/kotlin/org/litote/kmongo/MongoIterables.kt
+++ b/kmongo-core/src/main/kotlin/org/litote/kmongo/MongoIterables.kt
@@ -39,21 +39,24 @@ private class NullHandlerSequence<T>(val sequence: Sequence<T>) : Sequence<T?> {
 }
 
 /**
- * Evaluates the iterable given the [sequenceChain] of Sequences.
+ * Evaluates the current [MongoIterable] given the [expression] of Sequences.
  *
  * The mongo cursor is closed before returning the result.
  *
+ * Sample:
  * ```
  *   col.find().evaluate {
- *     filter { it.name != "Joe" }.last()
+ *      //this is a sequence evaluation
+ *      //If the first row has a name like "Fred", only one row is loaded in memory!
+ *      filter { it.name != "Joe" }.first()
  *   }
  * ```
  */
-fun <T, R> MongoIterable<T>.evaluate(sequenceChain: Sequence<T>.() -> R): R {
+fun <T, R> MongoIterable<T>.evaluate(expression: Sequence<T>.() -> R): R {
     @Suppress("UNCHECKED_CAST")
     return iterator().run {
         use {
-            sequenceChain(
+            expression(
                 NullHandlerSequence(
                     generateSequence {
                         if (hasNext()) {
diff --git a/kmongo-kdoc/docs/extensions-overview.md b/kmongo-kdoc/docs/extensions-overview.md
index ad34a773..e81770b7 100644
--- a/kmongo-kdoc/docs/extensions-overview.md
+++ b/kmongo-kdoc/docs/extensions-overview.md
@@ -425,6 +425,25 @@ KMongo does not fix the "for" issue, but **does solve automatically memory leaks
 
 You have nothing to change in your code - just compile it with the KMongo dependency in the classpath! 
 
+### Use Sequences
+
+Unfortunately, The `MongoIterable.asSequence()` extension loads in memory all the documents returned by the query.
+This is because it's required to close the Mongo cursor in `asSequence()` method, in order to avoid a memory leak!
+
+KMongo provides an [evaluate](https://litote.org/kmongo/dokka/kmongo/org.litote.kmongo/com.mongodb.client.-mongo-iterable/evaluate.html) method that allows to load only the needed rows in memory,
+and also ensures that the cursor is closed:
+
+```kotlin
+val notJoe = col.find().evaluate {
+  //this is a sequence evaluation 
+  //If the first row has a name like "Fred", only one row is loaded in memory!
+  filter { it.name != "Joe" }.first()
+ }    
+                                                                   
+//If col.find() returns 1M of documents, they are all loaded in memory!
+col.find().asSequence().filter { it.name != "Joe" }.first()
+``` 
+
 ## withKMongo
 
 The recommended method, in order to setup KMongo, is to use `KMongo.createClient()`
diff --git a/kmongo-kdoc/docs/object-mapping.md b/kmongo-kdoc/docs/object-mapping.md
index 29cdf385..646385d8 100644
--- a/kmongo-kdoc/docs/object-mapping.md
+++ b/kmongo-kdoc/docs/object-mapping.md
@@ -44,14 +44,14 @@ You just have to add the ```kmongo-id``` dependency in the frontend to compile.
 <dependency>
   <groupId>org.litote.kmongo</groupId>
   <artifactId>kmongo-id</artifactId>
-  <version>3.10.2</version>
+  <version>3.11.0</version>
 </dependency>
 ```
 
 - or Gradle
 
 ```
-compile 'org.litote.kmongo:kmongo-id:3.10.2'
+compile 'org.litote.kmongo:kmongo-id:3.11.0'
 ```
 
 #### Id <> Json Jackson serialization
diff --git a/kmongo-kdoc/docs/quick-start.md b/kmongo-kdoc/docs/quick-start.md
index 7c9f0840..1f6e0e8e 100644
--- a/kmongo-kdoc/docs/quick-start.md
+++ b/kmongo-kdoc/docs/quick-start.md
@@ -12,14 +12,14 @@ If you don't know, start with the sync driver and add this dependency to your pr
 <dependency>
   <groupId>org.litote.kmongo</groupId>
   <artifactId>kmongo</artifactId>
-  <version>3.10.2</version>
+  <version>3.11.0</version>
 </dependency>
 ```
 
 - or Gradle
 
 ```
-compile 'org.litote.kmongo:kmongo:3.10.2'
+compile 'org.litote.kmongo:kmongo:3.11.0'
 ```
 
 And [start coding](#lets-start-coding)
@@ -37,14 +37,14 @@ For the asynchronous driver, reactive streams style, [Kotlin Coroutines](https:/
 <dependency>
   <groupId>org.litote.kmongo</groupId>
   <artifactId>kmongo-async</artifactId>
-  <version>3.10.2</version>
+  <version>3.11.0</version>
 </dependency>
 ```
 
 - or Gradle
 
 ```
-compile 'org.litote.kmongo:kmongo-async:3.10.2'
+compile 'org.litote.kmongo:kmongo-async:3.11.0'
 ```
 
 #### Kotlin Coroutines
@@ -55,14 +55,14 @@ compile 'org.litote.kmongo:kmongo-async:3.10.2'
 <dependency>
   <groupId>org.litote.kmongo</groupId>
   <artifactId>kmongo-coroutine</artifactId>
-  <version>3.10.2</version>
+  <version>3.11.0</version>
 </dependency>
 ```
 
 - or Gradle
 
 ```
-compile 'org.litote.kmongo:kmongo-coroutine:3.10.2'
+compile 'org.litote.kmongo:kmongo-coroutine:3.11.0'
 ```
 
 #### RxJava2
@@ -73,14 +73,14 @@ compile 'org.litote.kmongo:kmongo-coroutine:3.10.2'
 <dependency>
   <groupId>org.litote.kmongo</groupId>
   <artifactId>kmongo-rxjava2</artifactId>
-  <version>3.10.2</version>
+  <version>3.11.0</version>
 </dependency>
 ```
 
 - or Gradle
 
 ```
-compile 'org.litote.kmongo:kmongo-rxjava2:3.10.2'
+compile 'org.litote.kmongo:kmongo-rxjava2:3.11.0'
 ```
 
 ## Object Mapping Engine