From e4c5135cbb02f0b79c547f2a637cd0da0bf6c7e5 Mon Sep 17 00:00:00 2001 From: Frank Celler Date: Sun, 11 Mar 2012 07:36:34 +0100 Subject: [PATCH] doc --- RestServer/{install.h => install-manual.dox} | 0 RestServer/ref-manual.dox | 157 ++++++++++++ RestServer/user-manual-avocsh.dox | 199 +++++++++++++++ RestServer/user-manual-server.dox | 254 +++++++++++++++++++ 4 files changed, 610 insertions(+) rename RestServer/{install.h => install-manual.dox} (100%) create mode 100644 RestServer/ref-manual.dox create mode 100644 RestServer/user-manual-avocsh.dox create mode 100644 RestServer/user-manual-server.dox diff --git a/RestServer/install.h b/RestServer/install-manual.dox similarity index 100% rename from RestServer/install.h rename to RestServer/install-manual.dox diff --git a/RestServer/ref-manual.dox b/RestServer/ref-manual.dox new file mode 100644 index 0000000000..5392ee7604 --- /dev/null +++ b/RestServer/ref-manual.dox @@ -0,0 +1,157 @@ +//////////////////////////////////////////////////////////////////////////////// +/// @brief installation guide +/// +/// @file +/// +/// DISCLAIMER +/// +/// Copyright 2012 triagens GmbH, Cologne, Germany +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// +/// Copyright holder is triAGENS GmbH, Cologne, Germany +/// +/// @author Dr. Frank Celler +/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page RefManual AvocadoDB Reference Manual +/// +///
    +///
  1. @ref JSModules +///
      +///
    1. @ref JSModuleActions +///
      2. +///
    2. @ref JSModuleConsole +///
      3. +///
    3. @ref JSModuleFs +///
      4. +///
    4. @ref JSModuleGraph +///
      5. +///
    5. @ref JSModuleInternal +///
      6. +///
    +///
  2. @ref CommandLine +///
      +///
    1. @ref CommandLineAvocado +///
      2. +///
    2. @ref CommandLineScheduler +///
      3. +///
    3. @ref CommandLineLogging +///
      4. +///
    4. @ref CommandLineRandom +///
      5. +///
    +///
    3. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page CommandLineTOC +/// +///
    +///
  1. configuration
    2. +///
  2. daemon
    3. +///
  3. gid
    4. +///
  4. help
    5. +///
  5. pid-file
    6. +///
  6. uid
    7. +///
  7. version
    8. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page CommandLine Command-Line Options +/// +///
+/// @copydoc CommandLineTOC +///
+/// +/// @section GeneralOptions General Options +/// +/// @copydetails triagens::rest::ApplicationServerImpl::initFile +/// +/// @CMDOPT{--daemon} +/// +/// Runs the server as a daemon (as a background process). This parameter can +/// only be set if the pid (process id) file is specified. That is, unless a +/// value to the parameter pid-file is given, then the server will report an +/// error and exit. +/// +/// @copydetails triagens::rest::ApplicationServerImpl::gid +/// +/// @copydetails triagens::rest::ApplicationServerImpl::options +/// +/// @copydetails triagens::rest::AnyServer::_pidFile +/// +/// @CMDOPT{--show-io-backends} +/// +/// If this option is specified, then the server will list available backends +/// and exit. This option is useful only when used in conjunction with the +/// option scheduler.backend. An integer is returned (which is platform +/// dependent) which indicates available backends on your platform. See libev +/// for further details and for the meaning of the integer returned. This +/// describes the allowed integers for @CODE{scheduler.backend}, see +/// @ref CommandLineScheduler "here" for details. +/// +/// @CMDOPT{--supervisor} +/// +/// Executes the server in supervisor mode. In the event that the server +/// unexpectedly terminates due to an internal error, the supervisor will +/// automatically restart the server. Setting this flag automatically implies +/// that the server will run as a daemon. Note that, as with the daemon flag, +/// this flag requires that the pid-file parameter will set. +/// +/// @copydetails triagens::rest::ApplicationServerImpl::uid +/// +/// @copydetails triagens::rest::ApplicationServerImpl::version +/// +///
+/// Next steps: +/// +/// - @ref CommandLineAvocado "Command-Line Options for the AvocadoDB" +/// - @ref CommandLineScheduler "Command-Line Options for Communication" +/// - @ref CommandLineLogging "Command-Line Options for Logging" +/// - @ref CommandLineRandom "Command-Line Options for Random Numbers" +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page CommandLineAvocadoTOC +/// +///
    +///
  1. database.directory
    2. +///
  2. server.admin-port
    3. +///
  3. server.http-port
    4. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page CommandLineAvocado Command-Line Options for the AvocadoDB +/// +///
