better error messages

Documentation/Books/HTTP/Indexes/Persistent.mdpp

@@ -0,0 +1,7 @@
+!CHAPTER Working with Persistent Indexes
+
+If a suitable persistent index exists, then /_api/simple/range and other operations
+will use this index to execute queries.
+
+<!-- js/actions/api-index.js -->
+@startDocuBlock JSF_post_api_index_persistent

Documentation/Books/HTTP/Indexes/Skiplist.mdpp

@@ -1,6 +1,7 @@
 !CHAPTER Working with Skiplist Indexes
 
-If a suitable skip-list index exists, then /_api/simple/range will use this index to execute a range query.
+If a suitable skip-list index exists, then /_api/simple/range and other operations
+will use this index to execute queries.
 
 <!-- js/actions/api-index.js -->
 @startDocuBlock JSF_post_api_index_skiplist

Documentation/Books/HTTP/SUMMARY.md

@@ -38,6 +38,7 @@
   * [Working with Indexes](Indexes/WorkingWith.md)
   * [Hash](Indexes/Hash.md)
   * [Skiplist](Indexes/Skiplist.md)
+  * [Persistent](Indexes/Persistent.md)
   * [Geo](Indexes/Geo.md)
   * [Fulltext](Indexes/Fulltext.md)
 * [Transactions](Transaction/README.md)

Documentation/DocuBlocks/Rest/Indexes/JSF_post_api_index.md

@@ -28,9 +28,9 @@ of the index details. Depending on the index type, a single attribute or
 multiple attributes can be indexed. In the latter case, an array of
 strings is expected.
 
-Indexing system attributes such as *_id*, *_key*, *_from*, and *_to*
+Indexing the system attribute *_id* is not supported for user-defined indexes. 
-is not supported for user-defined indexes. Manually creating an index using
+Manually creating an index using *_id* as an index attribute will fail with 
-any of these attributes will fail with an error.
+an error.
 
 Some indexes can be created as unique or non-unique variants. Uniqueness
 can be controlled for most indexes by specifying the *unique* flag in the
@@ -41,12 +41,13 @@ create a non-unique index.
 **Note**: The following index types do not support uniqueness, and using
 the *unique* attribute with these types may lead to an error:
 
+- geo indexes
 - fulltext indexes
 
 **Note**: Unique indexes on non-shard keys are not supported in a
 cluster.
 
-Hash and skiplist indexes can optionally be created in a sparse
+Hash, skiplist and persistent indexes can optionally be created in a sparse
 variant. A sparse index will be created if the *sparse* attribute in
 the index details is set to *true*. Sparse indexes do not index documents
 for which any of the index attributes is either not set or is *null*. 

Documentation/DocuBlocks/Rest/Indexes/JSF_post_api_index_persistent.md

@@ -0,0 +1,108 @@
+
+@startDocuBlock JSF_post_api_index_persistent
+@brief creates a persistent index
+
+@RESTHEADER{POST /_api/index, Create a persistent index)
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{collection-name,string,required}
+The collection name.
+
+
+@RESTBODYPARAM{type,string,required,string}
+must be equal to *"persistent"*.
+
+@RESTBODYPARAM{fields,array,required,string}
+an array of attribute paths.
+
+@RESTBODYPARAM{unique,boolean,required,}
+if *true*, then create a unique index.
+
+@RESTBODYPARAM{sparse,boolean,required,}
+if *true*, then create a sparse index.
+
+@RESTDESCRIPTION
+
+Creates a persistent index for the collection *collection-name*, if
+it does not already exist. The call expects an object containing the index
+details.
+
+In a sparse index all documents will be excluded from the index that do not 
+contain at least one of the specified index attributes (i.e. *fields*) or that 
+have a value of *null* in any of the specified index attributes. Such documents 
+will not be indexed, and not be taken into account for uniqueness checks if
+the *unique* flag is set.
+
+In a non-sparse index, these documents will be indexed (for non-present
+indexed attributes, a value of *null* will be used) and will be taken into
+account for uniqueness checks if the *unique* flag is set.
+
+**Note**: unique indexes on non-shard keys are not supported in a cluster.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+If the index already exists, then a *HTTP 200* is
+returned.
+
+@RESTRETURNCODE{201}
+If the index does not already exist and could be created, then a *HTTP 201*
+is returned.
+
+@RESTRETURNCODE{400}
+If the collection already contains documents and you try to create a unique
+persistent index in such a way that there are documents violating the
+uniqueness, then a *HTTP 400* is returned.
+
+@RESTRETURNCODE{404}
+If the *collection-name* is unknown, then a *HTTP 404* is returned.
+
+@EXAMPLES
+
+Creating a persistent index
+
+@EXAMPLE_ARANGOSH_RUN{RestIndexCreateNewPersistent}
+    var cn = "products";
+    db._drop(cn);
+    db._create(cn);
+
+    var url = "/_api/index?collection=" + cn;
+    var body = { 
+      type: "persistent", 
+      unique: false, 
+      fields: [ "a", "b" ] 
+    };
+
+    var response = logCurlRequest('POST', url, body);
+
+    assert(response.code === 201);
+
+    logJsonResponse(response);
+  ~ db._drop(cn);
+@END_EXAMPLE_ARANGOSH_RUN
+
+Creating a sparse persistent index
+
+@EXAMPLE_ARANGOSH_RUN{RestIndexCreateSparsePersistent}
+    var cn = "products";
+    db._drop(cn);
+    db._create(cn);
+
+    var url = "/_api/index?collection=" + cn;
+    var body = { 
+      type: "persistent",
+      unique: false, 
+      sparse: true, 
+      fields: [ "a" ] 
+    };
+
+    var response = logCurlRequest('POST', url, body);
+
+    assert(response.code === 201);
+
+    logJsonResponse(response);
+  ~ db._drop(cn);
+@END_EXAMPLE_ARANGOSH_RUN
+@endDocuBlock
+

utils/generateSwagger.py

@@ -510,6 +510,9 @@ def restheader(cargo, r=Regexen()):
     (fp, last) = cargo
 
     temp = parameters(last).split(',')
+    if temp == "":
+        raise Exception("Invalid restheader value. got empty string. Maybe missing closing bracket? " + path)
+
     (ucmethod, path) = temp[0].split()
 
     #TODO: hier checken, ob der letzte alles hatte (responses)
@@ -528,7 +531,7 @@ def restheader(cargo, r=Regexen()):
         raise Exception("Duplicate route")
 
     if currentDocuBlock == None:
-        raise Exception("No docublock started for this restheader: " + ucmethod + " " + path )
+        raise Exception("No docublock started for this restheader: " + ucmethod + " " + path)
 
     if lastDocuBlock != None and currentDocuBlock == lastDocuBlock:
         raise Exception("No new docublock started for this restheader: " + ucmethod + " " + path  + ' : ' + currentDocuBlock)