fixed documentation errors

Documentation/Examples/foxx-doc-comment

@@ -0,0 +1,8 @@
+/** Get all foxxes
+  * 
+  * If you want to get all foxxes, please use this
+  * method to do that.
+  */
+app.get("/foxxes", function () {
+  // ...
+});

Documentation/Manual/NewFeatures13.md

@@ -81,7 +81,7 @@ another:
         db.accounts.update(account1, { amount : account1.amount - amount });
         db.accounts.update(account2, { amount : account2.amount + amount });
 
-        /* will commit the transaction and return the value true */
+        // will commit the transaction and return the value true 
         return true; 
       }
     });

Documentation/Scripts/generateTOC.py

@@ -42,6 +42,9 @@ argv.pop(0)
 
 DEBUG = False
 
+print '# Auto-generated aliases'
+print ''
+
 ################################################################################
 ### @brief parse file
 ################################################################################

Documentation/UserManual/AqlExamples.md

@@ -637,7 +637,7 @@ For example, to get the 3 `ageGroup`s with the most users in them:
       FILTER u.active == true 
       COLLECT ageGroup = FLOOR(u.age / 5) * 5 INTO group 
       LET numUsers = LENGTH(group) 
-      FILTER numUsers > 2 /* group must contain at least 3 users in order to qualify */
+      FILTER numUsers > 2 // group must contain at least 3 users in order to qualify 
       SORT numUsers DESC 
       LIMIT 0, 3 
       RETURN { 

Documentation/UserManual/Arangosh.md

@@ -121,16 +121,14 @@ You can use this to define your own extra variables and functions that you need
 For example, you could put the following into the `.arangosh.rc` file in your home
 directory:
 
-    /* var keyword omitted intentionally,
-       otherwise "timed" would not survive the scope of this script */
+    // var keyword omitted intentionally,
+    // otherwise "timed" would not survive the scope of this script
     timed = function (cb) {
       var internal = require("internal");
       var start = internal.time();
-
       cb();
-
       internal.print("execution took: ", internal.time() - start);
-    }
+    };
 
 This will make a function named `timed` available in _arangosh_ in the global scope.
 

Documentation/UserManual/Foxx.md

@@ -301,14 +301,7 @@ If you now want to document your route, you can use JSDoc style comments (a
 multiline comment block with the first line starting with `/**` instead 
 of `/*`) above your routes to do that:
 
-    /** Get all Foxes
-     * 
-     * If you want to get all foxes, please use this
-     * method to do that.
-     */
-    app.get("/foxes", function () {
-      //...
-    });
+@verbinclude foxx-doc-comment
 
 The first line will be treated as a summary (For optical reasons in the 
 produced documentation, the summary is restricted to 60 characters). All 

Documentation/UserManual/Transactions.md

@@ -113,7 +113,7 @@ attribute:
         write: "users"
       },
       action: function () {
-        /* all operations go here */
+        // all operations go here 
       }
     });
 
@@ -126,7 +126,7 @@ of a Javascript function:
       collections: {
         write: "users"
       },
-      action: "function () { /* all operations go here */ }"
+      action: "function () { doSomething(); }"
     });
 
 Please note that any operations specified in `action` will be executed on the 
@@ -161,7 +161,7 @@ be thrown and not caught inside the transaction:
         var db = require("internal").db;
         db.users.save({ _key: "hello" });
 
-        /* will abort and roll back the transaction */
+        // will abort and roll back the transaction 
         throw "doh!";
       }
     });
@@ -180,7 +180,7 @@ case, the user can return any legal Javascript value from the function:
         var db = require("internal").db;
         db.users.save({ _key: "hello" });
 
-        /* will commit the transaction and return the value "hello" */
+        // will commit the transaction and return the value "hello" 
         return "hello"; 
       }
     });
@@ -195,7 +195,7 @@ The `c1` collection needs to be declared in the `write` attribute of the
 The `action` attribute contains the actual transaction code to be executed.
 This code contains all data modification operations (3 in this example).
 
-    /* setup */
+    // setup
     db._create("c1");
 
     db._executeTransaction({
@@ -210,13 +210,13 @@ This code contains all data modification operations (3 in this example).
       }
     });
 
-    db.c1.count(); /* 3 */
+    db.c1.count(); // 3 
 
 
 Aborting the transaction by throwing an exception in the `action` function
 will revert all changes, so as if the transaction never happened:
     