+/// @copydoc CommandLineAvocadoTOC +///
+/// +/// @copydetails triagens::avocado::AvocadoServer::_databasePath +/// +/// @copydetails triagens::avocado::AvocadoServer::_adminPort +/// +/// @copydetails triagens::avocado::AvocadoServer::_httpPort +//////////////////////////////////////////////////////////////////////////////// + +// Local Variables: +// mode: c++ +// mode: outline-minor +// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)" +// End: diff --git a/RestServer/user-manual-avocsh.dox b/RestServer/user-manual-avocsh.dox new file mode 100644 index 0000000000..077e7087c8 --- /dev/null +++ b/RestServer/user-manual-avocsh.dox @@ -0,0 +1,199 @@ +//////////////////////////////////////////////////////////////////////////////// +/// @brief installation guide +/// +/// @file +/// +/// DISCLAIMER +/// +/// Copyright 2012 triagens GmbH, Cologne, Germany +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// +/// Copyright holder is triAGENS GmbH, Cologne, Germany +/// +/// @author Dr. Frank Celler +/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page UserManualShell User Manual for the AvocadoDB Shell +/// +///
    +///
  1. @ref UserManualShellBasics +///
      +///
    1. @ref StartStop +///
      2. +///
    2. AvocadoScript +///
        +///
      1. @ref SimpleQueries +///
        2. +///
      +///
      3. +///
    3. Vertices, Edges, and Graphs +///
        +///
      1. @ref Graphs +///
        2. +///
      2. @ref JSModuleGraph +///
        3. +///
      +///
      4. +///
    +///
    2. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page UserManualShellBasics Basics +/// +/// The AvocadoDB groups documents into collections. Each collection can be +/// accessed using queries. For simple queries involving just one collection, +/// you can use a fluent interface from within JavaScript code, see @ref +/// AvocadoScript. This interface allows you to select documents from one +/// collection based on simple search criteria. The @ref HttpInterface +/// lets you create, modify, or delete a single document via HTTP. For +/// more complex queries, you can use the Avocado Query Language, which is +/// an extension of SQL resp. UNQL. +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page StartStopTOC +/// +///
    +///
  1. @ref StartStopHttp "Starting the HTTP Server"
    2. +///
  2. @ref StartStopDebug "Starting the Debug Shell"
    3. +///
  3. @ref StartStopOptions "Frequently Used Options"
    4. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page StartStop Starting the AvocadoDB +/// +/// The AvocadoDB has two mode of operation: as server, where it will answer to +/// HTTP requests, see @ref HttpInterface, and a debug shell, where you can +/// access the database directly. Using the debug shell allows you to issue all +/// commands normally available in actions and transactions, see @ref +/// AvocadoScript. +/// +/// You should never start more than one server for the same database, +/// independent from the mode of operation. +/// +///
+/// @copydoc StartStopTOC +///
+/// +/// @section StartStopHttp Starting the HTTP Server +/// +/// The following command starts the AvocadoDB in server mode. You will be able +/// to access the server using HTTP request on port 8529. See below for a list +/// of frequently used options, see @ref CommandLine "here" for a complete list. +/// +/// @verbinclude start2 +/// +/// @section StartStopDebug Starting the Debug Shell +/// +/// The following command starts a debug shell. See below for a list of +/// frequently used options, see @ref CommandLine "here" for a complete list. +/// +/// @verbinclude start1 +/// +/// @section StartStopOptions Frequently Used Options +/// +/// The following command-line options are frequently used. For a full +/// list of options see @ref CommandLine "here". +/// +/// @CMDOPT{@CA{database-directory}} +/// +/// Uses the @CA{database-directory} as base directory. There is an alternative +/// version available for use in configuration files, see @ref +/// CommandLineAvocado "here". +/// +/// @copydetails triagens::rest::ApplicationServerImpl::options +/// +/// @CMDOPT{--log @CA{level}} +/// +/// Allows the user to choose the level of information which is logged by the +/// server. The @CA{level} is specified as a string and can be one of the +/// following values: fatal, error, warning, info, debug, trace. For more +/// information see @ref CommandLineLogging "here". +/// +/// @copydetails triagens::avocado::AvocadoServer::_httpPort +/// +/// @CMDOPT{--shell} +/// +/// Opens a debug shell instead of starting the HTTP server. +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page DBAdminTOC +/// +///
    +///
  1. @ref DBAdminDurability +///
    2. +///
  2. @ref DBAdminIndex +///
      +///
    1. @ref DBAdminIndexGeo +///
    +///
    3. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page DBAdmin Database Administration +/// +///
