Doc - check for no new line after restdescription (#4883)

Documentation/DocuBlocks/Rest/AQL/delete_api_aqlfunction.md

@@ -19,7 +19,6 @@ the name of the AQL user function.
   qualified, including any namespaces. If none matches the *name*, HTTP 404 is returned. 
 
 @RESTDESCRIPTION
-
 Removes an existing AQL user function or function group, identified by *name*.
 
 @RESTRETURNCODES

Documentation/DocuBlocks/Rest/Administration/get_admin_database_version.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/database/target-version, Return the required version of the database}
 
 @RESTDESCRIPTION
-
 Returns the database-version that this server requires.
 The version is returned in the *version* attribute of the result.
 

Documentation/DocuBlocks/Rest/Administration/get_admin_routing_reloads.md

@@ -5,7 +5,6 @@
 @RESTHEADER{POST /_admin/routing/reload, Reloads the routing information}
 
 @RESTDESCRIPTION
-
 Reloads the routing information from the collection *routing*.
 
 @RESTRETURNCODES

Documentation/DocuBlocks/Rest/Administration/get_admin_server_role.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/server/role, Return role of a server in a cluster}
 
 @RESTDESCRIPTION
-
 Returns the role of a server in a cluster.
 The role is returned in the *role* attribute of the result.
 Possible return values for *role* are:

Documentation/DocuBlocks/Rest/Administration/get_admin_statistics.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/statistics, Read the statistics}
 
 @RESTDESCRIPTION
-
 Returns the statistics information. The returned object contains the
 statistics figures grouped together according to the description returned by
 *_admin/statistics-description*. For instance, to access a figure *userTime*

Documentation/DocuBlocks/Rest/Administration/get_admin_statistics_description.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/statistics-description, Statistics description}
 
 @RESTDESCRIPTION
-
 Returns a description of the statistics returned by */_admin/statistics*.
 The returned objects contains an array of statistics groups in the attribute
 *groups* and an array of statistics figures in the attribute *figures*.

Documentation/DocuBlocks/Rest/Administration/get_admin_time.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/time, Return system time}
 
 @RESTDESCRIPTION
-
 The call returns an object with the attribute *time*. This contains the
 current system time as a Unix timestamp with microsecond precision.
 

Documentation/DocuBlocks/Rest/Administration/get_api_cluster_endpoints.md

@@ -4,7 +4,6 @@
 @RESTHEADER{GET /_api/cluster/endpoints, Get information about all coordinator endpoints}
 
 @RESTDESCRIPTION 
-
 Returns an object with an attribute `endpoints`, which contains an
 array of objects, which each have the attribute `endpoint`, whose value
 is a string with the endpoint description. There is an entry for each

Documentation/DocuBlocks/Rest/Administration/post_admin_execute.md

@@ -8,7 +8,6 @@
 The body to be executed.
 
 @RESTDESCRIPTION
-
 Executes the javascript code in the body on the server as the body
 of a function with no arguments. If you have a *return* statement
 then the return value you produce will be returned as content type

Documentation/DocuBlocks/Rest/Cluster/get_cluster_statistics.md

@@ -8,7 +8,8 @@
 
 @RESTQUERYPARAM{DBserver,string,required}
 
-@RESTDESCRIPTION Queries the statistics of the given DBserver
+@RESTDESCRIPTION
+Queries the statistics of the given DBserver
 
 @RESTRETURNCODES
 

Documentation/DocuBlocks/Rest/Cursors/post_api_cursor_identifier.md

@@ -10,7 +10,6 @@
 The name of the cursor
 
 @RESTDESCRIPTION
-
 If the cursor is still alive, returns an object with the following
 attributes:
 

Documentation/DocuBlocks/Rest/Indexes/get_api_index.md

@@ -10,7 +10,6 @@
 The collection name.
 
 @RESTDESCRIPTION
-
 Returns an object with an attribute *indexes* containing an array of all
 index descriptions for the given collection. The same information is also
 available in the *identifiers* as an object with the index handles as

