From 81c54fd64e9eb76133fab01d0e95fbfe49665637 Mon Sep 17 00:00:00 2001
From: Jan Steemann <jan@arangodb.com>
Date: Thu, 10 Sep 2015 17:39:54 +0200
Subject: [PATCH] fixed documentation issues reported by @CoDEmanX

---
 Documentation/Books/Users/Aql/Invoke.mdpp       | 14 ++++++++++++--
 .../Books/Users/NewFeatures/NewFeatures27.mdpp  | 17 ++++++++++++-----
 2 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/Documentation/Books/Users/Aql/Invoke.mdpp b/Documentation/Books/Users/Aql/Invoke.mdpp
index 694acdecba..1aa01e1883 100644
--- a/Documentation/Books/Users/Aql/Invoke.mdpp
+++ b/Documentation/Books/Users/Aql/Invoke.mdpp
@@ -41,8 +41,18 @@ a template string generator function named *aqlQuery*:
     @END_EXAMPLE_ARANGOSH_OUTPUT
     @endDocuBlock 02_workWithAQL_aqlQuery
 
-Note: data-modifying AQL queries normally not return a result (unless the AQL query 
-contains a *RETURN* statement). When not using a *RETURN* statement in the query, the 
+Arbitrary JavaScript expressions can be used in queries that are generated with the 
+*aqlQuery* template string generator. Collection objects are handled automatically:
+
+    @startDocuBlockInline 02_workWithAQL_aqlQueryCollection
+    @EXAMPLE_ARANGOSH_OUTPUT{02_workWithAQL_aqlQueryCollection}
+      var key = 'testKey';
+      db._query(aqlQuery`FOR doc IN ${ db.mycollection } RETURN doc`).toArray();
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock 02_workWithAQL_aqlQueryCollection
+
+Note: data-modification AQL queries normally do not return a result (unless the AQL query 
+contains an extra *RETURN* statement). When not using a *RETURN* statement in the query, the 
 *toArray* method will return an empty array. 
 
 It is always possible to retrieve statistics for a query with the *getExtra* method:
diff --git a/Documentation/Books/Users/NewFeatures/NewFeatures27.mdpp b/Documentation/Books/Users/NewFeatures/NewFeatures27.mdpp
index 5174008b8b..d6d2e9734a 100644
--- a/Documentation/Books/Users/NewFeatures/NewFeatures27.mdpp
+++ b/Documentation/Books/Users/NewFeatures/NewFeatures27.mdpp
@@ -102,16 +102,16 @@ collections.
 !SUBSECTION RETURN DISTINCT
 
 To return unique values from a query, AQL now provides the `DISTINCT` keyword.
-It can used as a modifier for `RETURN` statements, as a shorter alternative to
+It can be used as a modifier for `RETURN` statements, as a shorter alternative to
 the already existing `COLLECT` statement.
 
 For example, the following query only returns distinct (unique) `status`
 attribute values from the collection:
 
-````
+```
     FOR doc IN collection
       RETURN DISTINCT doc.status
-````
+```
 
 `RETURN DISTINCT` is not allowed on the top-level of a query if there is no `FOR` 
 loop in front of it. `RETURN DISTINCT` is allowed in subqueries.
@@ -254,8 +254,15 @@ not require defining the bind parameter values separately:
     });
 ```
 
-Note that template strings are available in the JavaScript functions provided
-in ArangoDB to build queries, but aren't an AQL feature. AQL could always handle
+The `aqlQuery` template string generator will also handle collection objects
+automatically:
+
+```js
+    db._query(aqlQuery`FOR u IN ${ db.users } RETURN u.name`);
+```
+
+Note that while template strings are available in the JavaScript functions provided
+to build queries, they aren't a feature of AQL itself. AQL could always handle
 multiline query strings and provided bind parameters (`@...`) for separating
 the query string and the parameter values. The `aqlQuery` template string
 generator function will take care of this separation, too, but will do it