+/// @copydetails DBAdminTOC +///
+/// +/// @section DBAdminDurability Durability +/// +/// @subsection DBAdminDurability1 Mostly Memory/Durability +/// +/// Database documents are stored in the memory-memory-mapped files are used to +/// store them. The operating system has the advantageous option to decide +/// swapping sparsely used areas out of the main memory. Per default, these +/// memory-mapped files are synced frequently - advantageously storing all +/// documents securely at once (durability). +/// +/// @subsection DBAdminDurability2 AppendOnly/MVCC +/// +/// Instead of overwriting existing documents, a completely new version of the +/// document is generated. The two benefits are: +/// +/// - Objects can be stored coherently and compactly in the main memory. +/// - Objects are preserved-isolated writing and reading transactions allow +/// accessing these objects for parallel operations. +/// +/// The system collects obsolete versions as garbage, recognizing them as +/// forsaken. Garbage collection is asynchronous and runs parallel to other +/// processes. +/// +/// @subsection DBAdminDurability3 Configuration +/// +/// @copydetails JS_ParameterVocbaseCol +/// +/// @section DBAdminIndex Index Management +/// +/// @subsection DBAdminIndexHash Hash Indexes +/// +/// @copydetails JS_EnsureHashIndexVocbaseCol +/// +/// @subsection DBAdminIndexGeo Geo Indexes +/// +/// @copydetails JS_EnsureGeoIndexVocbaseCol +//////////////////////////////////////////////////////////////////////////////// + +// Local Variables: +// mode: c++ +// mode: outline-minor +// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)" +// End: diff --git a/RestServer/user-manual-server.dox b/RestServer/user-manual-server.dox new file mode 100644 index 0000000000..8b09cbc3ce --- /dev/null +++ b/RestServer/user-manual-server.dox @@ -0,0 +1,254 @@ +//////////////////////////////////////////////////////////////////////////////// +/// @brief installation guide +/// +/// @file +/// +/// DISCLAIMER +/// +/// Copyright 2012 triagens GmbH, Cologne, Germany +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// +/// Copyright holder is triAGENS GmbH, Cologne, Germany +/// +/// @author Dr. Frank Celler +/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page UserManualServer User Manual for the AvocadoDB Server +/// +///
    +///
  1. @ref UserManualServerBasics +///
      +///
    1. @ref UserManualServerStartStop +///
      2. +///
    2. AvocadoScript +///
        +///
      1. @ref SimpleQueries +///
        2. +///
      +///
      3. +///
    3. @ref AQL +///
        +///
      1. @ref Optimizer +///
        2. +///
      2. @ref IndexUsage +///
        3. +///
      +///
      4. +///
    4. @ref AvocadoScript +///
        +///
      1. @ref GeoCoordinates +///
        2. +///
      +///
      5. +///
    5. Vertices, Edges, and Graphs +///
        +///
      1. @ref Graphs +///
        2. +///
      2. @ref JSModuleGraph +///
        3. +///
      +///
      6. +///
    +///
    2. +///
  2. Client Communication +///
      +///
    1. @ref HttpInterface +///
        +///
      1. @ref RestDocument +///
        2. +///
      +///
      2. +///
    +///
    3. +///
  3. @ref DBAdmin +///
      +///
    1. @ref DBAdminDurability +///
      2. +///
    2. @ref DBAdminIndex +///
        +///
      1. @ref DBAdminIndexGeo +///
      +///
      3. +///
    +///
    4. +///
  4. Advanced Topics +///
      +///
    1. Actions +///
        +///
      1. @ref Actions +///
        2. +///
      2. @ref DefineAction +///
        3. +///
      +///
      2. +///
    2. @ref HttpInterface +///
        +///
      1. @ref RestSystem +///
        2. +///
      +///
      3. +///
    3. @ref jsUnity +///
      4. +///
    +///
    5. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page UserManualServerBasics Basics +/// +/// The AvocadoDB groups documents into collections. Each collection can be +/// accessed using queries. For simple queries involving just one collection, +/// you can use a fluent interface from within JavaScript code, see @ref +/// AvocadoScript. This interface allows you to select documents from one +/// collection based on simple search criteria. The @ref HttpInterface +/// lets you create, modify, or delete a single document via HTTP. For +/// more complex queries, you can use the Avocado Query Language, which is +/// an extension of SQL resp. UNQL. +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page UserManualServerStartStopTOC +/// +///
    +///
  1. @ref UserManualServerStartStopHttp "Starting the HTTP Server"
    2. +///
  2. @ref UserManualServerStartStopDebug "Starting the Debug Shell"
    3. +///
  3. @ref UserManualServerStartStopOptions "Frequently Used Options"
    4. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page UserManualServerStartStop Starting the AvocadoDB +/// +/// The AvocadoDB has two mode of operation: as server, where it will answer to +/// HTTP requests, see @ref HttpInterface, and a debug shell, where you can +/// access the database directly. Using the debug shell allows you to issue all +/// commands normally available in actions and transactions, see @ref +/// AvocadoScript. +/// +/// You should never start more than one server for the same database, +/// independent from the mode of operation. +/// +///