-    /* setup */
+    // setup
     db._create("c1");
 
     db._executeTransaction({
@@ -226,22 +226,22 @@ will revert all changes, so as if the transaction never happened:
       action: function () {
         var db = require("internal").db;
         db.c1.save({ _key: "key1" });
-        db.c1.count(); /* 1 */
+        db.c1.count(); // 1 
 
         db.c1.save({ _key: "key2" });
-        db.c1.count(); /* 2 */
+        db.c1.count(); // 2 
 
         throw "doh!";
       }
     });
 
-    db.c1.count(); /* 0 */
+    db.c1.count(); // 0 
 
 
 The automatic rollback is also executed when an internal exception is thrown 
 at some point during transaction execution:
 
-    /* setup */
+    // setup 
     db._create("c1");
 
     db._executeTransaction({
@@ -252,33 +252,33 @@ at some point during transaction execution:
         var db = require("internal").db;
         db.c1.save({ _key: "key1" });
         
-        /* will throw duplicate a key error, not explicitly requested by the user */
+        // will throw duplicate a key error, not explicitly requested by the user 
         db.c1.save({ _key: "key1" });  
 
-        /* we'll never get here... */
+        // we'll never get here... 
       }
     });
 
-    db.c1.count(); /* 0 */
+    db.c1.count(); // 0 
 
 
 As required by the *consistency* principle, aborting or rolling back a 
 transaction will also restore secondary indexes to the state at transaction
 start. The following example using a cap constraint should illustrate that:
 
-    /* setup */
+    // setup 
     db._create("c1");
     
-    /* limit the number of documents to 3 */
+    // limit the number of documents to 3 
     db.c1.ensureCapConstraint(3); 
 
-    /* insert 3 documents */
+    // insert 3 documents 
     db.c1.save({ _key: "key1" });
     db.c1.save({ _key: "key2" });
     db.c1.save({ _key: "key3" });
 
-    /* this will push out key1 */
-    /* we now have these keys: [ "key1", "key2", "key3" ] */
+    // this will push out key1 
+    // we now have these keys: [ "key1", "key2", "key3" ] 
     db.c1.save({ _key: "key4" });
 
 
@@ -288,15 +288,15 @@ start. The following example using a cap constraint should illustrate that:
       },
       action: function () {
         var db = require("internal").db;
-        /* this will push out key2. we now have keys [ "key3", "key4", "key5" ] */
+        // this will push out key2. we now have keys [ "key3", "key4", "key5" ] 
         db.c1.save({ _key: "key5" }); 
 
-        /* will abort the transaction */
+        // will abort the transaction 
         throw "doh!"
       }
     });
 
-    /* we now have these keys back: [ "key2", "key3", "key4" ] */
+    // we now have these keys back: [ "key2", "key3", "key4" ] 
 
 Cross-collection transactions
 =============================
@@ -305,7 +305,7 @@ There's also the possibility to run a transaction across multiple collections.
 In this case, multiple collections need to be declared in the `collections`
 attribute, e.g.:
 
-    /* setup */
+    // setup 
     db._create("c1");
     db._create("c2");
 
@@ -320,14 +320,14 @@ attribute, e.g.:
       }
     });
 
-    db.c1.count(); /* 1 */
-    db.c2.count(); /* 1 */
+    db.c1.count(); // 1 
+    db.c2.count(); // 1
 
 
 Again, throwing an exception from inside the `action` function will make the 
 transaction abort and roll back all changes in all collections:
 
-    /* setup */
+    // setup 
     db._create("c1");
     db._create("c2");
 
@@ -342,16 +342,16 @@ transaction abort and roll back all changes in all collections:
           db.c2.save({ _key: "key" + i });
         }
 
-        db.c1.count(); /* 100 */
-        db.c2.count(); /* 100 */
+        db.c1.count(); // 100 
+        db.c2.count(); // 100 
 
-        /* abort */
+        // abort 
         throw "doh!"
       }
     });
 
-    db.c1.count(); /* 0 */
-    db.c2.count(); /* 0 */
+    db.c1.count(); // 0 
+    db.c2.count(); // 0 
 
 Passing parameters to transactions {#TransactionsParameters}
 ============================================================
@@ -434,12 +434,12 @@ Example:
         read: "users"
       },
       action: function () {
-        /* execute an AQL query that traverses a graph starting at a "users" vertex. 
-           it is yet unknown into which other collections the query will traverse */
+        // execute an AQL query that traverses a graph starting at a "users" vertex. 
+        // it is yet unknown into which other collections the query will traverse 
         db._createStatement({ 
           query: "FOR t IN TRAVERSAL(users, connections, "users/1234", "any", { }) RETURN t"
         }).execute().toArray().forEach(function (d) {
-          /* ... */
+          // ...
         });
       }
     });
