Bug 577982 - Improve Javadoc on Display.syncCall

Update documentation on the Display.syncCall method to be more
comprehensive.

Change-Id: Id0780bde60bc144457789e4187f81e983b914ca4
Reviewed-on: https://git.eclipse.org/r/c/platform/eclipse.platform.swt/+/189170
Tested-by: Platform Bot <platform-bot@eclipse.org>
Reviewed-by: Jörg Kubitz <jkubitz-eclipse@gmx.de>

3 files changed, 60 insertions, 21 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java
index f4bfd1dad7..6c8d5a1534 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java
@@ -5173,15 +5173,28 @@ public void syncExec (Runnable runnable) {
 }
 
 /**
- * Calls the callable in the user-interface thread and returns the supplied value.
- * The callable may throw checked Exception. Any Exception is rethrown in the calling thread.
+ * Calls the callable on the user-interface thread at the next reasonable
+ * opportunity, and returns the its result from this method. The thread which
+ * calls this method is suspended until the callable completes.
+ * <p>
+ * Note that at the time the callable is invoked, widgets that have the receiver
+ * as their display may have been disposed. Therefore, it is necessary to check
+ * for this case inside the callable before accessing the widget.
+ * </p>
+ * <p>
+ * Any exception that is thrown from the callable is re-thrown in the calling
+ * thread. Note: The exception retains its original stack trace from the
+ * throwing thread. The call to {@code syncCall} will not be present in the
+ * stack trace.
+ * </p>
  *
- * @param callable the code to run on the user-interface thread
+ * @param callable the code to call on the user-interface thread
  *
- * @exception SWTException <ul>
- *    <li>ERROR_FAILED_EXEC - if an exception occurred when executing the runnable</li>
- *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
- * </ul>
+ * @exception SWTException <code>ERROR_DEVICE_DISPOSED</code> - if the receiver
+ *                         has been disposed
+ * @exception E            An exception that is thrown by the callable on the
+ *                         user-interface thread, and re-thrown on the calling
+ *                         thread
  *
  * @see #syncExec(Runnable)
  * @see SwtCallable#call()
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
index adb0516ee1..4dfc47fb1f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
@@ -6013,15 +6013,28 @@ public void syncExec (Runnable runnable) {
 }
 
 /**
- * Calls the callable in the user-interface thread and returns the supplied value.
- * The callable may throw checked Exception. Any Exception is rethrown in the calling thread.
+ * Calls the callable on the user-interface thread at the next reasonable
+ * opportunity, and returns the its result from this method. The thread which
+ * calls this method is suspended until the callable completes.
+ * <p>
+ * Note that at the time the callable is invoked, widgets that have the receiver
+ * as their display may have been disposed. Therefore, it is necessary to check
+ * for this case inside the callable before accessing the widget.
+ * </p>
+ * <p>
+ * Any exception that is thrown from the callable is re-thrown in the calling
+ * thread. Note: The exception retains its original stack trace from the
+ * throwing thread. The call to {@code syncCall} will not be present in the
+ * stack trace.
+ * </p>
  *
- * @param callable the code to run on the user-interface thread
+ * @param callable the code to call on the user-interface thread
  *
- * @exception SWTException <ul>
- *    <li>ERROR_FAILED_EXEC - if an exception occurred when executing the runnable</li>
- *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
- * </ul>
+ * @exception SWTException <code>ERROR_DEVICE_DISPOSED</code> - if the receiver
+ *                         has been disposed
+ * @exception E            An exception that is thrown by the callable on the
+ *                         user-interface thread, and re-thrown on the calling
+ *                         thread
  *
  * @see #syncExec(Runnable)
  * @see SwtCallable#call()
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java
index 421dfbe95f..6ecdf8f2fc 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java
@@ -4781,15 +4781,28 @@ public void syncExec (Runnable runnable) {
 }
 
 /**
- * Calls the callable in the user-interface thread and returns the supplied value.
- * The callable may throw checked Exception. Any Exception is rethrown in the calling thread.
+ * Calls the callable on the user-interface thread at the next reasonable
+ * opportunity, and returns the its result from this method. The thread which
+ * calls this method is suspended until the callable completes.
+ * <p>
+ * Note that at the time the callable is invoked, widgets that have the receiver
+ * as their display may have been disposed. Therefore, it is necessary to check
+ * for this case inside the callable before accessing the widget.
+ * </p>
+ * <p>
+ * Any exception that is thrown from the callable is re-thrown in the calling
+ * thread. Note: The exception retains its original stack trace from the
+ * throwing thread. The call to {@code syncCall} will not be present in the
+ * stack trace.
+ * </p>
  *
- * @param callable the code to run on the user-interface thread
+ * @param callable the code to call on the user-interface thread
  *
- * @exception SWTException <ul>
- *    <li>ERROR_FAILED_EXEC - if an exception occurred when executing the runnable</li>
- *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
- * </ul>
+ * @exception SWTException <code>ERROR_DEVICE_DISPOSED</code> - if the receiver
+ *                         has been disposed
+ * @exception E            An exception that is thrown by the callable on the
+ *                         user-interface thread, and re-thrown on the calling
+ *                         thread
  *
  * @see #syncExec(Runnable)
  * @see SwtCallable#call()