From 221165d4225d628fd8f54b40beba3327af55337e Mon Sep 17 00:00:00 2001
From: Nieve <nievegoor@gmail.com>
Date: Mon, 25 Apr 2016 22:16:55 +0200
Subject: [PATCH] Added documentation for compiled queries returning json
 strings

---
 .../documents/compiled_queries.md             | 37 ++++++++++++++++++-
 .../Linq/compiled_query_Tests.cs              |  8 ++++
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/documentation/documentation/documents/compiled_queries.md b/documentation/documentation/documents/compiled_queries.md
index ac6d5380de..341bcba677 100644
--- a/documentation/documentation/documents/compiled_queries.md
+++ b/documentation/documentation/documents/compiled_queries.md
@@ -48,6 +48,9 @@ To the best of our knowledge and testing, you may use any <[linkto:documentation
 * `OrderBy/OrderByDescending` etc.
 * `Count()`
 * `Any()`
+* `AsJson()`
+* `ToJsonArray()`
+* `ToJsonArrayAsync()`
 
 At this point (v0.9), the only limitations are:
 
@@ -81,10 +84,40 @@ A sample usage of this type of query is shown below:
 
 ## Querying for a single document
 
-Finally, if you are querying for a single document with no transformation, you can use this interface as a convenience:
+If you are querying for a single document with no transformation, you can use this interface as a convenience:
 
 <[sample:ICompiledQuery-for-single-doc]>
 
 And an example:
 
-<[sample:FindUserByAllTheThings]>
\ No newline at end of file
+<[sample:FindUserByAllTheThings]>
+
+
+
+## Querying for multiple results as Json
+
+To query for multiple results and have them returned as a Json string, you may run any query on your `IQueryable<T>` (be it ordering or filtering) and then simply finalize the query with `ToJsonArray();` like so:
+
+<[sample:CompiledToJsonArray]>
+
+If you wish to do it asynchronously, you can use the `ToJsonArrayAsync()` method.
+
+A sample usage of this type of query is shown below:
+
+<[sample:FindJsonOrderedUsersByUsername]>
+
+Note that the result has the documents comma separated and wrapped in angle brackets (as per the Json notation).
+
+
+
+## Querying for a single document
+
+Finally, if you are querying for a single document as json, you will need to prepend your call to `Single()`, `First()` and so on with a call to `AsJson()`:
+
+<[sample:CompiledAsJson]>
+
+And an example:
+
+<[sample:FindJsonUserByUsername]>
+
+(our ToJson method simply reuturns a string representation of the `User` instance in Json notation)
\ No newline at end of file
diff --git a/src/Marten.Testing/Linq/compiled_query_Tests.cs b/src/Marten.Testing/Linq/compiled_query_Tests.cs
index f04feca22c..2625a780bc 100644
--- a/src/Marten.Testing/Linq/compiled_query_Tests.cs
+++ b/src/Marten.Testing/Linq/compiled_query_Tests.cs
@@ -76,6 +76,7 @@ public void a_single_item_compiled_query_SingleOrDefault()
                 .ShouldBeNull();
         }
 
+        // SAMPLE: FindJsonUserByUsername
         [Fact]
         public void a_single_item_compiled_query_AsJson()
         {
@@ -84,7 +85,9 @@ public void a_single_item_compiled_query_AsJson()
             user.ShouldNotBeNull();
             user.ShouldBe(_user1.ToJson());
         }
+        // ENDSAMPLE
 
+        // SAMPLE: FindJsonOrderedUsersByUsername
         [Fact]
         public void a_sorted_list_compiled_query_AsJson()
         {
@@ -93,6 +96,7 @@ public void a_sorted_list_compiled_query_AsJson()
             user.ShouldNotBeNull();
             user.ShouldBe($"[{_user1.ToJson()},{_user5.ToJson()}]");
         }
+        // ENDSAMPLE
 
         [Fact]
         public void a_filtered_list_compiled_query_AsJson()
@@ -201,6 +205,7 @@ public Expression<Func<IQueryable<User>, User>> QueryIs()
     }
     // ENDSAMPLE
 
+    // SAMPLE: CompiledAsJson
     public class FindJsonUserByUsername : ICompiledQuery<User, string>
     {
         public string Username { get; set; }
@@ -212,7 +217,9 @@ public Expression<Func<IQueryable<User>, string>> QueryIs()
 
         }
     }
+    // ENDSAMPLE
 
+    // SAMPLE: CompiledToJsonArray
     public class FindJsonOrderedUsersByUsername : ICompiledQuery<User, string>
     {
         public string FirstName { get; set; }
@@ -225,6 +232,7 @@ public Expression<Func<IQueryable<User>, string>> QueryIs()
 
         }
     }
+    // ENDSAMPLE
 
     public class FindJsonUsersByUsername : ICompiledQuery<User, string>
     {