Document CLI arguments (#6909)

* Documentation file added

* fixes motivated by the review of server arguments

* updated changelog

* added client app arguments

Co-authored-by: SerhiiGadzhilov <71632867+SerhiiGadzhilov@users.noreply.github.com>

ChangeLog

@@ -5,6 +5,7 @@ Bug fixes:
 - #6889 Systray Icon on Ubuntu Auto Start (take 2)
 
 Enhancements:
+- #6909 Document CLI Arguments
 - #6916 Main Window receives screen name change
 - #6910 Don't use the word “Version” for release names because it can lead to errors during update checking.
 - #6918 Removing positional union initialisation

src/lib/synergy/ArgParser.cpp

@@ -233,9 +233,6 @@ ArgParser::parseGenericArgs(int argc, const char* const* argv, int& i)
         // try to restart
         argsBase().m_restartable = true;
     }
-    else if (isArg(i, argc, argv, "-z", NULL)) {
-        argsBase().m_backend = true;
-    }
     else if (isArg(i, argc, argv, NULL, "--no-hooks")) {
         argsBase().m_noHooks = true;
     }

src/lib/synergy/ArgsBase.h

@@ -40,7 +40,6 @@ namespace lib {
             Type                 m_classType         = kBase;      /// @brief Stores what type of object this is
 
             bool                 m_daemon            = true;       /// @brief Should run as a daemon
-            bool                 m_backend           = false;      /// @brief //TODO Unsure what this is used for
             bool                 m_restartable       = true;       /// @brief Should the app restart automatically
             bool                 m_noHooks           = false;      /// @brief Should the app use hooks
             const char*          m_pname             = nullptr;    /// @brief The filename of the running process

src/lib/synergy/ClientAppArguments.md

@@ -0,0 +1,159 @@
+# ClientApp - List of Command Line Arguments
+
+As obtained by ```parseArgs()```
+
+## Common Arguments
+
+As obtained by ```updateCommonArgs()```
+
+*m_name*
+The name of the host as reported by the platform.
+
+*m_pname*
+Name of the process (synergys\[.exe])
+
+## Platform Arguments
+
+### Windows
+
+**--service** (deprecated, the program ends if specified)
+
+**--exit-pause**
+*m_pauseOnExit*
+
+Will wait for a key to be pressed before ending execution.
+
+**--stop-on-desk-switch**
+*m_stopOnDeskSwitch*
+
+Passed-in to the server screen at its creation. Shuts down the service when the cursor crosses over.
+
+### X-Windows
+
+**--display**
+*m_display*
+Identifies the X server to work on.
+
+**--no-xinitthreads**
+*m_disableXInitThreads*
+
+Passed-in to the server screen at creation. Avoids calling XInitThreads at the screen constructor.
+
+## Generic Arguments
+
+As collected by ```parseGenericArgs()```
+
+**-d** / **--debug**
+*m_logFilter* (string)
+
+If present, one value out of the following strings (each string contains all previous information levels): 
+    "FATAL",
+    "ERROR",
+    "WARNING",
+    "NOTE",
+    "INFO",
+    "DEBUG",
+    "DEBUG1",
+    "DEBUG2",
+    "DEBUG3",
+    "DEBUG4",
+    "DEBUG5".
+
+**-l** / **--log**
+*m_logFile*
+
+Uses FileLogOutputter to send log to that file. The file will be open/closed for each write operation. When reaching 1Mb, the file will be renamed with the same name +".1".
+
+**-f** / **--no-daemon**
+*m_daemon* false
+
+**--daemon**
+*m_daemon* true
+
+With m_daemon true, the main loop will be wrapped around a call to "daemonise" and a system logger created.
+
+**-n** / **--name**
+*m_name* (Screen name)
+
+Used to identify the server's screen.
+
+**-1** / **--no-restart**
+*m_restartable* false
+
+**--restart**
+*m_restartable* true
+
+With this flag true, ```initServer()``` and ```startServer()``` will setup a one-time timer on the queue for restarting in case of any failures.
+The time to wait is 10 seconds in the case of the particular issue "XSocketAddressInUse" but in all other cases will be zero.
+
+**--no-hooks**
+*m_noHooks* true
+
+Applies only to MS Windows, avoids using hooks.
+
+**--help**
+
+Shows help.
+
+**--version**
+
+Shows version, then exits.
+
+**--no-tray**
+m_disableTray true
+
+Avoids the creation of a task bar receiver.
+
+**--ipc**
+m_enableIpc true
+
+Implements the event queue over IPC.
+
+**--server**
+**--client**
+(accepted but ignored)
+
+**--enable-drag-drop**
+*m_enableDragDrop*
+
+Ignored for XWindows, or MS Windows below Vista. It enables steps required for drag and drop.
+
+**--enable-crypto**
+*m_enableCrypto* true
+
+Enables secure data sockets.
+
+**--profile-dir**
+*m_profileDirectory*
+
+If the profile directory is not passed-in, then it is inferred. For XWindows as "~/.synergy" or else "~/Library/Synergy".
+
+**--plugin-dir**
+*m_pluginDirectory*
+
+If unspecified, it is inferred. For XWindows "~/plugins" or else "~/Plugins".
+
+**--tls-cert**
+*m_tlsCertFile*
+
+If unspecified and used, then it is sought for as prifleDirectory/SSL/Synergy.pem
+
+## Uncategorised
+
+**\<server-address>**
+
+Exactly one non-option argument (server-address). The address to connect to a server.
+
+## Deprecated
+
+(accepted but effectively ignored)
+
+**--crypto-pass**
+
+**--res-w**
+
+**--res-h**
+
+**--prm-wc**
+
+**--prm-hc**

src/lib/synergy/ServerApp.cpp

@@ -538,7 +538,7 @@ ServerApp::startServer()
         assert(m_serverState == kInitialized);
     }
 
