updated documentation

Documentation/Examples/api-collection-bad-handle

@@ -4,7 +4,7 @@ HTTP/1.1 400 Bad Request
 content-type: application/json
 
 {
-  "errorMessage": "expect GET /_api/collection/<collection-identifer>",
+  "errorMessage": "expected GET /_api/collection/<collection-name>",
   "errorNum": 400,
   "code": 400,
   "error": true

Documentation/Examples/shell-read-document-bad-handle

@@ -1,5 +1,5 @@
 arango> db.example.document("12345");
 JavaScript exception in file '(arango)' at 1,12:
-  [ArangoError 10: bad parameter: <document-idenifier> must be a document identifier]
+  [ArangoError 10: bad parameter: <document-identifier> must be a document identifier]
 !db.example.document("12345");
 !           ^

arangod/Documentation/api-collection.dox

@@ -48,26 +48,26 @@
 ///  <li>@ref HttpCollectionConstructor
 ///   <ul>
 ///    <li>@ref HttpCollectionCreate "POST /_api/collection"</li>
-///    <li>@ref HttpCollectionDelete "DELETE /_api/collection/collection-identifier"</li>
+///    <li>@ref HttpCollectionDelete "DELETE /_api/collection/collection-name"</li>
-///    <li>@ref HttpCollectionTruncate "PUT /_api/collection/collection-identifier/truncate"</li>
+///    <li>@ref HttpCollectionTruncate "PUT /_api/collection/collection-name/truncate"</li>
 ///   </ul>
 ///  </li>
 ///  <li>@ref HttpCollectionReading
 ///   <ul>
-///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier"</li>
+///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-name"</li>
-///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier/properties"</li>
+///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-name/properties"</li>
-///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier/count"</li>
+///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-name/count"</li>
-///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier/figures"</li>
+///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-name/figures"</li>
-///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-identifier"</li>
+///    <li>@ref HttpCollectionRead "GET /_api/collection/collection-name"</li>
 ///    <li>@ref HttpCollectionReadAll "GET /_api/collection/"</li>
 ///   </ul>
 ///  </li>
 ///  <li>@ref HttpCollectionChanging
 ///   <ul>
-///    <li>@ref HttpCollectionLoad "PUT /_api/collection/collection-identifier/load"</li>
+///    <li>@ref HttpCollectionLoad "PUT /_api/collection/collection-name/load"</li>
-///    <li>@ref HttpCollectionUnload "PUT /_api/collection/collection-identifier/unload"</li>
+///    <li>@ref HttpCollectionUnload "PUT /_api/collection/collection-name/unload"</li>
-///    <li>@ref HttpCollectionProperties "PUT /_api/collection/collection-identifier/properties"</li>
+///    <li>@ref HttpCollectionProperties "PUT /_api/collection/collection-name/properties"</li>
-///    <li>@ref HttpCollectionRename "PUT /_api/collection/collection-identifier/rename"</li>
+///    <li>@ref HttpCollectionRename "PUT /_api/collection/collection-name/rename"</li>
 ///   </ul>
 ///  </li>
 /// </ul>
@@ -95,16 +95,22 @@
 /// @section HttpCollectionResource Address of a Collection
 ////////////////////////////////////////////////////////////
 ///
-/// All collections in ArangoDB have an unique identifier. This collection
+/// All collections in ArangoDB have an unique identifier and
-/// identifier identifies a collection and is managed by ArangoDB. All
+/// a unique name. ArangoDB internally uses the collection's unique 
-/// collections are found under the URI
+/// identifier to look up collections. This identifier however is
+/// managed by ArangoDB and the user has no control over it. In
+/// order to allow users use their own names, each collection also
+/// has a unique name, which is specified by the user.
+/// To access a collection from the user perspective, the 
+/// collection name should be used, i.e.:
 ///
-/// @LIT{http://server:port/_api/collection/collection-identifier}
+/// @LIT{http://server:port/_api/collection/collection-name}
 ///
-/// For example: Assume that the collection identifier is @LIT{7254820},
+/// For example: Assume that the collection identifier is @LIT{7254820}
-/// then the URL of that collection is:
+/// and the collection name is @LIT{demo}, then the URL of that 
+/// collection is:
 ///
-/// @LIT{http://localhost:8529/_api/collection/7254820}
+/// @LIT{http://localhost:8529/_api/collection/demo}
 ///
 /// @section HttpCollectionHttp Working with Collections using HTTP
 ///////////////////////////////////////////////////////////////////

arangod/Documentation/api-index.dox

@@ -46,7 +46,7 @@
 ///
 /// <ul>
 ///  <li>@ref HttpIndexRead "GET /_api/index/index-handle"</li>
-///  <li>@ref HttpIndexCreate "POST /_api/index?collection=collection-identifier"</li>
+///  <li>@ref HttpIndexCreate "POST /_api/index?collection=collection-name"</li>
 ///  <li>@ref HttpIndexDelete "DELETE /_api/index/index-handle"</li>
 ///  <li>@ref HttpIndexReadAll "GET /_api/index?collection=index-handle"</li>
 /// </ul>
@@ -86,10 +86,10 @@
 ///
 /// @LIT{http://server:port/_api/index/index-handle}
 ///
-/// For example: Assume that the index handle is @LIT{7254820/63563528} then
+/// For example: Assume that the index handle is @LIT{demo/63563528} then
 /// the URL of that index is:
 ///
-/// @LIT{http://localhost:8529/_api/index/7254820/63563528}
+/// @LIT{http://localhost:8529/_api/index/demo/63563528}
 ///
 /// @section HttpIndexHttp Working with Indexes using HTTP
 //////////////////////////////////////////////////////////

arangod/Documentation/http-interface.dox

@@ -35,17 +35,16 @@
 /// Each resource has an identifier, which allows to access the given resource.
 ///
 /// - collection:
-///     A collection can be referenced using the collection identifier or the
+///     A collection can be referenced using the collection name
-///     collection name.
 /// - document:
-///     A document can be referenced using the collection identifier and the
+///     A document can be referenced using the combination of the collection 
-///     document identifier. Alternativly you can use a document reference which
+///     name and the unique document key. Alternativly you can use a document 
-///     is a string of the form "collection-identifier:document-identifier".
+///     handle which is a string of the form "collection-name/document-key".
 /// - index:
 ///     An index can be referenced using the index identifier.
 /// - revision:
-///     Each document has a unique document identifier. However, it is possible
+///     Each document has a unique document key. However, it is possible
-///     to update documents. In this case the document identifier stays the
+///     to update documents. In this case the document key stays the
 ///     same. Each new revision of such a document gets a new revision number.
 /// - etag:
 ///     A revision of a document has an etag.

arangod/Documentation/rest-document.dox

@@ -46,12 +46,12 @@
 ///
 /// <ul>
 ///  <li>@ref RestDocumentRead "GET /_api/document/document-handle"</li>
-///  <li>@ref RestDocumentCreate "POST /_api/document?collection=collection-identifier"</li>
+///  <li>@ref RestDocumentCreate "POST /_api/document?collection=collection-name"</li>
 ///  <li>@ref RestDocumentReplace "PUT /_api/document/document-handle"</li>
 ///  <li>@ref RestDocumentUpdate "PATCH /_api/document/document-handle"</li>
 ///  <li>@ref RestDocumentDelete "DELETE /_api/document/document-handle"</li>
 ///  <li>@ref RestDocumentHead "HEAD /_api/document/document-handle"</li>
-///  <li>@ref RestDocumentReadAll "GET /_api/document?collection=collection-identifier"</li>
+///  <li>@ref RestDocumentReadAll "GET /_api/document?collection=collection-name"</li>
 /// </ul>
 ////////////////////////////////////////////////////////////////////////////////
 

arangod/Documentation/rest-edge.dox

@@ -46,11 +46,11 @@
 ///
 /// <ul>
 ///  <li>@ref RestEdgeRead "GET /_api/edge/document-handle"</li>
-///  <li>@ref RestEdgeCreate "POST /_api/edge?collection=collection-identifier&from=from-handle&to=to-handle"</li>
+///  <li>@ref RestEdgeCreate "POST /_api/edge?collection=collection-name&from=from-handle&to=to-handle"</li>
 ///  <li>@ref RestEdgeUpdate "PUT /_api/edge/document-handle"</li>
 ///  <li>@ref RestEdgeDelete "DELETE /_api/edge/document-handle"</li>
 ///  <li>@ref RestEdgeHead "HEAD /_api/edge/document-handle"</li>
-///  <li>@ref RestEdgeEdges "GET /_api/edges/collection-identifier?vertex=vertex-handle&directory=direction"</li>
+///  <li>@ref RestEdgeEdges "GET /_api/edges/collection-name?vertex=vertex-handle&directory=direction"</li>
 /// </ul>
 ////////////////////////////////////////////////////////////////////////////////
 

arangod/Documentation/shell-collection.dox

@@ -93,14 +93,14 @@
 /// @section ShellCollectionResource Address of a Collection
 ////////////////////////////////////////////////////////////
 ///
-/// All collections in ArangoDB have an unique identifier. This collection
+/// All collections in ArangoDB have an unique identifier and
-/// identifier identifies a collection and is managed by ArangoDB. Each
+/// a unique name. ArangoDB internally uses the collection's unique 
-/// collection, in addition, has a unique name. This name is managed by the
+/// identifier to look up collections. This identifier however is
-/// user. The interface allows you to access the collections as:
+/// managed by ArangoDB and the user has no control over it. In
-///
+/// order to allow users use their own names, each collection also
-/// @LIT{db._collection(@FA{collection-identifier})}
+/// has a unique name, which is specified by the user.
-///
+/// To access a collection from the user perspective, the 
-/// or
+/// collection name should be used, i.e.:
 ///
 /// @LIT{db._collection(@FA{collection-name})}
 ///
@@ -112,14 +112,10 @@
 ///
 /// @LIT{db._collection("demo")}
 ///
-/// or
-///
-/// @LIT{db._collection(7254820)}
-///
 /// If no collection with such a name or identifier exists, then
 /// @LIT{null} is returned.
 ///
-/// There is a short-cut
+/// There is a short-cut that can be used for non-system collections:
 ///
 /// @LIT{db.@FA{collection-name}}
 ///

arangod/RestHandler/RestDocumentHandler.cpp

@@ -167,11 +167,11 @@ HttpHandler::status_e RestDocumentHandler::execute () {
 ///
 /// @RESTHEADER{POST /_api/document,creates a document}
 ///
-/// @REST{POST /_api/document?collection=@FA{collection-identifier}}
+/// @REST{POST /_api/document?collection=@FA{collection-name}}
 ///
-/// Creates a new document in the collection identified by the
+/// Creates a new document in the collection identified by @FA{collection-name}.
-/// @FA{collection-identifier}.  A JSON representation of the document must be
+/// A JSON representation of the document must be passed as the body of the POST 
-/// passed as the body of the POST request.
+/// request.
 ///
 /// If the document was created successfully, then a @LIT{HTTP 201} is returned
 /// and the "Location" header contains the path to the newly created
@@ -196,8 +196,9 @@ HttpHandler::status_e RestDocumentHandler::execute () {
 /// synchronisation for collections that have a default @LIT{waitForSync} value
 /// of @LIT{true}.
 ///
-/// If the @FA{collection-identifier} is unknown, then a @LIT{HTTP 404} is
+/// If the collection specified by @FA{collection-name} is unknown, then a 
-/// returned and the body of the response contains an error document.
+/// @LIT{HTTP 404} is returned and the body of the response contains an error 
+/// document.
 ///
 /// If the body does not contain a valid JSON representation of a document,
 /// then a @LIT{HTTP 400} is returned and the body of the response contains
@@ -205,8 +206,7 @@ HttpHandler::status_e RestDocumentHandler::execute () {
 ///
 /// @REST{POST /_api/document?collection=@FA{collection-name}@LATEXBREAK&createCollection=@FA{create-flag}}
 ///
-/// Instead of a @FA{collection-identifier}, a @FA{collection-name} can be
+/// If @FA{create-flag} has a value of @LIT{true} or @LIT{yes}, then the 
-/// used. If @FA{create-flag} has a value of @LIT{true} or @LIT{yes}, then the 
 /// collection is created if it does not yet exist. Other values for @FA{create-flag}
 /// will be ignored so the collection must be present for the operation to succeed.
 ///
@@ -344,7 +344,7 @@ bool RestDocumentHandler::readDocument () {
     default:
       generateError(HttpResponse::BAD, 
                     TRI_ERROR_HTTP_SUPERFLUOUS_SUFFICES,
-                    "expecting GET /_api/document/<document-handle> or GET /_api/document?collection=<collection-identifier>");
+                    "expecting GET /_api/document/<document-handle> or GET /_api/document?collection=<collection-name>");
       return false;
   }
 }
@@ -471,12 +471,10 @@ bool RestDocumentHandler::readSingleDocument (bool generateBody) {
 ///
 /// @RESTHEADER{GET /_api/document,reads all document}
 ///
-/// @REST{GET /_api/document?collection=@FA{collection-identifier}}
+/// @REST{GET /_api/document?collection=@FA{collection-name}}
 ///
 /// Returns a list of all URI for all documents from the collection identified
-/// by @FA{collection-identifier}.
+/// by @FA{collection-name}.
-///
-/// Instead of a @FA{collection-identifier}, a collection name can be given.
 ///
 /// @EXAMPLES
 ///
@@ -623,7 +621,7 @@ bool RestDocumentHandler::checkDocument () {
 ///
 /// For example, to conditionally replace a document based on a specific revision
 /// id, you the following request:
-/// @REST{PUT /_api/document/@FA{collection-identifier}/@FA{document-identifier}?rev=@FA{etag}}
+/// @REST{PUT /_api/document/@FA{document-handle}?rev=@FA{etag}}
 ///
 /// If a target revision id is provided in the request (e.g. via the @FA{etag} value
 /// in the @LIT{rev} URL parameter above), ArangoDB will check that

arangod/RestHandler/RestEdgeHandler.cpp

@@ -75,19 +75,25 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request, TRI_vocbase_t* vocbase)
 ///
 /// @RESTHEADER{POST /_api/edge,creates an edge}
 ///
-/// @REST{POST /_api/edge?collection=@FA{collection-identifier}&from=@FA{from-handle}&to=@FA{to-handle}}
+/// @REST{POST /_api/edge?collection=@FA{collection-name}&from=@FA{from-handle}&to=@FA{to-handle}}
 ///
-/// Creates a new edge in the collection identified by the
+/// Creates a new edge in the collection identified by @FA{collection-name}.  
-/// @FA{collection-identifier}.  A JSON representation of the document must be
+/// A JSON representation of the edge document must be passed as the body of 
-/// passed as the body of the POST request. The object handle of the start point
+/// the POST request. This JSON object may contain the edge's document key in
-/// must be passed in @FA{from-handle}. The object handle of the end point must
+/// the @LIT{_key} attribute if needed. It may also contain the boolean 
-/// be passed in @FA{to-handle}.
+/// @LIT{_bidirectional} attribute.
+/// The document handle of the start point must be passed in @FA{from-handle}. 
+/// The document handle of the end point must be passed in @FA{to-handle}.
+///
+/// @LIT{from-handle} and @{to-handle} are immutable once the edge has been
+/// created.
 ///
 /// In all other respects the method works like @LIT{POST /document}, see
 /// @ref RestDocument for details.
 ///
 /// If you request such an edge, the returned document will also contain the
-/// attributes @LIT{_from} and @LIT{_to}.
+/// attributes @LIT{_bidirectional} and either @LIT{_vertices} or 
+/// @LIT{_from} and @LIT{_to}.
 ///
 /// @EXAMPLES
 ///

arangod/RestHandler/RestImportHandler.cpp

@@ -161,13 +161,13 @@ HttpHandler::status_e RestImportHandler::execute () {
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief creates documents
 ///
-/// @REST{POST /_api/import?type=documents&collection=@FA{collection-identifier}}
+/// @REST{POST /_api/import?type=documents&collection=@FA{collection-name}}
 ///
-/// Creates documents in the collection identified by the
+/// Creates documents in the collection identified by @FA{collection-name}.  
-/// @FA{collection-identifier}.  The JSON representations of the documents must 
+/// The JSON representations of the documents must be passed as the body of the 
-/// be passed as the body of the POST request.
+/// POST request.
 ///
-/// If the document was created successfully, then a @LIT{HTTP 201} is returned.
+/// If the documents were created successfully, then a @LIT{HTTP 201} is returned.
 ////////////////////////////////////////////////////////////////////////////////
 
 bool RestImportHandler::createByArray () {
@@ -278,13 +278,13 @@ bool RestImportHandler::createByArray () {
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief creates documents
 ///
-/// @REST{POST /_api/import?collection=@FA{collection-identifier}}
+/// @REST{POST /_api/import?collection=@FA{collection-name}}
 ///
-/// Creates documents in the collection identified by the
+/// Creates documents in the collection identified by @FA{collection-name}. 
-/// @FA{collection-identifier}.  The JSON representations of the documents must 
+/// The JSON representations of the documents must be passed as the body of the 
-/// be passed as the body of the POST request.
+/// POST request.
 ///
-/// If the document was created successfully, then a @LIT{HTTP 201} is returned.
+/// If the documents were created successfully, then a @LIT{HTTP 201} is returned.
 ////////////////////////////////////////////////////////////////////////////////
 
 bool RestImportHandler::createByList () {
@@ -460,6 +460,9 @@ bool RestImportHandler::createByList () {
   return true;
 }
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief create response for number of documents created / failed
+////////////////////////////////////////////////////////////////////////////////
 
 void RestImportHandler::generateDocumentsCreated (size_t numCreated, size_t numError, size_t numEmpty) {
   _response = createResponse(HttpResponse::CREATED);
@@ -475,6 +478,10 @@ void RestImportHandler::generateDocumentsCreated (size_t numCreated, size_t numE
     .appendText("}");
 }
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief parse a single document line
+////////////////////////////////////////////////////////////////////////////////
+
 TRI_json_t* RestImportHandler::parseJsonLine (const string& line) {
   char* errmsg = 0;
   TRI_json_t* json = TRI_Json2String(TRI_UNKNOWN_MEM_ZONE, line.c_str(), &errmsg);
@@ -486,6 +493,10 @@ TRI_json_t* RestImportHandler::parseJsonLine (const string& line) {
   return json;
 }
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief create a JSON object from a line containing a document
+////////////////////////////////////////////////////////////////////////////////
+
 TRI_json_t* RestImportHandler::createJsonObject (TRI_json_t* keys, TRI_json_t* values, const string& line) {
   
   if (values->_type != TRI_JSON_LIST) {
@@ -519,12 +530,16 @@ TRI_json_t* RestImportHandler::createJsonObject (TRI_json_t* keys, TRI_json_t* v
   return result;
 }
 
+////////////////////////////////////////////////////////////////////////////////
+/// @brief validate keys
+////////////////////////////////////////////////////////////////////////////////
+
 bool RestImportHandler::checkKeys (TRI_json_t* keys) {
   if (keys->_type != TRI_JSON_LIST) {
     return false;
   }
   
-  size_t n = keys->_value._objects._length;
+  const size_t n = keys->_value._objects._length;
   
   if (n == 0) {
     return false;

arangod/V8Server/v8-vocbase.cpp

@@ -4892,16 +4892,17 @@ static v8::Handle<v8::Value> MapGetVocBase (v8::Local<v8::String> name,
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief returns a single collection or null
 ///
-/// @FUN{db._collection(@FA{collection-identifier})}
-///
-/// Returns the collection with the given identifier or null if no such
-/// collection exists.
-///
 /// @FUN{db._collection(@FA{collection-name})}
 ///
 /// Returns the collection with the given name or null if no such collection
 /// exists.
 ///
+/// @FUN{db._collection(@FA{collection-identifier})}
+///
+/// Returns the collection with the given identifier or null if no such
+/// collection exists. Accessing collections by identifier is discouraged for
+/// end users. End users should access collections using the collection name.
+///
 /// @EXAMPLES
 ///
 /// Get a collection by name: