Doc - Deprecation notes 3.4 (#6405)

Documentation/Books/AQL/Functions/Geo.md

@@ -117,9 +117,11 @@ This function can be **optimized** via a S2 based geospatial index, please look
 
 Determine whether a coordinate is inside a polygon.
 
-Note: the *IS_IN_POLYGON* AQL function is **deprecated** as of ArangoDB 3.4.0 in
+{% hint 'warning' %}
+The *IS_IN_POLYGON* AQL function is **deprecated** as of ArangoDB 3.4.0 in
 favor of the new `GEO_CONTAINS` AQL function, which works with
 [GeoJSON](https://tools.ietf.org/html/rfc7946) Polygons and MultiPolygons.
+{% endhint %}
 
 `IS_IN_POLYGON(polygon, latitude, longitude) → bool`
 
@@ -279,18 +281,32 @@ Geo Index Functions
 -------------------
 
 {% hint 'warning' %}
-The AQL functions `NEAR()`, `WITHIN()` and `WITHIN_RECTANGLE()` are deprecated.
+The AQL functions `NEAR()`, `WITHIN()` and `WITHIN_RECTANGLE()` are
+deprecated starting from version 3.4.0.
 Please use the [Geo utility functions](#geo-utility-functions) instead.
 {% endhint %}
 
-AQL offers the following functions to filter data based on [geo
+AQL offers the following functions to filter data based on
-indexes](../../Manual/Indexing/Geo.html). These functions require the collection
+[geo indexes](../../Manual/Indexing/Geo.html). These functions require the collection
 to have at least one geo index. If no geo index can be found, calling this
 function will fail with an error at runtime. There is no error when explaining
 the query however.
 
 ### NEAR()
 
+{% hint 'warning' %}
+`NEAR` is a deprecated AQL function from version 3.4.0 on.
+Use [DISTANCE()](#distance) in a query like this instead:
+
+```js
+FOR doc IN doc
+  SORT DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude) ASC
+  RETURN doc
+```
+Assuming there exists a geo-type index on `latitude` and `longitude`, the
+optimizer will recognize it and accelerate the query.
+{% endhint %}
+
 `NEAR(coll, latitude, longitude, limit, distanceName) → docArray`
 
 Return at most *limit* documents from collection *coll* that are near
@@ -314,18 +330,23 @@ contain the distance value in an attribute of that name.
 - returns **docArray** (array): an array of documents, sorted by distance
   (shortest distance first)
 
+### WITHIN()
 
-**Note:** `NEAR` is a *deprecated* AQL function, instead use a query like this:
+{% hint 'warning' %}
+`WITHIN` is a deprecated AQL function from version 3.4.0 on.
+Use [DISTANCE()](#distance) in a query like this instead:
 
 ```js
 FOR doc IN doc
-  SORT DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude) ASC
+  LET d = DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude)
+  FILTER d <= radius
+  SORT d ASC
   RETURN doc
 ```
+
 Assuming there exists a geo-type index on `latitude` and `longitude`, the
 optimizer will recognize it and accelerate the query.
-
+{% endhint %}
-### WITHIN()
 
 `WITHIN(coll, latitude, longitude, radius, distanceName) → docArray`
 
@@ -348,20 +369,21 @@ value in an attribute of that name.
 - returns **docArray** (array): an array of documents, sorted by distance
   (shortest distance first)
 
-**Note:** `WITHIN` is a *deprecated* AQL function, instead use a query like this:
+### WITHIN_RECTANGLE()
+
+{% hint 'warning' %}
+`WITHIN_RECTANGLE` is a deprecated AQL function from version 3.4.0 on. Use
+[GEO_CONTAINS](#geocontains) and a GeoJSON polygon instead:
 
 ```js
+LET rect = {type: "Polygon", coordinates: [[[longitude1, latitude1], ...]]]}
 FOR doc IN doc
-  LET d = DISTANCE(doc.latitude, doc.longitude, paramLatitude, paramLongitude)
+  FILTER GEO_CONTAINS(poly, [doc.longitude, doc.latitude])
-  FILTER d <= radius
-  SORT d ASC
   RETURN doc
 ```
-
 Assuming there exists a geo-type index on `latitude` and `longitude`, the
 optimizer will recognize it and accelerate the query.
-
+{% endhint %}
-### WITHIN_RECTANGLE()
 
 `WITHIN_RECTANGLE(coll, latitude1, longitude1, latitude2, longitude2) → docArray`
 
@@ -379,15 +401,3 @@ bounding rectangle with the points (*latitude1*, *longitude1*) and (*latitude2*,
 - **longitude2** (number): the top-right longitude portion of the search
   coordinate
 - returns **docArray** (array): an array of documents, in random order
-
-**Note:** `WITHIN_RECTANGLE` is a *deprecated* AQL function, instead use a query
-using a GeoJSON polygon:
-
-```js
-LET rect = {type: "Polygon", coordinates: [[[longitude1, latitude1], ...]]]}
-FOR doc IN doc
-  FILTER GEO_CONTAINS(poly, [doc.longitude, doc.latitude])
-  RETURN doc
-```
-Assuming there exists a geo-type index on `latitude` and `longitude`, the
-optimizer will recognize it and accelerate the query.

Documentation/Books/HTTP/SimpleQuery/README.md

@@ -1,6 +1,12 @@
 HTTP Interface for Simple Queries
 =================================
 
+{% hint 'warning' %}
+The Simple Queries API is deprecated from version 3.4.0 on.
+These endpoints should no longer be used.
+They are superseded by AQL queries.
+{% endhint %}
+
 Simple Queries
 --------------
 

Documentation/Books/HTTP/Traversal/README.md

@@ -1,16 +1,19 @@
 HTTP Interface for Traversals
 =============================
 
-### Traversals
+{% hint 'warning' %}
+The API endpoint `/_api/traversal` is deprecated from version 3.4.0 on.
+The preferred way to traverse graphs is with AQL.
+{% endhint %}
 
 ArangoDB's graph traversals are executed on the server. Traversals can be 
 initiated by clients by sending the traversal description for execution to
 the server.
 
-Traversals in ArangoDB are used to walk over a graph
+Traversals in ArangoDB are used to walk over a graph stored in one
-stored in one [edge collection](../../Manual/Appendix/Glossary.html#edge-collection). It can easily be described
+[edge collection](../../Manual/Appendix/Glossary.html#edge-collection).
-which edges of the graph should be followed and which actions
+It can easily be described which edges of the graph should be followed
-should be performed on each visited vertex.
+and which actions should be performed on each visited vertex.
 Furthermore the ordering of visiting the nodes can be
 specified, for instance depth-first or breadth-first search
 are offered.

Documentation/Books/Manual/Foxx/Guides/LegacyMode.md

@@ -5,11 +5,12 @@ ArangoDB 3 continues to support Foxx services written for ArangoDB 2.8 by
 running them in a special legacy compatibility mode that provides access to
 some of the modules and APIs no longer provided in 3.0 and beyond.
 
-{% hint 'info' %}
+{% hint 'warning' %}
 Legacy compatibility mode is strictly intended as a temporary stop
 gap solution for supporting existing services while
 [upgrading to ArangoDB 3.x](../Migrating2x/README.md)
-and should not be considered a permanent feature of ArangoDB or Foxx.
+and is not a permanent feature of ArangoDB or Foxx. It is considered
+as deprecated from v3.4.0 on.
 {% endhint %}
 
 In order to mark an existing service as a legacy service,

Documentation/Books/Manual/Indexing/Persistent.md

@@ -1,6 +1,11 @@
 Persistent indexes
 ==================
 
+{% hint 'warning' %}
+The persistent index type is considered as deprecated from version 3.4.0 on.
+It will be removed in 4.0.0. If you use the RocksDB storage engine, you can
+replace it with a skiplist index, which uses the same implementation.
+{% endhint %}
 
 Introduction to Persistent Indexes
 ----------------------------------

Documentation/Books/Manual/ReleaseNotes/UpgradingChanges34.md

@@ -365,8 +365,8 @@ The following APIs have been added or augmented:
   The old/new revisions can be accessed by passing the URL parameters `returnOld` and
   `returnNew` to the following endpoints:
 
-  * /_api/gharial/<graph>/vertex/<collection>
+  * `/_api/gharial/<graph>/vertex/<collection>`
-  * /_api/gharial/<graph>/edge/<collection>
+  * `/_api/gharial/<graph>/edge/<collection>`
 
   The exception from this is that the HTTP DELETE verb for these APIs does not
   support `returnOld` because that would make the existing API incompatible.
@@ -456,7 +456,7 @@ instead of error 1582 (`ERROR_QUERY_FUNCTION_NOT_FOUND`) in some situations.
   now always produce the same result, whereas in previous versions of ArangoDB the
   function may have generated different results.
   
-  Each AQL query that is run will still evalute the result value of the `DATE_NOW` 
+  Each AQL query that is run will still evaluate the result value of the `DATE_NOW` 
   function independently, but only once at the beginning of the query. This is most
   often what is desired anyway, but the change makes `DATE_NOW` useless to measure
   time differences inside a single query.
@@ -720,7 +720,7 @@ removed in future versions of ArangoDB:
   using the simple query API, because that is more flexible and allows greater 
   control of how the queries are executed.
 
-* the REST API for querying endpoints at `/_api/endpoints`:
+* the REST API for querying endpoints at `/_api/endpoint`:
 
   The API `/_api/endpoint` is deprecated since ArangoDB version 3.1. 
   For cluster mode there is `/_api/cluster/endpoints` to find all current 
@@ -759,6 +759,12 @@ removed in future versions of ArangoDB:
   The types `geo1` and `geo2` will still work in ArangoDB 3.4, but may be removed
   in future versions.
 
+* the persistent index type is marked for removal in 4.0.0 and is thus deprecated.
+
+  This index type was added when there was only the MMFiles storage engine as
+  kind of a stop gap. We recommend to switch to RocksDB engine, which persists
+  all index types with no difference between skiplist and persistent indexes.
+
 * the legacy mode for Foxx applications from ArangoDB 2.8 or earlier:
 
   The legacy mode is described in more detail in the [Foxx manual](https://docs.arangodb.com/3.3/Manual/Foxx/LegacyMode.html).

Documentation/DocuBlocks/Rest/Administration/get_api_endpoint.md

@@ -4,9 +4,13 @@
 
 @RESTHEADER{GET /_api/endpoint, Return list of all endpoints}
 
-@RESTDESCRIPTION
+@HINTS
-*THIS API IS DEPRECATED*
+{% hint 'warning' %}
+This route should no longer be used.
+It is considered as deprecated from version 3.4.0 on.
+{% endhint %}
 
+@RESTDESCRIPTION
 Returns an array of all configured endpoints the server is listening on.
 
 The result is a JSON array of JSON objects, each with `"entrypoint"' as

Documentation/DocuBlocks/Rest/Collections/delete_api_collection.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{DELETE /_api/collection/{collection-name}, Drops a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collection_checksum.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection/{collection-name}/checksum, Return checksum for the collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collection_count.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection/{collection-name}/count, Return number of documents in a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collection_figures.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection/{collection-name}/figures, Return statistics for a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collection_name.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection/{collection-name}, Return information about a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collection_properties.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection/{collection-name}/properties, Read properties of a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collection_revision.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection/{collection-name}/revision, Return collection revision id}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/get_api_collections.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/collection,reads all collections}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTQUERYPARAMETERS
 
 @RESTQUERYPARAM{excludeSystem,boolean,optional}

Documentation/DocuBlocks/Rest/Collections/post_api_collection.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{POST /_api/collection, Create collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTDESCRIPTION
 Creates a new collection with a given name. The request must contain an
 object with the following attributes.

Documentation/DocuBlocks/Rest/Collections/put_api_collection_load.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/load, Load collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/put_api_collection_load_indexes_in_memory.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/loadIndexesIntoMemory, Load Indexes into Memory}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/put_api_collection_properties.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/properties, Change properties of a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/put_api_collection_rename.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/rename, Rename collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/put_api_collection_rotate.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/rotate, Rotate journal of a collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/put_api_collection_truncate.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/truncate, Truncate collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Collections/put_api_collection_unload.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{PUT /_api/collection/{collection-name}/unload, Unload collection}
 
+@HINTS
+{% hint 'warning' %}
+Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
+You should reference them via their names instead.
+{% endhint %}
+
 @RESTURLPARAMETERS
 
 @RESTURLPARAM{collection-name,string,required}

Documentation/DocuBlocks/Rest/Graph Traversal/HTTP_API_TRAVERSAL.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{POST /_api/traversal,executes a traversal}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+It is considered as deprecated from version 3.4.0 on.
+It is superseded by AQL graph traversal.
+{% endhint %}
+
 @RESTDESCRIPTION
 Starts a traversal starting from a given vertex and following.
 edges contained in a given edgeCollection. The request must

Documentation/DocuBlocks/Rest/Replication/get_api_replication_logger_follow.md

@@ -4,6 +4,12 @@
 
 @RESTHEADER{GET /_api/replication/logger-follow, Returns log entries}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+It is considered as deprecated from version 3.4.0 on.
+{% endhint %}
+
 @RESTQUERYPARAMETERS
 
 @RESTQUERYPARAM{from,number,optional}

Documentation/DocuBlocks/Rest/Simple Queries/RestLookupByKeys.md

@@ -3,6 +3,13 @@
 
 @RESTHEADER{PUT /_api/simple/lookup-by-keys, Find documents by their keys}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to look in for the documents
 
@@ -17,6 +24,10 @@ will be returned.  Keys for which no document can be found in the
 underlying collection are ignored, and no exception will be thrown for
 them.
 
+Equivalent AQL query:
+
+    FOR doc IN @@collection FILTER doc._key IN @keys RETURN doc
+
 The body of the response contains a JSON object with a *documents*
 attribute. The *documents* attribute is an array containing the
 matching documents. The order in which matching documents are present

Documentation/DocuBlocks/Rest/Simple Queries/RestRemoveByKeys.md

@@ -3,6 +3,13 @@
 
 @RESTHEADER{PUT /_api/simple/remove-by-keys, Remove documents by their keys}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to look in for the documents to remove
 
@@ -35,6 +42,11 @@ contained in the *keys* array. Keys for which no document can be found in
 the underlying collection are ignored, and no exception will be thrown for
 them.
 
+Equivalent AQL query (the RETURN clause is optional):
+
+    FOR key IN @keys REMOVE key IN @@collection
+      RETURN OLD
+
 The body of the response contains a JSON object with information how many
 documents were removed (and how many were not). The *removed* attribute will
 contain the number of actually removed documents. The *ignored* attribute 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_all.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/all, Return all documents}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTALLBODYPARAM{query,string,required}
 Contains the query.
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_any.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/any, Return a random document}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTDESCRIPTION
 Returns a random document from a collection. The call expects a JSON object
 as body with the following attributes:
@@ -13,7 +20,7 @@ The identifier or name of the collection to query.
 
 Returns a JSON object with the document stored in the attribute
 *document* if the collection contains at least one document. If
-the collection is empty, the *document* attrbute contains null.
+the collection is empty, the *document* attribute contains null.
 
 @RESTRETURNCODES
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_by_example.md

@@ -4,6 +4,20 @@
 
 @RESTHEADER{PUT /_api/simple/by-example, Simple query by-example}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
+{% hint 'warning' %}
+Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive.
+A more lightweight alternative is to use the [HTTP Cursor API](../AqlQueryCursor/README.md).
+Starting from versions 3.2.14 and 3.3.8 this performance impact is not
+an issue anymore, as the internal implementation of the API has changed.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_first_example.md

@@ -4,6 +4,20 @@
 
 @RESTHEADER{PUT /_api/simple/first-example, Find documents matching an example}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
+{% hint 'warning' %}
+Till ArangoDB versions 3.2.13 and 3.3.7 this API is quite expensive.
+A more lightweight alternative is to use the [HTTP Cursor API](../AqlQueryCursor/README.md).
+Starting from versions 3.2.14 and 3.3.8 this performance impact is not
+an issue anymore, as the internal implementation of the API has changed.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_fulltext.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/fulltext, Fulltext index query}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 
@@ -40,7 +47,6 @@ way for retrieving documents from a collection using the near operator is
 to issue an AQL query using the *FULLTEXT* [AQL function](../../AQL/Functions/Fulltext.html) 
 as follows:
 
-
     FOR doc IN FULLTEXT(@@collection, @attributeName, @queryString, @limit) 
       RETURN doc
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_near.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/near, Returns documents near a coordinate}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 
@@ -47,7 +54,6 @@ This API may be removed in future versions of ArangoDB. The preferred
 way for retrieving documents from a collection using the near operator is
 to issue an [AQL query](../../AQL/Functions/Geo.html) using the *NEAR* function as follows: 
 
-
     FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit)
       RETURN doc`
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_range.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/range, Simple range query}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 
@@ -39,7 +46,6 @@ The function may be removed in future versions of ArangoDB. The preferred
 way for retrieving documents from a collection within a specific range
 is to use an AQL query as follows: 
 
-
     FOR doc IN @@collection 
       FILTER doc.value >= @left && doc.value < @right 
       LIMIT @skip, @limit 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_remove_by_example.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/remove-by-example, Remove documents by example}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to remove from.
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_replace_by_example.md

@@ -3,6 +3,13 @@
 
 @RESTHEADER{PUT /_api/simple/replace-by-example, Replace documents by example}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to replace within.
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_update_by_example.md

@@ -3,6 +3,13 @@
 
 @RESTHEADER{PUT /_api/simple/update-by-example, Update documents by example}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to update within.
 
@@ -51,7 +58,6 @@ Using it will result in an error.
 
 Returns the number of documents that were updated.
 
-
 @RESTRETURNCODES
 
 @RESTRETURNCODE{200}

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_within.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/within, Find documents within a radius around a coordinate}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 
@@ -48,7 +55,6 @@ This API may be removed in future versions of ArangoDB. The preferred
 way for retrieving documents from a collection using the near operator is
 to issue an [AQL query](../../AQL/Functions/Geo.html) using the *WITHIN* function as follows: 
 
-
     FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName)
       RETURN doc
 

Documentation/DocuBlocks/Rest/Simple Queries/put_api_simple_within_rectangle.md

@@ -4,6 +4,13 @@
 
 @RESTHEADER{PUT /_api/simple/within-rectangle, Within rectangle query}
 
+@HINTS
+{% hint 'warning' %}
+This route should no longer be used.
+All endpoints for Simple Queries are deprecated from version 3.4.0 on.
+They are superseded by AQL queries.
+{% endhint %}
+
 @RESTBODYPARAM{collection,string,required,string}
 The name of the collection to query.
 

Documentation/Scripts/generateMdFiles.py

@@ -147,12 +147,14 @@ def getRestBodyParam():
 def getRestDescription():
     #print >>sys.stderr, "RESTDESCRIPTION"
     if thisVerb['description']:
-        #print >> sys.stderr, thisVerb['description']
+        description = thisVerb['description']
-        return RX3[0].sub(RX3[1], thisVerb['description'])
+        #print >> sys.stderr, description
+        description = RX4[0].sub(RX4[1], description)
+        return RX3[0].sub(RX3[1], description)
     else:
         #print >> sys.stderr, "ELSE"
         return ""
-        
+
 def getRestReplyBodyParam(param):
     rc = "\n**Response Body**\n"
 
@@ -214,6 +216,7 @@ SIMPL_REPL_VALIDATE_DICT = {
 }
 SIMPL_REPL_DICT = {
     "\\"                    : "\\\\",
+    "@HINTS"                : "",
     "@RESTDESCRIPTION"      : getRestDescription,
     "@RESTURLPARAMETERS"    : "\n**Path Parameters**\n",
     "@RESTQUERYPARAMETERS"  : "\n**Query Parameters**\n",
@@ -236,6 +239,7 @@ SIMPLE_RX = re.compile(
 r'''
 \\|                                 # the backslash...
 @RESTDESCRIPTION|                   # -> <empty>
+@HINTS|                             # -> <inject hints>
 @RESTURLPARAMETERS|                 # -> \n**Path Parameters**\n
 @RESTQUERYPARAMETERS|               # -> \n**Query Parameters**\n
 @RESTHEADERPARAMETERS|              # -> \n**Header Parameters**\n
@@ -338,6 +342,8 @@ RX2 = [
 
 RX3 = (re.compile(r'\*\*Example:\*\*((?:.|\n)*?)</code></pre>'), r"")
 
+RX4 = (re.compile(r'<!-- Hints Start -->.*<!-- Hints End -->', re.DOTALL), r"")
+
 match_RESTHEADER = re.compile(r"@RESTHEADER\{(.*)\}")
 match_RESTRETURNCODE = re.compile(r"@RESTRETURNCODE\{(.*)\}")
 have_RESTBODYPARAM = re.compile(r"@RESTBODYPARAM|@RESTDESCRIPTION")

utils/generateSwagger.py

@@ -301,7 +301,7 @@ def Typography(txt):
     r = rc(r"""@ref [a-zA-Z0-9]+""", MS)
     txt = r.sub("the manual", txt)
     txt = re.sub(r"@endDocuBlock", "", txt)
-    txt = BACKSLASH(txt);
+    txt = BACKSLASH(txt)
     return txt
 
 ################################################################################
@@ -373,6 +373,7 @@ class Regexen:
         self.DESCRIPTION_BL = re.compile('^\s*$')
         self.EMPTY_LINE = re.compile('^\s*$')
         self.START_DOCUBLOCK = re.compile('.*@startDocuBlock ')
+        self.HINTS = re.compile('.*@HINTS')
         self.END_EXAMPLE_ARANGOSH_RUN = re.compile('.*@END_EXAMPLE_ARANGOSH_RUN')
         self.EXAMPLES = re.compile('.*@EXAMPLES')
         self.EXAMPLE_ARANGOSH_RUN = re.compile('.*@EXAMPLE_ARANGOSH_RUN{')
@@ -412,6 +413,7 @@ def next_step(fp, line, r):
     if not line:                              return eof, (fp, line)
     elif check_end_of_comment(line, r):       return skip_code, (fp, line)
     elif r.START_DOCUBLOCK.match(line):       return start_docublock, (fp, line)
+    elif r.HINTS.match(line):                 return hints, (fp, line)
     elif r.EXAMPLE_ARANGOSH_RUN.match(line):  return example_arangosh_run, (fp, line)
     elif r.RESTBODYPARAM.match(line):         return restbodyparam, (fp, line)
     elif r.RESTSTRUCT.match(line):            return reststruct, (fp, line)
@@ -571,6 +573,7 @@ def restheader(cargo, r=Regexen()):
 
     swagger['paths'][httpPath][method] = {
         'x-filename': fn,
+        'x-hints': '',
         'x-examples': [],
         'tags': [currentTag],
         'summary': summary.strip(),
@@ -879,6 +882,23 @@ def restqueryparam(cargo, r=Regexen()):
     swagger['paths'][httpPath][method]['parameters'].append(para) 
     return generic_handler_desc(cargo, r, "restqueryparam", None, para, 'description')
 
+################################################################################
+### @brief hints
+################################################################################
+
+def hints(cargo, r=Regexen()):
+    global swagger, operation, httpPath, method
+
+    ret = generic_handler_desc(cargo, r, "hints", None,
+                               swagger['paths'][httpPath][method], 'x-hints')
+
+    if r.TRIPLENEWLINEATSTART.match(swagger['paths'][httpPath][method]['x-hints']):
+        (fp, last) = cargo
+        print >> sys.stderr, 'remove newline after @HINTS in file %s' % (fp.name)
+        exit(1)
+
+    return ret
+
 ################################################################################
 ### @brief restdescription
 ################################################################################
@@ -888,8 +908,8 @@ def restdescription(cargo, r=Regexen()):
     swagger['paths'][httpPath][method]['description'] += '\n\n'
 
     ret = generic_handler_desc(cargo, r, "restdescription", None,
-                                swagger['paths'][httpPath][method],
+                               swagger['paths'][httpPath][method],
-                                'description')
+                               'description')
 
     if r.TRIPLENEWLINEATSTART.match(swagger['paths'][httpPath][method]['description']):
         (fp, last) = cargo
@@ -1165,6 +1185,7 @@ automat.add_state(comment)
 automat.add_state(eof, end_state=1)
 automat.add_state(error, end_state=1)
 automat.add_state(start_docublock)
+automat.add_state(hints)
 automat.add_state(example_arangosh_run)
 automat.add_state(examples)
 automat.add_state(skip_code)
@@ -1314,7 +1335,7 @@ for version in f:
 f.close()
 
 
-paths = {};
+paths = {}
 
 topdir = sys.argv[4]
 files = {}
@@ -1352,7 +1373,7 @@ def descOffsetGet(value):
 
 for route in swagger['paths'].keys():
     for verb in swagger['paths'][route].keys():
-        offsetPlus = 0;
+        offsetPlus = 0
         thisVerb = swagger['paths'][route][verb]
         if len(thisVerb['description']) == 0:
             print >> sys.stderr, "Description of Route empty; @RESTDESCRIPTION missing?"
@@ -1424,6 +1445,18 @@ for route in swagger['paths'].keys():
             #print '-'*80
             #print thisVerb['description']
 
+        # Simplify hint box code to something that works in Swagger UI
+        # Append the result to the description field
+        # Place invisible markers, so that hints can be removed again
+        if 'x-hints' in thisVerb and len(thisVerb['x-hints']) > 0:
+            thisVerb['description'] += '\n<!-- Hints Start -->'
+            tmp = re.sub("{% hint '([^']+?)' %}",
+                         lambda match: "\n\n**{}:**  ".format(match.group(1).title()),
+                         thisVerb['x-hints'])
+            tmp = re.sub('{%[^%]*?%}', '', tmp)
+            thisVerb['description'] += tmp
+            thisVerb['description'] += '\n<!-- Hints End -->'
+
         # Append the examples to the description:
         if 'x-examples' in thisVerb and len(thisVerb['x-examples']) > 0:
             thisVerb['description'] += '\n'