Improve `@arangodb` docs

Documentation/Books/Manual/Appendix/JavaScriptModules/Actions.mdpp

@@ -1,6 +1,8 @@
 Module "actions"
 ================
 
+`const actions = require('@arangodb/actions')`
+
 The action module provides the infrastructure for defining low-level HTTP actions.
 
 If you want to define HTTP endpoints in ArangoDB you should probably use the [Foxx microservice framework](../../Foxx/README.md) instead.

Documentation/Books/Manual/Appendix/JavaScriptModules/ArangoDB.mdpp

@@ -0,0 +1,70 @@
+ArangoDB Module
+===============
+
+`const arangodb = require('@arangodb')`
+
+**Note**: This module should not be confused with the [`arangojs` JavaScript driver](https://github.com/arangodb/arangojs) which can be used to access ArangoDB from outside the database. Although the APIs share similarities and the functionality overlaps, the two are not compatible with each other and can not be used interchangeably.
+
+The `db` object
+---------------
+
+`arangodb.db`
+
+The `db` object represents the current database and lets you access collections and run queries. For more information see the [db object reference](../References/DBObject.html).
+
+**Examples**
+
+```js
+const db = require('@arangodb').db;
+
+const thirteen = db._query('RETURN 5 + 8').next();
+```
+
+The `aql` template string handler
+---------------------------------
+
+`arangodb.aql`
+
+The `aql` function is a JavaScript template string handler. It can be used to write complex AQL queries as multi-line strings without having to worry about bindVars and the distinction between collections and regular parameters.
+
+To use it just prefix a JavaScript template string (the ones with backticks instead of quotes) with its import name (e.g. `aql`) and pass in variables like you would with a regular template string. The string will automatically be converted into an object with `query` and `bindVars` attributes which you can pass directly to `db._query` to execute. If you pass in a collection it will be automatically recognized as a collection reference and handled accordingly.
+
+To find out more about AQL see the [AQL documentation](../../../AQL/index.html).
+
+**Examples**
+
+```js
+const aql = require('@arangodb').aql;
+
+const filterValue = 23;
+const mydata = db._collection('mydata');
+const result = db._query(aql`
+  FOR d IN ${mydata}
+  FILTER d.num > ${filterValue}
+  RETURN d
+`).toArray();
+```
+
+The `errors` object
+-------------------
+
+`arangodb.errors`
+
+This object provides useful objects for each error code ArangoDB might use in `ArangoError` errors. This is helpful when trying to catch specific errors raised by ArangoDB, e.g. when trying to access a document that does not exist. Each object has a `code` property corresponding to the `errorNum` found on `ArangoError` errors.
+
+For a complete list of the error names and codes you may encounter see the [appendix on error codes](../ErrorCodes.md).
+
+**Examples**
+
+```js
+const errors = require('@arangodb').errors;
+
+try {
+  someCollection.document('does-not-exist');
+} catch (e) {
+  if (e.isArangoError && e.errorNum === errors.ERROR_ARANGO_DOCUMENT_NOT_FOUND.code) {
+    throw new Error('Document does not exist');
+  }
+  throw new Error('Something went wrong');
+}
+```

Documentation/Books/Manual/Appendix/JavaScriptModules/Console.mdpp

@@ -1,10 +1,9 @@
 Console Module
 ==============
 
-`require('console')`
+`global.console === require('console')`
 
-The implementation follows the CommonJS specification
-[Console](http://wiki.commonjs.org/wiki/Console).
+**Note**: You don't need to load this module directly. The `console` object is globally defined throughout ArangoDB and provides access to all functions in this module.
 
 ### console.assert
 

Documentation/Books/Manual/Appendix/JavaScriptModules/FileSystem.mdpp

@@ -1,10 +1,11 @@
 Filesystem Module
 =================
 
-`require('fs')`
+`const fs = require('fs')`
 
-The implementation tries to follow the CommonJS specification where possible.
-[Filesystem/A/0](http://wiki.commonjs.org/wiki/Filesystem/A/0).
+The implementation tries to follow the CommonJS
+[Filesystem/A/0](http://wiki.commonjs.org/wiki/Filesystem/A/0)
+specification where possible.
 
 Single File Directory Manipulation
 ----------------------------------

Documentation/Books/Manual/Appendix/JavaScriptModules/Queries.mdpp

@@ -1,10 +1,13 @@
-Module "queries"
-================
+Queries Module
+==============
+
+`const queries = require('@arangodb/aql/queries')`
 
 The query module provides the infrastructure for working with currently running AQL queries via arangosh.
 
+Properties
+----------
 
-### Properties
 `queries.properties()` Returns the servers current query tracking configuration; we change the slow query threshold to get better results:
 
     @startDocuBlockInline QUERY_01_properyOfQueries
@@ -15,8 +18,8 @@ The query module provides the infrastructure for working with currently running
     @END_EXAMPLE_ARANGOSH_OUTPUT
     @endDocuBlock QUERY_01_properyOfQueries
 
-
-### Currently running queries
+Currently running queries
+-------------------------
 
 We [create a task](Tasks.md) 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):
@@ -44,7 +47,9 @@ uses resources, you may want to increase `period` (and not forget to remove it..
     @endDocuBlock QUERY_02_listQueries
 The function returns the currently running AQL queries as an array.
 
-### Slow queries
+Slow queries
+------------
+
 The function returns the last AQL queries that exceeded the slow query threshold as an array:
 
     @startDocuBlockInline QUERY_03_listSlowQueries
@@ -54,7 +59,9 @@ The function returns the last AQL queries that exceeded the slow query threshold
     @END_EXAMPLE_ARANGOSH_OUTPUT
     @endDocuBlock QUERY_03_listSlowQueries
 
-### Clear slow queries
+Clear slow queries
+------------------
+
 Clear the list of slow AQL queries:
 
     @startDocuBlockInline QUERY_04_clearSlowQueries
@@ -65,8 +72,9 @@ Clear the list of slow AQL queries:
     @END_EXAMPLE_ARANGOSH_OUTPUT
     @endDocuBlock QUERY_04_clearSlowQueries
 
+Kill
+----
 
-### Kill
 Kill a running AQL query:
 
     @startDocuBlockInline QUERY_05_killQueries
@@ -80,7 +88,3 @@ Kill a running AQL query:
     queries.kill(runningQueries[0].id);
     @END_EXAMPLE_ARANGOSH_OUTPUT
     @endDocuBlock QUERY_05_killQueries
-
-
-
-

Documentation/Books/Manual/Appendix/JavaScriptModules/README.mdpp

@@ -77,6 +77,8 @@ ArangoDB Specific Modules
 
 There are a large number of ArangoDB-specific modules using the `@arangodb` namespace, mostly for internal use by ArangoDB itself. The following however are noteworthy:
 
+* [@arangodb](ArangoDB.md) provides direct access to the database and its collections.
+
 * [@arangodb/crypto](Crypto.md) provides various cryptography functions including hashing algorithms.
 
 * [@arangodb/foxx](../../Foxx/README.md) is the namespace providing the various building blocks of the Foxx microservice framework.

Documentation/Books/Manual/Appendix/JavaScriptModules/Request.mdpp

@@ -1,10 +1,10 @@
-Module "request"
-================
+Request Module
+==============
+
+`const request = require('@arangodb/request')`
 
 The request module provides the functionality for making HTTP requests.
 
-`require('@arangodb/request')`
-
 Making HTTP requests
 --------------------
 

Documentation/Books/Manual/Appendix/JavaScriptModules/Tasks.mdpp

@@ -1,7 +1,13 @@
 Task Management
 ===============
 
-### Introduction to Task Management in ArangoDB
+`const tasks = require('@arangodb/tasks')`
+
+**Note**: If you are trying to schedule tasks in Foxx you should
+consider using the [Foxx queues module](../../Foxx/Scripts.md#Queues) instead,
+which provides a more high-level API that also persists tasks across reboots.
+
+## Introduction to Task Management in ArangoDB
 
 ArangoDB can execute user-defined JavaScript functions as one-shot
 or periodic tasks. This functionality can be used to implement timed
@@ -29,7 +35,7 @@ Tasks registered in ArangoDB will be executed until the server
 gets shut down or restarted. After a restart of the server, any 
 user-defined one-shot or periodic tasks will be lost. 
 
-### Commands for Working with Tasks
+## Commands for Working with Tasks
 
 ArangoDB provides the following commands for working with tasks.
 All commands can be accessed via the *tasks* module, which can be
@@ -41,7 +47,7 @@ Please note that the *tasks* module is available inside the ArangoDB
 server only. It cannot be used from the ArangoShell or ArangoDB's web
 interface.
 
-### Register a task
+## Register a task
 
 To register a task, the JavaScript snippet or function needs to be
 specified in addition to the execution frequency. Optionally, a task
@@ -134,7 +140,7 @@ tasks.register({
 **Note**: When specifying an *offset* value of 0, ArangoDB will internally add 
 a very small value to the offset so will be slightly greater than zero.
 
-### Unregister a task
+## Unregister a task
 
 After a task has been registered, it can be unregistered using its id:
 
@@ -146,7 +152,7 @@ tasks.unregister("mytask-1");
 Note that unregistering a non-existing task will throw an exception.
 
 
-### List all tasks
+## List all tasks
 
 To get an overview of which tasks are registered, there is the *get* 
 method. If the *get* method is called without any arguments, it will

Documentation/Books/Manual/Appendix/JavaScriptModules/WAL.mdpp

@@ -1,6 +1,8 @@
 Write-ahead log
 ===============
 
+`const wal = require('internal').wal`
+
 This module provides functionality for administering the write-ahead logs.
 
 ### Configuration

Documentation/Books/Manual/Foxx/Modules.mdpp

@@ -8,68 +8,11 @@ Additionally there are modules providing some level of compatibility with Node.j
 The `@arangodb` module
 ----------------------
 
-This module provides access to various ArangoDB internals as well as three of the most important exports necessary to work with the database in Foxx:
+`require('@arangodb')`
 
-### The `db` object
+This module provides access to various ArangoDB internals as well as three of the most important exports necessary to work with the database in Foxx: `db`, `aql` and `errors`.
 
-`require('@arangodb').db`
-
-The `db` object represents the current database and lets you access collections and run queries. For more information see the [db object reference](../Appendix/References/DBObject.html).
-
-**Examples**
-
-```js
-const db = require('@arangodb').db;
-
-const thirteen = db._query('RETURN 5 + 8')[0];
-```
-
-### The `aql` template string handler
-
-`require('@arangodb').aql`
-
-The `aql` function is a JavaScript template string handler. It can be used to write complex AQL queries as multi-line strings without having to worry about bindVars and the distinction between collections and regular parameters.
-
-To use it just prefix a JavaScript template string (the ones with backticks instead of quotes) with its import name (e.g. `aql`) and pass in variables like you would with a regular template string. The string will automatically be converted into an object with `query` and `bindVars` attributes which you can pass directly to `db._query` to execute. If you pass in a collection it will be automatically recognized as a collection reference and handled accordingly.
-
-To find out more about AQL see the [AQL documentation](../../AQL/index.html).
-
-**Examples**
-
-```js
-const aql = require('@arangodb').aql;
-
-const filterValue = 23;
-const mydata = db._collection('mydata');
-const result = db._query(aql`
-  FOR d IN ${mydata}
-  FILTER d.num > ${filterValue}
-  RETURN d
-`);
-```
-
-### The `errors` object
-
-`require('@arangodb').errors`
-
-This object provides useful objects for each error code ArangoDB might use in `ArangoError` errors. This is helpful when trying to catch specific errors raised by ArangoDB, e.g. when trying to access a document that does not exist. Each object has a `code` property corresponding to the `errorNum` found on `ArangoError` errors.
-
-For a complete list of the error names and codes you may encounter see the [appendix on error codes](../Appendix/ErrorCodes.md).
-
-**Examples**
-
-```js
-const errors = require('@arangodb').errors;
-
-try {
-  mydata.document('does-not-exist');
-} catch (e) {
-  if (e.isArangoError && e.errorNum === errors.ERROR_ARANGO_DOCUMENT_NOT_FOUND.code) {
-    res.throw(404, 'Document does not exist');
-  }
-  res.throw(500, 'Something went wrong', e);
-}
-```
+You can find a full description of this module [in the ArangoDB module appendix](../Appendix/JavaScriptModules/ArangoDB.md).
 
 The `@arangodb/request` module
 ------------------------------

Documentation/Books/Manual/Foxx/Scripts.mdpp

@@ -116,6 +116,8 @@ if (textsCollection) {
 Queues
 ------
 
+`const queues = require('@arangodb/foxx/queues')`
+
 Foxx allows defining job queues that let you perform slow or expensive actions asynchronously. These queues can be used to send e-mails, call external APIs or perform other actions that you do not want to perform directly or want to retry on failure.
 
 @startDocuBlock foxxQueues

Documentation/Books/Manual/SUMMARY.md

@@ -216,6 +216,7 @@
     * [db](Appendix/References/DBObject.md)
     * [collection](Appendix/References/CollectionObject.md)
   * [JavaScript Modules](Appendix/JavaScriptModules/README.md)
+    * [@arangodb](Appendix/JavaScriptModules/ArangoDB.md)
     * [console](Appendix/JavaScriptModules/Console.md)
     * [crypto](Appendix/JavaScriptModules/Crypto.md)
     * [fs](Appendix/JavaScriptModules/FileSystem.md)