From bbb8198d2be525ed8987b882d75c253c75e98bb5 Mon Sep 17 00:00:00 2001 From: Willi Goesgens Date: Wed, 12 Aug 2015 16:58:06 +0200 Subject: [PATCH] Add a @brief to all descriptions, remove stray markup. --- arangod/RestHandler/RestQueryCacheHandler.cpp | 9 ++++-- .../RestHandler/RestReplicationHandler.cpp | 28 +++++++++++++++++++ arangod/V8Server/v8-collection.cpp | 2 +- js/actions/_admin/app.js | 8 ++++++ js/actions/_admin/routing/app.js | 1 + js/actions/_admin/server/app.js | 1 + js/actions/_admin/wal/app.js | 3 ++ js/actions/_api/collection/app.js | 5 ++++ js/actions/_api/user/app.js | 5 ++++ js/actions/api-simple.js | 15 +++++----- js/actions/api-traversal.js | 2 +- 11 files changed, 67 insertions(+), 12 deletions(-) diff --git a/arangod/RestHandler/RestQueryCacheHandler.cpp b/arangod/RestHandler/RestQueryCacheHandler.cpp index f425967ce7..36d0b4801d 100644 --- a/arangod/RestHandler/RestQueryCacheHandler.cpp +++ b/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} diff --git a/arangod/RestHandler/RestReplicationHandler.cpp b/arangod/RestHandler/RestReplicationHandler.cpp index 77121dd3dd..8062e7da59 100644 --- a/arangod/RestHandler/RestReplicationHandler.cpp +++ b/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 diff --git a/arangod/V8Server/v8-collection.cpp b/arangod/V8Server/v8-collection.cpp index ddf68298fd..1f9ae04403 100644 --- a/arangod/V8Server/v8-collection.cpp +++ b/arangod/V8Server/v8-collection.cpp @@ -2962,7 +2962,7 @@ static string GetId (const v8::FunctionCallbackInfo& 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" }); diff --git a/js/actions/_admin/app.js b/js/actions/_admin/app.js index 26b686974c..a9d2bb76cd 100644 --- a/js/actions/_admin/app.js +++ b/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} /// diff --git a/js/actions/_admin/routing/app.js b/js/actions/_admin/routing/app.js index 115cf271c6..b1a7ea684b 100644 --- a/js/actions/_admin/routing/app.js +++ b/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} /// diff --git a/js/actions/_admin/server/app.js b/js/actions/_admin/server/app.js index 14bf33ad85..f1c6d2d0ea 100644 --- a/js/actions/_admin/server/app.js +++ b/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} /// diff --git a/js/actions/_admin/wal/app.js b/js/actions/_admin/wal/app.js index b8629b7073..7467e84c0e 100644 --- a/js/actions/_admin/wal/app.js +++ b/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} /// diff --git a/js/actions/_api/collection/app.js b/js/actions/_api/collection/app.js index fdc9a71177..ede4e7a7b7 100644 --- a/js/actions/_api/collection/app.js +++ b/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} /// diff --git a/js/actions/_api/user/app.js b/js/actions/_api/user/app.js index 855906a145..6c9dcd2f8e 100644 --- a/js/actions/_api/user/app.js +++ b/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} /// diff --git a/js/actions/api-simple.js b/js/actions/api-simple.js index 5bc9b76e17..106e144907 100644 --- a/js/actions/api-simple.js +++ b/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 /// diff --git a/js/actions/api-traversal.js b/js/actions/api-traversal.js index c6d5fb32e0..b7a39b9653 100644 --- a/js/actions/api-traversal.js +++ b/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} ///