QProcess/Doc: clarify that started() may be emitted very early

On Windows, process creation is synchronous so we will always emit
either started() or errorOccurred() before QProcess::start() returns.
This condition doesn't currently happen on Unix systems, but we could do
that because we're now using vfork() on most platforms, so the child
process has either successfully execve()d or _exit()ed before
QProcessPrivate::startProcess continued.

Drive-by reorganization of the code to remove the one-line \note in the
middle of the docs.

Pick-to: 6.5 6.6 6.7
Fixes: QTBUG-120968
Task-number: QTCREATORBUG-30066
Change-Id: I4d0668e0fae5299551ff91480828a68e62fdacec
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@gmx.de>
Reviewed-by: Jarek Kobus <jaroslaw.kobus@qt.io>

1 files changed, 15 insertions, 12 deletions

diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp
index a8a32ef633..970bd584a2 100644
--- a/src/corelib/io/qprocess.cpp
+++ b/src/corelib/io/qprocess.cpp
@@ -1985,7 +1985,8 @@ QProcessEnvironment QProcess::processEnvironment() const
 
     Returns \c true if the process was started successfully; otherwise
     returns \c false (if the operation timed out or if an error
-    occurred).
+    occurred). If the process had already started successfully before this
+    function, it returns immediately.
 
     This function can operate without an event loop. It is
     useful when writing non-GUI applications and when performing
@@ -2164,18 +2165,22 @@ QByteArray QProcess::readAllStandardError()
 /*!
     Starts the given \a program in a new process, passing the command line
     arguments in \a arguments. See setProgram() for information about how
-    QProcess searches for the executable to be run.
+    QProcess searches for the executable to be run. The OpenMode is set to \a
+    mode. No further splitting of the arguments is performed.
 
     The QProcess object will immediately enter the Starting state. If the
     process starts successfully, QProcess will emit started(); otherwise,
-    errorOccurred() will be emitted.
-
-    \note Processes are started asynchronously, which means the started()
-    and errorOccurred() signals may be delayed. Call waitForStarted() to make
-    sure the process has started (or has failed to start) and those signals
-    have been emitted.
-
-    \note No further splitting of the arguments is performed.
+    errorOccurred() will be emitted. Do note that on platforms that are able to
+    start child processes synchronously (notably Windows), those signals will
+    be emitted before this function returns and this QProcess object will
+    transition to either QProcess::Running or QProcess::NotRunning state,
+    respectively. On others paltforms, the started() and errorOccurred()
+    signals will be delayed.
+
+    Call waitForStarted() to make sure the process has started (or has failed
+    to start) and those signals have been emitted. It is safe to call that
+    function even if the process starting state is already known, though the
+    signal will not be emitted again.
 
     \b{Windows:} The arguments are quoted and joined into a command line
     that is compatible with the \c CommandLineToArgvW() Windows function.
@@ -2184,8 +2189,6 @@ QByteArray QProcess::readAllStandardError()
     not follow the \c CommandLineToArgvW() rules is cmd.exe and, by
     consequence, all batch scripts.
 
-    The OpenMode is set to \a mode.
-
     If the QProcess object is already running a process, a warning may be
     printed at the console, and the existing process will continue running
     unaffected.