Documentation/DocuBlocks/Rest/Indexes/get_api_reads_index.md

@@ -10,7 +10,6 @@
 The index-handle.
 
 @RESTDESCRIPTION
-
 The result is an object describing the index. It has at least the following
 attributes:
 

Documentation/DocuBlocks/Rest/Indexes/post_api_index_delete.md

@@ -10,7 +10,6 @@
 The index handle.
 
 @RESTDESCRIPTION
-
 Deletes an index with *index-handle*.
 
 @RESTRETURNCODES

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

@@ -8,7 +8,6 @@
 Contains the query.
 
 @RESTDESCRIPTION
-
 Returns all documents of a collections. Equivalent to the AQL query
 `FOR doc IN collection RETURN doc`. The call expects a JSON object
 as body with the following attributes:

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

@@ -5,7 +5,6 @@
 @RESTHEADER{PUT /_api/simple/any, Return a random document}
 
 @RESTDESCRIPTION
-
 Returns a random document from a collection. The call expects a JSON object
 as body with the following attributes:
 

Documentation/DocuBlocks/Rest/User Management/README.md

@@ -23,7 +23,6 @@ specified, this will default to true
 An optional JSON object with arbitrary extra data about the user.
 
 @RESTDESCRIPTION
-
 Create a new user. You need server access level *Administrate* in order to
 execute this REST call.
 
@@ -85,7 +84,6 @@ The name of the user.
 The name of the database.
 
 @RESTDESCRIPTION
-
 Sets the database access levels for the database *dbname* of user *user*. You
 need the *Administrate* server access level in order to execute this REST
 call.
@@ -141,7 +139,6 @@ The name of the user.
 The name of the database.
 
 @RESTDESCRIPTION
-
 Clears the database access level for the database *dbname* of user *user*. As
 consequence the default database access level is used. If there is no defined
 default database access level, it defaults to *No access*. You need permission
@@ -201,7 +198,6 @@ The name of the database.
 The name of the collection.
 
 @RESTDESCRIPTION
-
 Sets the collection access level for the *collection* in the database *dbname*
 for user *user*. You need the *Administrate* server access level in order to
 execute this REST call.
@@ -261,7 +257,6 @@ The name of the database.
 The name of the collection.
 
 @RESTDESCRIPTION
-
 Clears the collection access level for the collection *collection* in the
 database *dbname* of user *user*.  As consequence the default collection
 access level is used. If there is no defined default collection access level,
@@ -314,7 +309,6 @@ The name of the user for which you want to query the databases.
 Return the full set of access levels for all databases and all collections.
 
 @RESTDESCRIPTION
-
 Fetch the list of databases available to the specified *user*. You need
 *Administrate* for the server access level in order to execute this REST call.
 
@@ -393,7 +387,6 @@ The name of the user for which you want to query the databases.
 The name of the database to query
 
 @RESTDESCRIPTION
-
 Fetch the database access level for a specific database
 
 @RESTRETURNCODES
@@ -449,7 +442,6 @@ The name of the database to query
 The name of the collection
 
 @RESTDESCRIPTION
-
 Returns the collection access level for a specific collection
 
 @RESTRETURNCODES
@@ -510,7 +502,6 @@ specified, this will default to true
 An optional JSON object with arbitrary extra data about the user.
 
 @RESTDESCRIPTION
-
 Replaces the data of an existing user. The name of an existing user must be
 specified in *user*. You need server access level *Administrate* in order to
 execute this REST call. Additionally, a user can change his/her own data.
@@ -576,7 +567,6 @@ specified, this will default to true
 An optional JSON object with arbitrary extra data about the user.
 
 @RESTDESCRIPTION
-
 Partially updates the data of an existing user. The name of an existing user
 must be specified in *user*. You need server access level *Administrate* in
 order to execute this REST call. Additionally, a user can change his/her own
@@ -634,7 +624,6 @@ The specified user does not exist
 The name of the user
 
 @RESTDESCRIPTION