-    double retryTime;
+    double retryTime {};
     ClientListener* listener = NULL;
     try {
         listener   = openClientListener(args().m_config->getSynergyAddress());

src/lib/synergy/ServerAppArguments.md

@@ -0,0 +1,170 @@
+# ServerApp - List of Command Line Arguments
+
+As obtained by ```parseServerArgs()```
+
+## Common Arguments
+
+As obtained by ```updateCommonArgs()```
+
+*m_name*
+The name of the host as reported by the platform.
+
+*m_pname*
+Name of the process (synergys\[.exe])
+
+## Platform Arguments
+
+### Windows
+
+**--service** (deprecated, the program ends if specified)
+
+**--exit-pause**
+*m_pauseOnExit*
+
+Will wait for a key to be pressed before ending execution.
+
+**--stop-on-desk-switch**
+*m_stopOnDeskSwitch*
+
+Passed-in to the server screen at its creation. Shuts down the service when the cursor crosses over.
+
+### X-Windows
+
+**--display**
+*m_display*
+Identifies the X server to work on.
+
+**--no-xinitthreads**
+*m_disableXInitThreads*
+
+Passed-in to the server screen at creation. Avoids calling XInitThreads at the screen constructor.
+
+## Generic Arguments
+
+As collected by ```parseGenericArgs()```
+
+**-d** / **--debug**
+*m_logFilter* (string)
+
+If present, one value out of the following strings (each string contains all previous information levels): 
+    "FATAL",
+    "ERROR",
+    "WARNING",
+    "NOTE",
+    "INFO",
+    "DEBUG",
+    "DEBUG1",
+    "DEBUG2",
+    "DEBUG3",
+    "DEBUG4",
+    "DEBUG5".
+
+**-l** / **--log**
+*m_logFile*
+
+Uses FileLogOutputter to send log to that file. The file will be open/closed for each write operation. When reaching 1Mb, the file will be renamed with the same name +".1".
+
+**-f** / **--no-daemon**
+*m_daemon* false
+
+**--daemon**
+*m_daemon* true
+
+With m_daemon true, the main loop will be wrapped around a call to "daemonise" and a system logger created.
+
+**-n** / **--name**
+*m_name* (Screen name)
+
+Used to identify the server's screen.
+
+**-1** / **--no-restart**
+*m_restartable* false
+
+**--restart**
+*m_restartable* true
+
+With this flag true, ```initServer()``` and ```startServer()``` will setup a one-time timer on the queue for restarting in case of any failures.
+The time to wait is 10 seconds in the case of the particular issue "XSocketAddressInUse" but in all other cases will be zero.
+
+**--no-hooks**
+*m_noHooks* true
+
+Applies only to MS Windows, avoids using hooks.
+
+**--help**
+
+Shows help.
+
+**--version**
+
+Shows version, then exits.
+
+**--no-tray**
+m_disableTray true
+
+Avoids the creation of a task bar receiver.
+
+**--ipc**
+m_enableIpc true
+
+Implements the event queue over IPC.
+
+**--server**
+**--client**
+(accepted but ignored)
+
+**--enable-drag-drop**
+*m_enableDragDrop*
+
+Ignored for XWindows, or MS Windows below Vista. It enables steps required for drag and drop.
+
+**--enable-crypto**
+*m_enableCrypto* true
+
+Enables secure data sockets.
+
+**--profile-dir**
+*m_profileDirectory*
+
+If the profile directory is not passed-in, then it is inferred. For XWindows as "~/.synergy" or else "~/Library/Synergy".
+
+**--plugin-dir**
+*m_pluginDirectory*
+
+If unspecified, it is inferred. For XWindows "~/plugins" or else "~/Plugins".
+
+**--tls-cert**
+*m_tlsCertFile*
+
+If unspecified and used, then it is sought for as prifleDirectory/SSL/Synergy.pem
+
+## Uncategorised
+
+**-a** / **--address**
+*m_synergyAddress*
+
+Used as the listening address.
+
+**-c** / **--config**
+*m_configFile*
+
+Configuration file path.
+
+"" / **--serial-key**
+*m_serial*
+
+Serial key.
+
+## Deprecated
+
+(accepted but effectively ignored)
+
+**--crypto-pass**
+
+**--res-w**
+
+**--res-h**
+
+**--prm-wc**
+
+**--prm-hc**

src/lib/synergy/win32/AppUtilWindows.cpp

@@ -71,9 +71,6 @@ AppUtilWindows::daemonNTMainLoop(int argc, const char** argv)
 {
     app().initApp(argc, argv);
     debugServiceWait();
-
-    // NB: what the hell does this do?!
-    app().argsBase().m_backend = false;
     
     return ArchMiscWindows::runDaemon(mainLoopStatic);
 }

src/test/unittests/synergy/GenericArgsParsingTests.cpp

@@ -160,16 +160,13 @@ TEST_F(GenericArgsParsingTests, parseGenericArgs_restartCmd_restartTrue)
     EXPECT_EQ(1, i);
 }
 
-TEST_F(GenericArgsParsingTests, parseGenericArgs_backendCmd_backendTrue)
+TEST_F(GenericArgsParsingTests, parseGenericArgs_backendCmd_rejected)
 {
     int i = 1;
     const int argc = 2;
     const char* kBackendCmd[argc] = { "stub", "-z" };
 
-    m_argParser->parseGenericArgs(argc, kBackendCmd, i);
-
-    EXPECT_EQ(true, argsBase.m_backend);
-    EXPECT_EQ(1, i);
+    EXPECT_FALSE(m_argParser->parseGenericArgs(argc, kBackendCmd, i));
 }
 
 TEST_F(GenericArgsParsingTests, parseGenericArgs_noHookCmd_noHookTrue)