Add a @brief to all descriptions, remove stray markup.

arangod/RestHandler/RestQueryCacheHandler.cpp

@@ -95,8 +95,9 @@ HttpHandler::status_t RestQueryCacheHandler::execute () {
 // -----------------------------------------------------------------------------
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief clears the AQL query cache
 /// @startDocuBlock DeleteApiQueryCache
+/// @brief clears the AQL query cache
+///
 /// @RESTHEADER{DELETE /_api/query-cache, Clears any results in the AQL query cache}
 ///
 /// @RESTRETURNCODES
@@ -125,8 +126,9 @@ bool RestQueryCacheHandler::clearCache () {
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief returns the global configuration for the AQL query cache
 /// @startDocuBlock GetApiQueryCacheProperties
+/// @brief returns the global configuration for the AQL query cache
+///
 /// @RESTHEADER{GET /_api/query-cache/properties, Returns the global properties for the AQL query cache}
 ///
 /// Returns the global AQL query cache configuration. The configuration is a
@@ -172,8 +174,9 @@ bool RestQueryCacheHandler::readProperties () {
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief changes the configuration for the AQL query cache
 /// @startDocuBlock PutApiQueryCacheProperties
+/// @brief changes the configuration for the AQL query cache
+///
 /// @RESTHEADER{PUT /_api/query-cache/properties, Changes the global properties for the AQL query cache}
 ///
 /// @RESTBODYPARAM{properties,json,required}

arangod/RestHandler/RestReplicationHandler.cpp

@@ -515,6 +515,8 @@ void RestReplicationHandler::handleCommandLoggerState () {
 ///
 /// @RESTHEADER{POST /_api/replication/batch, Create new dump batch}
 ///
+/// **Note**: These calls are uninteresting to users.
+///
 /// @RESTBODYPARAM{body,json,required}
 /// A JSON object with the batch configuration.
 ///
@@ -552,6 +554,8 @@ void RestReplicationHandler::handleCommandLoggerState () {
 ///
 /// @RESTHEADER{PUT /_api/replication/batch/{id}, Prolong existing dump batch}
 ///
+/// **Note**: These calls are uninteresting to users.
+///
 /// @RESTBODYPARAM{body,json,required}
 /// A JSON object with the batch configration.
 ///
@@ -592,6 +596,8 @@ void RestReplicationHandler::handleCommandLoggerState () {
 ///
 /// @RESTHEADER{DELETE /_api/replication/batch/{id}, Deletes an existing dump batch}
 ///
+/// **Note**: These calls are uninteresting to users.
+///
 /// @RESTURLPARAMETERS
 ///
 /// @RESTURLPARAM{id,string,required}
@@ -789,6 +795,8 @@ void RestReplicationHandler::handleTrampolineCoordinator () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_api_replication_logger_returns
+/// @brief Fetch log lines from the server
+///
 /// @RESTHEADER{GET /_api/replication/logger-follow, Returns log entries}
 ///
 /// @RESTQUERYPARAMETERS
@@ -1087,6 +1095,8 @@ void RestReplicationHandler::handleCommandLoggerFollow () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_inventory
+/// @brief Returns an overview of collections and their indexes
+///
 /// @RESTHEADER{GET /_api/replication/inventory, Return inventory of collections and indexes}
 ///
 /// @RESTQUERYPARAMETERS
@@ -1273,6 +1283,8 @@ void RestReplicationHandler::handleCommandInventory () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_api_replication_cluster_inventory
+/// @brief returs an overview of collections and indexes in a cluster
+///
 /// @RESTHEADER{GET /_api/replication/clusterInventory, Return cluster inventory of collections and indexes}
 ///
 /// @RESTQUERYPARAMETERS
@@ -2689,6 +2701,8 @@ void RestReplicationHandler::handleCommandRestoreDataCoordinator () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_api_replication_dump
+/// @brief returns the whole content of one collection
+///
 /// @RESTHEADER{GET /_api/replication/dump, Return data of a collection}
 ///
 /// @RESTQUERYPARAMETERS
@@ -2962,6 +2976,8 @@ void RestReplicationHandler::handleCommandDump () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_synchronize
+/// @brief start a replication
+///
 /// @RESTHEADER{PUT /_api/replication/sync, Synchronize data from a remote endpoint}
 ///
 /// @RESTBODYPARAM{configuration,json,required}
@@ -3154,6 +3170,8 @@ void RestReplicationHandler::handleCommandSync () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_serverID
+/// @brief fetch this servers uniq identifier
+///
 /// @RESTHEADER{GET /_api/replication/server-id, Return server id}
 ///
 /// @RESTDESCRIPTION
@@ -3203,6 +3221,8 @@ void RestReplicationHandler::handleCommandServerId () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_applier
+/// @brief fetch the current replication configuration
+///
 /// @RESTHEADER{GET /_api/replication/applier-config, Return configuration of replication applier}
 ///
 /// @RESTDESCRIPTION
@@ -3292,6 +3312,8 @@ void RestReplicationHandler::handleCommandApplierGetConfig () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_applier_adjust
+/// @brief set configuration values of an applier
+///
 /// @RESTHEADER{PUT /_api/replication/applier-config, Adjust configuration of replication applier}
 ///
 /// @RESTBODYPARAM{configuration,json,required}
@@ -3493,6 +3515,8 @@ void RestReplicationHandler::handleCommandApplierSetConfig () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_applier_start
+/// @brief start the replication applier
+///
 /// @RESTHEADER{PUT /_api/replication/applier-start, Start replication applier}
 ///
 /// @RESTQUERYPARAMETERS
@@ -3586,6 +3610,8 @@ void RestReplicationHandler::handleCommandApplierStart () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_api_replication_applier_stop
+/// @brief stop the replication
+///
 /// @RESTHEADER{PUT /_api/replication/applier-stop, Stop replication applier}
 ///
 /// @RESTDESCRIPTION
@@ -3642,6 +3668,8 @@ void RestReplicationHandler::handleCommandApplierStop () {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_api_replication_applier_state
+/// @brief output the current status of the replication
+///
 /// @RESTHEADER{GET /_api/replication/applier-state, State of the replication applier}
 ///
 /// @RESTDESCRIPTION

arangod/V8Server/v8-collection.cpp

@@ -2962,7 +2962,7 @@ static string GetId (const v8::FunctionCallbackInfo<v8::Value>& args, int which)
 ///
 /// @EXAMPLES
 ///
-/// @EXAMPLE_ARANGOSH_OUTPUT{SaveEdgeCol}
+/// @EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_01_SaveEdgeCol}
 /// ~ db._create("vertex");
 /// ~ db._createEdgeCollection("relation");
 ///   v1 = db.vertex.insert({ name : "vertex 1" });

js/actions/_admin/app.js

@@ -46,6 +46,7 @@ var arangodb = require("org/arangodb");
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_time
+/// @brief Get the current time of the system
 ///
 /// @RESTHEADER{GET /_admin/time, Return system time}
 ///
@@ -72,6 +73,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_sleep
+/// @brief Suspend the execution for a specified duration before returnig
 ///
 /// @RESTHEADER{GET /_admin/sleep?duration=5, Sleep for 5 seconds}
 ///
@@ -103,6 +105,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_echo
+/// @brief Send back what was sent in, headers, post body etc.
 ///
 /// @RESTHEADER{GET /_admin/echo, Return current request}
 ///
@@ -137,6 +140,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_long_echo
+/// @brief Send back what was sent in, headers, post body etc.
 ///
 /// @RESTHEADER{GET /_admin/long_echo, Return current request and continues}
 ///
@@ -174,6 +178,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_statistics
+/// @brief return the statistics information
 ///
 /// @RESTHEADER{GET /_admin/statistics, Read the statistics}
 ///
@@ -233,6 +238,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_statistics_description
+/// @brief fetch descriptive info of statistics
 ///
 /// @RESTHEADER{GET /_admin/statistics-description, Statistics description}
 ///
@@ -602,6 +608,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_post_admin_test
+/// @brief show the available unittests on the server.
 ///
 /// @RESTHEADER{POST /_admin/test, Runs tests on server}
 ///
@@ -659,6 +666,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_post_admin_execute
+/// @brief Execute a script on the server.
 ///
 /// @RESTHEADER{POST /_admin/execute, Execute program}
 ///

js/actions/_admin/routing/app.js

@@ -39,6 +39,7 @@ var actions = require("org/arangodb/actions");
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_routing_reloads
+/// @brief Reload the routing table.
 ///
 /// @RESTHEADER{POST /_admin/routing/reload, Reloads the routing information}
 ///

js/actions/_admin/server/app.js

@@ -37,6 +37,7 @@ var actions = require("org/arangodb/actions");
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_server_role
+/// @brief Get to know whether this server is a Coordinator or DB-Server
 ///
 /// @RESTHEADER{GET /_admin/server/role, Return role of a server in a cluster}
 ///

js/actions/_admin/wal/app.js

@@ -38,6 +38,7 @@ var actions = require("org/arangodb/actions");
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_admin_wal_flush
+/// @brief Sync the WAL to disk.
 ///
 /// @RESTHEADER{PUT /_admin/wal/flush, Flushes the write-ahead log}
 ///
@@ -90,6 +91,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_put_admin_wal_properties
+/// @brief configure parameters of the wal
 ///
 /// @RESTHEADER{PUT /_admin/wal/properties, Configures the write-ahead log}
 ///
@@ -140,6 +142,7 @@ actions.defineHttp({
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_get_admin_wal_properties
+/// @brief fetch the current configuration.
 ///
 /// @RESTHEADER{GET /_admin/wal/properties, Retrieves the configuration of the write-ahead log}
 ///

js/actions/_api/collection/app.js

@@ -473,6 +473,7 @@ function get_api_collections (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSA_get_api_collection_properties
+/// @brief reads the properties of the specified collection
 ///
 /// @RESTHEADER{GET /_api/collection/{collection-name}/properties, Read properties of a collection}
 ///
@@ -561,6 +562,7 @@ function get_api_collections (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSA_get_api_collection_count
+/// @brief Counts the documents in a collection
 ///
 /// @RESTHEADER{GET /_api/collection/{collection-name}/count, Return number of documents in a collection}
 ///
@@ -610,6 +612,7 @@ function get_api_collections (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSA_get_api_collection_figures
+/// @brief Fetch the statistics of a collection
 ///
 /// @RESTHEADER{GET /_api/collection/{collection-name}/figures, Return statistics for a collection}
 ///
@@ -743,6 +746,7 @@ function get_api_collections (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSA_get_api_collection_revision
+/// @brief Retrieve the collections revision id
 ///
 /// @RESTHEADER{GET /_api/collection/{collection-name}/revision, Return collection revision id}
 ///
@@ -791,6 +795,7 @@ function get_api_collections (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSA_get_api_collection_checksum
+/// @brief returns a checksum for the specified collection
 ///
 /// @RESTHEADER{GET /_api/collection/{collection-name}/checksum, Return checksum for the collection}
 ///

js/actions/_api/user/app.js

@@ -38,6 +38,7 @@ var users = require("org/arangodb/users");
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_api_user_fetch
+/// @brief fetch the properties of a user.
 ///
 /// @RESTHEADER{GET /_api/user/{user}, Fetch User}
 ///
@@ -97,6 +98,7 @@ function get_api_user (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_api_user_create
+/// @brief Create a new user.
 ///
 /// @RESTHEADER{POST /_api/user, Create User}
 ///
@@ -189,6 +191,7 @@ function post_api_user (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_api_user_replace
+/// @brief replace an existing user with a new one.
 ///
 /// @RESTHEADER{PUT /_api/user/{user}, Replace User}
 ///
@@ -272,6 +275,7 @@ function put_api_user (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_api_user_update
+/// @brief modify attributes of an existing user
 ///
 /// @RESTHEADER{PATCH /_api/user/{user}, Update User}
 ///
@@ -357,6 +361,7 @@ function patch_api_user (req, res) {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @startDocuBlock JSF_api_user_delete
+/// @brief delete a user permanently.
 ///
 /// @RESTHEADER{DELETE /_api/user/{user}, Remove User}
 ///

js/actions/api-simple.js

@@ -45,7 +45,8 @@ var API = "_api/simple/";
 ///
 /// RESTHEADER{PUT /_api/simple/by-example-hash, Hash index}
 ///
-/// **Note**: This is only used internally and should not be accessible by the user.
+/// **Note**: This is only used internally and should not be accessible by the user
+///           and thus this documentation is private.
 ///
 /// RESTBODYPARAM{query,string,required}
 /// Contains the query specification.
@@ -87,13 +88,13 @@ var API = "_api/simple/";
 ////////////////////////////////////////////////////////////////////////////////
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSA_put_api_simple_by_example_skiplist
 /// @brief returns all documents of a collection matching a given example,
 /// using a specific skiplist index
 ///
 /// @RESTHEADER{PUT /_api/simple/by-example-skiplist, Skiplist index}
 ///
 /// **Note**: This is only used internally and should not be accesible by the user.
+///           and thus this documentation is private.
 ///
 /// @RESTBODYPARAM{query,string,required}
 /// Contains the query specification.
@@ -132,16 +133,17 @@ var API = "_api/simple/";
 /// is returned if the collection specified by *collection* is unknown.  The
 /// response body contains an error document in this case.
 /// The same error code is also returned if an invalid index id or type is used.
-/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @startDocuBlock JSA_put_api_simple_by_condition_skiplist
 /// @brief returns all documents of a collection matching a given condition,
 /// using a specific skiplist index
 ///
 /// @RESTHEADER{PUT /_api/simple/by-condition-skiplist,Query by-condition using Skiplist index}
 ///
+/// **Note**: This is only used internally and should not be accesible by the user.
+///           and thus this documentation is private.
+///
 /// @RESTBODYPARAM{query,string,required}
 /// Contains the query specification.
 ///
@@ -179,7 +181,6 @@ var API = "_api/simple/";
 /// is returned if the collection specified by *collection* is unknown.  The
 /// response body contains an error document in this case.
 /// The same error code is also returned if an invalid index id or type is used.
-/// @endDocuBlock
 ////////////////////////////////////////////////////////////////////////////////
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -421,7 +422,7 @@ actions.defineHttp({
 /// way for retrieving documents from a collection using the near operator is
 /// to issue an [AQL query](../Aql/GeoFunctions.md) using the *NEAR* function as follows: 
 ///
-///     FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit) 
+///     FOR doc IN NEAR(@@collection, @latitude, @longitude, @limit)
 ///       RETURN doc`
 ///
 /// @RESTRETURNCODES
@@ -611,7 +612,7 @@ actions.defineHttp({
 /// to issue an [AQL query](../Aql/GeoFunctions.md) using the *WITHIN* function as follows: 
 ///
 ///     FOR doc IN WITHIN(@@collection, @latitude, @longitude, @radius, @distanceAttributeName)
-///       RETURN doc`
+///       RETURN doc
 ///
 /// @RESTRETURNCODES
 ///

js/actions/api-traversal.js

@@ -62,8 +62,8 @@ function notFound (req, res, code, message) {
 }
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief execute a server-side traversal
 /// @startDocuBlock JSF_HTTP_API_TRAVERSAL
+/// @brief execute a server-side traversal
 ///
 /// @RESTHEADER{POST /_api/traversal,executes a traversal}
 ///