added documentation for --upgrade option

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
 ///

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;