@@ -560,7 +560,7 @@ into one transaction.
 Additionally, transactions in ArangoDB cannot be nested, i.e. a transaction 
 must not call any other transaction. If an attempt is made to call a transaction 
 from inside a running transaction, the server will throw error `1651 (nested 
-transactions detected`).
+transactions detected)`.
 
 It is also disallowed to execute user transaction on some of ArangoDB's own system
 collections. This shouldn't be a problem for regular usage as system collections will

Documentation/UserManual/Traversals.md

@@ -587,10 +587,10 @@ To set up the collections and populate them with initial data, the following scr
     db._create("v");
     db._createEdgeCollection("e");
 
-    /* vertices: root node */
+    // vertices: root node 
     db.v.save({ _key: "world", name: "World", type: "root" });
 
-    /* vertices: continents */
+    // vertices: continents 
     db.v.save({ _key: "continent-africa", name: "Africa", type: "continent" });
     db.v.save({ _key: "continent-asia", name: "Asia", type: "continent" });
     db.v.save({ _key: "continent-australia", name: "Australia", type: "continent" });
@@ -598,7 +598,7 @@ To set up the collections and populate them with initial data, the following scr
     db.v.save({ _key: "continent-north-america", name: "North America", type: "continent" });
     db.v.save({ _key: "continent-south-america", name: "South America", type: "continent" });
 
-    /* vertices: countries */
+    // vertices: countries 
     db.v.save({ _key: "country-afghanistan", name: "Afghanistan", type: "country", code: "AFG" });
     db.v.save({ _key: "country-albania", name: "Albania", type: "country", code: "ALB" });
     db.v.save({ _key: "country-algeria", name: "Algeria", type: "country", code: "DZA" });
@@ -640,7 +640,7 @@ To set up the collections and populate them with initial data, the following scr
     db.v.save({ _key: "country-germany", name: "Germany", type: "country", code: "DEU" });
     db.v.save({ _key: "country-people-s-republic-of-china", name: "People's Republic of China", type: "country", code: "CHN" });
 
-    /* vertices: capitals */
+    // vertices: capitals 
     db.v.save({ _key: "capital-algiers", name: "Algiers", type: "capital" });
     db.v.save({ _key: "capital-andorra-la-vella", name: "Andorra la Vella", type: "capital" });
     db.v.save({ _key: "capital-asmara", name: "Asmara", type: "capital" });
@@ -682,7 +682,7 @@ To set up the collections and populate them with initial data, the following scr
     db.v.save({ _key: "capital-yaounde", name: "Yaounde", type: "capital" });
     db.v.save({ _key: "capital-zagreb", name: "Zagreb", type: "capital" });
 
-    /* edges: continent -> world */
+    // edges: continent -> world 
     db.e.save("v/continent-africa", "v/world", { type: "is-in" });
     db.e.save("v/continent-asia", "v/world", { type: "is-in" });
     db.e.save("v/continent-australia", "v/world", { type: "is-in" });
@@ -690,7 +690,7 @@ To set up the collections and populate them with initial data, the following scr
     db.e.save("v/continent-north-america", "v/world", { type: "is-in" });
     db.e.save("v/continent-south-america", "v/world", { type: "is-in" });
 
-    /* edges: country -> continent */
+    // edges: country -> continent 
     db.e.save("v/country-afghanistan", "v/continent-asia", { type: "is-in" });
     db.e.save("v/country-albania", "v/continent-europe", { type: "is-in" });
     db.e.save("v/country-algeria", "v/continent-africa", { type: "is-in" });
@@ -732,7 +732,7 @@ To set up the collections and populate them with initial data, the following scr
     db.e.save("v/country-germany", "v/continent-europe", { type: "is-in" });
     db.e.save("v/country-people-s-republic-of-china", "v/continent-asia", { type: "is-in" });
 
-    /* edges: capital -> country */
+    // edges: capital -> country 
     db.e.save("v/capital-algiers", "v/country-algeria", { type: "is-in" });
     db.e.save("v/capital-andorra-la-vella", "v/country-andorra", { type: "is-in" });
     db.e.save("v/capital-asmara", "v/country-eritrea", { type: "is-in" });