From 285533ab4c9b2b44973677ccde300b14d2f15a2d Mon Sep 17 00:00:00 2001
From: Jan Steemann <jan@arangodb.com>
Date: Tue, 4 Dec 2012 11:55:04 +0100
Subject: [PATCH] added documentation for --upgrade option

---
 .../Documentation/command-line-options.dox    |  4 +++
 arangod/V8Server/ApplicationV8.h              | 27 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/arangod/Documentation/command-line-options.dox b/arangod/Documentation/command-line-options.dox
index 4a13f9bc8c..2cd917e890 100644
--- a/arangod/Documentation/command-line-options.dox
+++ b/arangod/Documentation/command-line-options.dox
@@ -35,6 +35,7 @@
 ///     <ul>
 ///      <li>@ref CommandLineHelp "help"</li>
 ///      <li>@ref CommandLineVersion "version"</li>
+///      <li>@ref CommandLineUpgrade "upgrade"</li>
 ///      <li>@ref CommandLineConfiguration "configuration"</li>
 ///      <li>@ref CommandLineDaemon "daemon"</li>
 ///      <li>@ref CommandLineDefaultLanguage "default-language"</li>
@@ -126,6 +127,9 @@
 /// @anchor CommandLineVersion
 /// @copydetails triagens::rest::ApplicationServer::_version
 ///
+/// @anchor CommandLineUpgrade
+/// @copydetails triagens::arango::ApplicationV8::_performUpgrade
+///
 /// @anchor CommandLineConfiguration
 /// @copydetails triagens::rest::ApplicationServer::_configFile
 ///
diff --git a/arangod/V8Server/ApplicationV8.h b/arangod/V8Server/ApplicationV8.h
index 481473e863..0d887768b4 100644
--- a/arangod/V8Server/ApplicationV8.h
+++ b/arangod/V8Server/ApplicationV8.h
@@ -370,6 +370,33 @@ namespace triagens {
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief perform a database upgrade
+///
+/// @CMDOPT{\--upgrade}
+///
+/// Specifying this option will make the server perform a database upgrade at
+/// start. A database upgrade will first compare the version number stored in 
+/// the file VERSION in the database directory with the current server version.
+///
+/// If the two version numbers match, the server will start normally.
+///
+/// If the version number found in the database directory is higher than the
+/// version number the server is running, the server expects this is an
+/// unintentional downgrade and will warn about this. It will however start
+/// normally. Using the server in these conditions is however not recommended 
+/// nor supported.
+///
+/// If the version number found in the database directory is lower than the
+/// version number the server is running, the server will check whether there
+/// are any upgrade tasks to perform. It will then execute all required upgrade
+/// tasks and print their statuses. If one of the upgrade tasks fails, the
+/// server will exit and refuse to start.
+/// Re-starting the server with the upgrade option will then again trigger the
+/// upgrade check and execution until the problem is fixed. If all tasks are
+/// finished, the server will start normally.
+///
+/// Whether or not this option is specified, the server will always perform a
+/// version check on startup. Running the server with a non-matching version
+/// number in the VERSION file will make the server refuse to start.
 ////////////////////////////////////////////////////////////////////////////////
 
         bool _performUpgrade;