From 45e69ca79ad9d748c18e680f091b91c54900f65f Mon Sep 17 00:00:00 2001 From: Jan Steemann Date: Mon, 27 Jan 2014 14:49:41 +0100 Subject: [PATCH] fixed documentation errors --- Documentation/Examples/foxx-doc-comment | 8 +++ Documentation/Manual/NewFeatures13.md | 2 +- Documentation/Scripts/generateTOC.py | 3 + Documentation/UserManual/AqlExamples.md | 2 +- Documentation/UserManual/Arangosh.md | 8 +-- Documentation/UserManual/Foxx.md | 9 +-- Documentation/UserManual/Transactions.md | 70 ++++++++++++------------ Documentation/UserManual/Traversals.md | 14 ++--- 8 files changed, 59 insertions(+), 57 deletions(-) create mode 100644 Documentation/Examples/foxx-doc-comment diff --git a/Documentation/Examples/foxx-doc-comment b/Documentation/Examples/foxx-doc-comment new file mode 100644 index 0000000000..184d0808d0 --- /dev/null +++ b/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 () { + // ... +}); diff --git a/Documentation/Manual/NewFeatures13.md b/Documentation/Manual/NewFeatures13.md index 87b3f67a02..e292e6c98e 100644 --- a/Documentation/Manual/NewFeatures13.md +++ b/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; } }); diff --git a/Documentation/Scripts/generateTOC.py b/Documentation/Scripts/generateTOC.py index a160ee01aa..1aead0f989 100755 --- a/Documentation/Scripts/generateTOC.py +++ b/Documentation/Scripts/generateTOC.py @@ -42,6 +42,9 @@ argv.pop(0) DEBUG = False +print '# Auto-generated aliases' +print '' + ################################################################################ ### @brief parse file ################################################################################ diff --git a/Documentation/UserManual/AqlExamples.md b/Documentation/UserManual/AqlExamples.md index 94dfa23b69..b95ca7e524 100644 --- a/Documentation/UserManual/AqlExamples.md +++ b/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 { diff --git a/Documentation/UserManual/Arangosh.md b/Documentation/UserManual/Arangosh.md index 2cfa115eca..e860529bac 100644 --- a/Documentation/UserManual/Arangosh.md +++ b/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. diff --git a/Documentation/UserManual/Foxx.md b/Documentation/UserManual/Foxx.md index a1799a7f1b..16f4034ae7 100644 --- a/Documentation/UserManual/Foxx.md +++ b/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 diff --git a/Documentation/UserManual/Transactions.md b/Documentation/UserManual/Transactions.md index 0885ceb1da..9def12865d 100644 --- a/Documentation/UserManual/Transactions.md +++ b/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 diff --git a/Documentation/UserManual/Traversals.md b/Documentation/UserManual/Traversals.md index 13895bc24c..c8831d9464 100644 --- a/Documentation/UserManual/Traversals.md +++ b/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" });