-
 Removes an existing user, identified by *user*.  You need *Administrate* for
 the server access level in order to execute this REST call.
 
@@ -683,7 +672,6 @@ The specified user does not exist
 The name of the user
 
 @RESTDESCRIPTION
-
 Fetches data about the specified user. You can fetch information about
 yourself or you need the *Administrate* server access level in order to
 execute this REST call.
@@ -729,7 +717,6 @@ The user with the specified name does not exist.
 @RESTHEADER{GET /_api/user/, List available Users}
 
 @RESTDESCRIPTION
-
 Fetches data about all users.  You need the *Administrate* server access level
 in order to execute this REST call.  Otherwise, you will only get information
 about yourself.

Documentation/DocuBlocks/Rest/Views/get_api_view_properties.md

@@ -7,6 +7,7 @@
 @RESTURLPARAMETERS
 
 @RESTDESCRIPTION
+TBD
 
 @RESTURLPARAM{view-name,string,required}
 The name of the view.

Documentation/DocuBlocks/Rest/wal/get_admin_wal_properties.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/wal/properties, Retrieves the configuration of the write-ahead log}
 
 @RESTDESCRIPTION
-
 Retrieves the configuration of the write-ahead log. The result is a JSON
 object with the following attributes:
 - *allowOversizeEntries*: whether or not operations that are bigger than a

Documentation/DocuBlocks/Rest/wal/get_admin_wal_transactions.md

@@ -5,7 +5,6 @@
 @RESTHEADER{GET /_admin/wal/transactions, Returns information about the currently running transactions}
 
 @RESTDESCRIPTION
-
 Returns information about the currently running transactions. The result
 is a JSON object with the following attributes:
 - *runningTransactions*: number of currently running transactions

Documentation/DocuBlocks/Rest/wal/put_admin_wal_flush.md

@@ -18,7 +18,6 @@ long-running transactions and the write-ahead log garbage collector cannot
 finish garbage collection.
 
 @RESTDESCRIPTION
-
 Flushes the write-ahead log. By flushing the currently active write-ahead
 logfile, the data in it can be transferred to collection journals and
 datafiles. This is useful to ensure that all data for a collection is

Documentation/DocuBlocks/Rest/wal/put_admin_wal_properties.md

@@ -5,7 +5,6 @@
 @RESTHEADER{PUT /_admin/wal/properties, Configures the write-ahead log}
 
 @RESTDESCRIPTION
-
 Configures the behavior of the write-ahead log. The body of the request
 must be a JSON object with the following attributes:
 - *allowOversizeEntries*: whether or not operations that are bigger than a

utils/generateSwagger.py

@@ -391,6 +391,7 @@ class Regexen:
         self.RESTRETURNCODES = re.compile('.*@RESTRETURNCODES')
         self.RESTURLPARAM = re.compile('.*@RESTURLPARAM{')
         self.RESTURLPARAMETERS = re.compile('.*@RESTURLPARAMETERS')
+        self.TRIPLENEWLINEATSTART = re.compile('^\n\n\n')
 
 ################################################################################
 ### @brief checks for end of comment
@@ -864,10 +865,18 @@ def restqueryparam(cargo, r=Regexen()):
 def restdescription(cargo, r=Regexen()):
     global swagger, operation, httpPath, method
     swagger['paths'][httpPath][method]['description'] += '\n\n'
-    return generic_handler_desc(cargo, r, "restdescription", None,
+
+    ret = generic_handler_desc(cargo, r, "restdescription", None,
                                 swagger['paths'][httpPath][method],
                                 'description')
 
+    if r.TRIPLENEWLINEATSTART.match(swagger['paths'][httpPath][method]['description']):
+        (fp, last) = cargo
+        print >> sys.stderr, 'remove newline after @RESTDESCRIPTION in file %s' % (fp.name)
+        exit(1)
+
+    return ret
+
 ################################################################################
 ### @brief restreplybody
 ################################################################################