From 9038aa3da97dfdcb5fda2609e20db9ccfa07ee28 Mon Sep 17 00:00:00 2001
From: Willi Goesgens <willi@arangodb.com>
Date: Tue, 11 Aug 2015 16:13:35 +0200
Subject: [PATCH] Add examples to the query administration.

---
 .../Books/Users/ModuleQueries/README.mdpp     | 80 +++++++++++++------
 1 file changed, 56 insertions(+), 24 deletions(-)

diff --git a/Documentation/Books/Users/ModuleQueries/README.mdpp b/Documentation/Books/Users/ModuleQueries/README.mdpp
index 7209e15a18..a635e0015d 100644
--- a/Documentation/Books/Users/ModuleQueries/README.mdpp
+++ b/Documentation/Books/Users/ModuleQueries/README.mdpp
@@ -1,42 +1,74 @@
 !CHAPTER Module "queries"
-The query module provides the infrastructure for defining HTTP queries.
+The query module provides the infrastructure for working with currently running AQL queries via arangosh.
+
+
+!SUBSECTION Properties
+`queries.properties()` Returns the servers current query tracking configuration; we change the slow query threshhold to get better results:
+
+    @startDocuBlockInline QUERY_01_properyOfQueries
+    @EXAMPLE_ARANGOSH_OUTPUT{QUERY_01_properyOfQueries}
+    ~var queries = require("org/arangodb/aql/queries");
+    queries.properties();
+    queries.properties({slowQueryThreshold: 1});
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock QUERY_01_properyOfQueries
+
 
 !SUBSECTION Currently running queries
+We [create a task](../ModuleTasks/index.html) that spawns queries, so we have nice output. Since this task
+uses resources, you may want to increase `period` (and not forget to remove it... afterwards):
 
-`require("org/arangodb/aql/queries").current();`
-
+    @startDocuBlockInline QUERY_02_listQueries
+    @EXAMPLE_ARANGOSH_OUTPUT{QUERY_02_listQueries}
+    var queries = require("org/arangodb/aql/queries");
+    var tasks = require("org/arangodb/tasks");
+    |tasks.register({
+    |  id: "mytask-1",
+    |  name: "this is a sample task to spawn slow aql queries",
+    |  period: 2,
+    |  command: "require('internal').db._query('FOR sleepLoooong IN 1..5 LET sleepLoooonger = SLEEP(1) RETURN sleepLoooong');"
+    });
+    ~require("internal").wait(5)
+    queries.current();
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock QUERY_02_listQueries
 The function returns the currently running AQL queries as an array.
 
 !SUBSECTION Slow queries
+The function returns the last AQL queries that exceeded the slow query threshold as an array:
 
-`require("org/arangodb/aql/queries").slow();`
-
-The function returns the last AQL queries that exceeded the slow query threshold as an array.
+    @startDocuBlockInline QUERY_03_listSlowQueries
+    @EXAMPLE_ARANGOSH_OUTPUT{QUERY_03_listSlowQueries}
+    ~var queries = require("org/arangodb/aql/queries");
+    queries.slow();
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock QUERY_03_listSlowQueries
 
 !SUBSECTION Clear slow queries
+Clear the list of slow AQL queries:
 
-`require("org/arangodb/aql/queries").clearSlow();`
+    @startDocuBlockInline QUERY_04_clearSlowQueries
+    @EXAMPLE_ARANGOSH_OUTPUT{QUERY_04_clearSlowQueries}
+    ~var queries = require("org/arangodb/aql/queries");
+    queries.clearSlow();
+    queries.slow();
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock QUERY_04_clearSlowQueries
 
-Clears the list of slow AQL queries.
-
-!SUBSECTION Properties
-
-`require("org/arangodb/aql/queries").properties();`
-
-Returns the current query tracking configuration.
 
 !SUBSECTION Kill
+Kill a running AQL query:
+
+    @startDocuBlockInline QUERY_05_killQueries
+    @EXAMPLE_ARANGOSH_OUTPUT{QUERY_05_killQueries}
+    ~var queries = require("org/arangodb/aql/queries");
+    ~var tasks = require("org/arangodb/tasks");
+    var oneQuery = queries.current()[1];
+    queries.kill(oneQuery.id);
+    tasks.unregister("mytask-1");
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock QUERY_05_killQueries
 
-`require("org/arangodb/aql/queries").kill();`
-
-Kills a running AQL query.
 
 
 
-var tasks = require("org/arangodb/tasks");
-tasks.register({
-  id: "mytask-1",
-  name: "this is a snippet task",
-  period: 15,
-  command: "require('console').log('hello from snippet task');"
-});
\ No newline at end of file