+/// @copydoc UserManualServerStartStopTOC +///
+/// +/// @section UserManualServerStartStopHttp Starting the HTTP Server +/// +/// The following command starts the AvocadoDB in server mode. You will be able +/// to access the server using HTTP request on port 8529. See below for a list +/// of frequently used options, see @ref CommandLine "here" for a complete list. +/// +/// @verbinclude start2 +/// +/// @section UserManualServerStartStopDebug Starting the Debug Shell +/// +/// The following command starts a debug shell. See below for a list of +/// frequently used options, see @ref CommandLine "here" for a complete list. +/// +/// @verbinclude start1 +/// +/// @section UserManualServerStartStopOptions Frequently Used Options +/// +/// The following command-line options are frequently used. For a full +/// list of options see @ref CommandLine "here". +/// +/// @CMDOPT{@CA{database-directory}} +/// +/// Uses the @CA{database-directory} as base directory. There is an alternative +/// version available for use in configuration files, see @ref +/// CommandLineAvocado "here". +/// +/// @copydetails triagens::rest::ApplicationServerImpl::options +/// +/// @CMDOPT{--log @CA{level}} +/// +/// Allows the user to choose the level of information which is logged by the +/// server. The @CA{level} is specified as a string and can be one of the +/// following values: fatal, error, warning, info, debug, trace. For more +/// information see @ref CommandLineLogging "here". +/// +/// @copydetails triagens::avocado::AvocadoServer::_httpPort +/// +/// @CMDOPT{--shell} +/// +/// Opens a debug shell instead of starting the HTTP server. +//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page DBAdminTOC +/// +///
    +///
  1. @ref DBAdminDurability +///
    2. +///
  2. @ref DBAdminIndex +///
      +///
    1. @ref DBAdminIndexGeo +///
    +///
    3. +///
+//////////////////////////////////////////////////////////////////////////////// + +//////////////////////////////////////////////////////////////////////////////// +/// @page DBAdmin Database Administration +/// +///
+/// @copydetails DBAdminTOC +///
+/// +/// @section DBAdminDurability Durability +/// +/// @subsection DBAdminDurability1 Mostly Memory/Durability +/// +/// Database documents are stored in the memory-memory-mapped files are used to +/// store them. The operating system has the advantageous option to decide +/// swapping sparsely used areas out of the main memory. Per default, these +/// memory-mapped files are synced frequently - advantageously storing all +/// documents securely at once (durability). +/// +/// @subsection DBAdminDurability2 AppendOnly/MVCC +/// +/// Instead of overwriting existing documents, a completely new version of the +/// document is generated. The two benefits are: +/// +/// - Objects can be stored coherently and compactly in the main memory. +/// - Objects are preserved-isolated writing and reading transactions allow +/// accessing these objects for parallel operations. +/// +/// The system collects obsolete versions as garbage, recognizing them as +/// forsaken. Garbage collection is asynchronous and runs parallel to other +/// processes. +/// +/// @subsection DBAdminDurability3 Configuration +/// +/// @copydetails JS_ParameterVocbaseCol +/// +/// @section DBAdminIndex Index Management +/// +/// @subsection DBAdminIndexHash Hash Indexes +/// +/// @copydetails JS_EnsureHashIndexVocbaseCol +/// +/// @subsection DBAdminIndexGeo Geo Indexes +/// +/// @copydetails JS_EnsureGeoIndexVocbaseCol +//////////////////////////////////////////////////////////////////////////////// + +// Local Variables: +// mode: c++ +// mode: outline-minor +// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)" +// End: