Javadoc bash pre-RC4

30 files changed, 348 insertions, 192 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java
index e437cacd39..94ba66405d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java
@@ -217,7 +217,13 @@ public void addFocusListener(FocusListener listener) {
  * be notified when gesture events are generated for the control,
  * by sending it one of the messages defined in the
  * <code>GestureListener</code> interface.
- *
+ * <p>
+ * NOTE: If <code>setTouchEnabled(true)</code> has previously been
+ * invoked on the receiver then <code>setTouchEnabled(false)</code>
+ * must be invoked on it to specify that gesture events should be
+ * sent instead of touch events.
+ * </p>
+ * 
  * @param listener the listener which should be notified
  *
  * @exception IllegalArgumentException <ul>
@@ -230,6 +236,7 @@ public void addFocusListener(FocusListener listener) {
  *
  * @see GestureListener
  * @see #removeGestureListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -477,8 +484,9 @@ public void addPaintListener(PaintListener listener) {
  * one of the messages defined in the <code>TouchListener</code>
  * interface.
  * <p>
- * NOTE: You must also call <code>setTouchEnabled</code> to notify the 
- * windowing toolkit that you want touch events to be generated.
+ * NOTE: You must also call <code>setTouchEnabled(true)</code> to 
+ * specify that touch events should be sent, which will cause gesture
+ * events to not be sent.
  * </p>
  * 
  * @param listener the listener which should be notified
@@ -493,6 +501,7 @@ public void addPaintListener(PaintListener listener) {
  *
  * @see TouchListener
  * @see #removeTouchListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -1519,19 +1528,23 @@ public String getToolTipText () {
 }
 
 /**
- * Returns <code>true</code> if this control is receiving OS-level touch events,
- * otherwise <code>false</code>
- * <p>
- * Note that this method will return false if the current platform does not support touch-based input.
- * If this method does return true, gesture events will not be sent to the control.
+ * Returns <code>true</code> if this control is set to send touch events, or
+ * <code>false</code> if it is set to send gesture events instead.  This method
+ * also returns <code>false</code> if a touch-based input device is not detected
+ * (this can be determined with <code>Display#getTouchEnabled()</code>).  Use
+ * {@link #setTouchEnabled(boolean)} to switch the events that a control sends
+ * between touch events and gesture events.
  *
- * @return <code>true</code> if the widget is currently receiving touch events; <code>false</code> otherwise.
+ * @return <code>true</code> if the control is set to send touch events, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see #setTouchEnabled
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public boolean getTouchEnabled() {
@@ -4038,15 +4051,19 @@ public void setToolTipText (String string) {
 }
 
 /**
- * Sets whether the receiver should accept touch events. By default, a Control does not accept touch
- * events. No error or exception is thrown if the underlying hardware does not support touch input.
+ * Sets whether this control should send touch events (by default controls do not).
+ * Setting this to <code>false</code> causes the receiver to send gesture events
+ * instead.  No exception is thrown if a touch-based input device is not
+ * detected (this can be determined with <code>Display#getTouchEnabled()</code>).
  * 
  * @param enabled the new touch-enabled state
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
- *    
+ *
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public void setTouchEnabled(boolean enabled) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java
index 005e4c3338..488b7e4217 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java
@@ -1380,10 +1380,10 @@ public Shell getActiveShell () {
 }
 
 /**
- * Returns the single instance of the application menu bar or null
- * when there is no application menu bar for the platform.
+ * Returns the single instance of the application menu bar, or
+ * <code>null</code> if there is no application menu bar for the platform.
  *
- * @return the application menu bar or <code>null</code>
+ * @return the application menu bar, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -2126,10 +2126,10 @@ public Image getSystemImage (int id) {
 }
 
 /**
- * Returns the single instance of the system-provided menu for the application.
- * On platforms where no menu is provided for the application this method returns null.
+ * Returns the single instance of the system-provided menu for the application, or
+ * <code>null</code> on platforms where no menu is provided for the application.
  *
- * @return the system menu or <code>null</code>
+ * @return the system menu, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -2195,8 +2195,10 @@ public Thread getThread () {
 }
 
 /**	 
- * Returns true if a touch-aware input device is attached to the system,
- * enabled, and ready for use.
+ * Returns a boolean indicating whether a touch-aware input device is
+ * attached to the system and is ready for use.
+ *
+ * @return <code>true</code> if a touch-aware input device is detected, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
index 2cfe121971..c2ada247fe 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
@@ -310,6 +310,8 @@ public boolean getEnabled () {
 /**
  * Gets the identifier associated with the receiver.
  *
+ * @return the receiver's identifier
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
index 09bf921bdf..b8a333d35f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
@@ -890,7 +890,8 @@ Shell getModalShell () {
 /**
  * Gets the receiver's modified state.
  *
- * </ul>
+ * @return <code>true</code> if the receiver is marked as modified, or <code>false</code> otherwise
+ * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -921,9 +922,9 @@ float [] getParentBackground () {
 
 /** 
  * Returns the region that defines the shape of the shell,
- * or null if the shell has the default shape.
+ * or <code>null</code> if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell (or null)
+ * @return the region that defines the shape of the shell, or <code>null</code>
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -992,13 +993,13 @@ float getThemeAlpha () {
 }
 
 /**
- * Returns the instance of the ToolBar object representing the tool bar that can appear on the
- * trim of the shell. This will return <code>null</code> if the platform does not support tool bars that
- * not part of the content area of the shell, or if the style of the shell does not support a 
- * tool bar. 
+ * Returns a ToolBar object representing the tool bar that can be shown in the receiver's
+ * trim. This will return <code>null</code> if the platform does not support tool bars that
+ * are not part of the content area of the shell, or if the Shell's style does not support 
+ * having a tool bar. 
  * <p>
  * 
- * @return a ToolBar object representing the window's tool bar or null.
+ * @return a ToolBar object representing the Shell's tool bar, or <ocde>null</code>.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java
index 9943e99349..e899ae2c87 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java
@@ -1211,7 +1211,7 @@ public String getText (int start, int end) {
  * Returns the widget's text as a character array.
  * <p>
  * The text for a text widget is the characters in the widget, or
- * a zero length array if this has never been set.
+ * a zero-length array if this has never been set.
  * </p>
  *
  * @return a character array that contains the widget's text
@@ -1220,7 +1220,9 @@ public String getText (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #setTextChars(char[])
+ *
  * @since 3.7
  */
 public char [] getTextChars () {
@@ -2347,9 +2349,9 @@ public void setText (String string) {
 }
 
 /**
- * Sets the contents of the receiver to the characters in the array. If the receiver has style
- * SINGLE and the argument contains multiple lines of text, the result of this
- * operation is undefined and may vary from platform to platform.
+ * Sets the contents of the receiver to the characters in the array. If the receiver
+ * has style <code>SWT.SINGLE</code> and the argument contains multiple lines of text
+ * then the result of this operation is undefined and may vary between platforms.
  *
  * @param text a character array that contains the new text
  *
@@ -2360,7 +2362,9 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #getTextChars()
+ *
  * @since 3.7
  */
 public void setTextChars (char [] text) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
index 63121a5da1..ca0e428614 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
@@ -390,7 +390,13 @@ public void addFocusListener(FocusListener listener) {
  * be notified when gesture events are generated for the control,
  * by sending it one of the messages defined in the
  * <code>GestureListener</code> interface.
- *
+ * <p>
+ * NOTE: If <code>setTouchEnabled(true)</code> has previously been
+ * invoked on the receiver then <code>setTouchEnabled(false)</code>
+ * must be invoked on it to specify that gesture events should be
+ * sent instead of touch events.
+ * </p>
+ * 
  * @param listener the listener which should be notified
  *
  * @exception IllegalArgumentException <ul>
@@ -403,6 +409,7 @@ public void addFocusListener(FocusListener listener) {
  *
  * @see GestureListener
  * @see #removeGestureListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -662,8 +669,9 @@ void addTraits(NSMutableDictionary dict, Font font) {
  * one of the messages defined in the <code>TouchListener</code>
  * interface.
  * <p>
- * NOTE: You must also call <code>setTouchEnabled</code> to notify the 
- * windowing toolkit that you want touch events to be generated.
+ * NOTE: You must also call <code>setTouchEnabled(true)</code> to 
+ * specify that touch events should be sent, which will cause gesture
+ * events to not be sent.
  * </p>
  * 
  * @param listener the listener which should be notified
@@ -678,6 +686,7 @@ void addTraits(NSMutableDictionary dict, Font font) {
  *
  * @see TouchListener
  * @see #removeTouchListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -1935,19 +1944,23 @@ public String getToolTipText () {
 }
 
 /**
- * Returns <code>true</code> if this control is receiving OS-level touch events,
- * otherwise <code>false</code>
- * <p>
- * Note that this method will return false if the current platform does not support touch-based input.
- * If this method does return true, gesture events will not be sent to the control.
+ * Returns <code>true</code> if this control is set to send touch events, or
+ * <code>false</code> if it is set to send gesture events instead.  This method
+ * also returns <code>false</code> if a touch-based input device is not detected
+ * (this can be determined with <code>Display#getTouchEnabled()</code>).  Use
+ * {@link #setTouchEnabled(boolean)} to switch the events that a control sends
+ * between touch events and gesture events.
  *
- * @return <code>true</code> if the widget is currently receiving touch events; <code>false</code> otherwise.
+ * @return <code>true</code> if the control is set to send touch events, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see #setTouchEnabled
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public boolean getTouchEnabled() {
@@ -4092,15 +4105,19 @@ public void setToolTipText (String string) {
 }
 
 /**
- * Sets whether the receiver should accept touch events. By default, a Control does not accept touch
- * events. No error or exception is thrown if the underlying hardware does not support touch input.
+ * Sets whether this control should send touch events (by default controls do not).
+ * Setting this to <code>false</code> causes the receiver to send gesture events
+ * instead.  No exception is thrown if a touch-based input device is not
+ * detected (this can be determined with <code>Display#getTouchEnabled()</code>).
  * 
  * @param enabled the new touch-enabled state
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
- *    
+ *
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public void setTouchEnabled(boolean enabled) {
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 f3c7e53a82..a374930374 100755
--- 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
@@ -1950,10 +1950,10 @@ public Image getSystemImage (int id) {
 }
 
 /**
- * Returns the single instance of the application menu bar or null
- * when there is no application menu bar for the platform.
+ * Returns the single instance of the application menu bar, or
+ * <code>null</code> if there is no application menu bar for the platform.
  *
- * @return the application menu bar or <code>null</code>
+ * @return the application menu bar, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -1974,10 +1974,10 @@ public Menu getMenuBar () {
 }
 
 /**
- * Returns the single instance of the system-provided menu for the application.
- * On platforms where no menu is provided for the application this method returns null.
+ * Returns the single instance of the system-provided menu for the application, or
+ * <code>null</code> on platforms where no menu is provided for the application.
  *
- * @return the system menu or <code>null</code>
+ * @return the system menu, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -2057,8 +2057,10 @@ public Thread getThread () {
 }
 
 /**	 
- * Returns true if a touch-aware input device is attached to the system,
- * enabled, and ready for use.
+ * Returns a boolean indicating whether a touch-aware input device is
+ * attached to the system and is ready for use.
+ *
+ * @return <code>true</code> if a touch-aware input device is detected, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java
index 8dda65660e..d12c0bf3b9 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java
@@ -290,6 +290,8 @@ public boolean getEnabled () {
 /**
  * Gets the identifier associated with the receiver.
  *
+ * @return the receiver's identifier
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Shell.java
index 0d4562a9f9..3c03062ddb 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Shell.java
@@ -1041,7 +1041,8 @@ Shell getModalShell () {
 /**
  * Gets the receiver's modified state.
  *
- * </ul>
+ * @return <code>true</code> if the receiver is marked as modified, or <code>false</code> otherwise
+ * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -1085,9 +1086,9 @@ public Point getMinimumSize () {
 
 /** 
  * Returns the region that defines the shape of the shell,
- * or null if the shell has the default shape.
+ * or <code>null</code> if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell (or null)
+ * @return the region that defines the shape of the shell, or <code>null</code>
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1159,13 +1160,13 @@ float getThemeAlpha () {
 }
 
 /**
- * Returns the instance of the ToolBar object representing the tool bar that can appear on the
- * trim of the shell. This will return <code>null</code> if the platform does not support tool bars that
- * not part of the content area of the shell, or if the style of the shell does not support a 
- * tool bar. 
+ * Returns a ToolBar object representing the tool bar that can be shown in the receiver's
+ * trim. This will return <code>null</code> if the platform does not support tool bars that
+ * are not part of the content area of the shell, or if the Shell's style does not support 
+ * having a tool bar. 
  * <p>
  * 
- * @return a ToolBar object representing the window's tool bar or null.
+ * @return a ToolBar object representing the Shell's tool bar, or <ocde>null</code>.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java
index 0bfe238001..3ea2fb46d2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java
@@ -1160,7 +1160,7 @@ public String getText (int start, int end) {
  * Returns the widget's text as a character array.
  * <p>
  * The text for a text widget is the characters in the widget, or
- * a zero length array if this has never been set.
+ * a zero-length array if this has never been set.
  * </p>
  *
  * @return a character array that contains the widget's text
@@ -1169,7 +1169,9 @@ public String getText (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #setTextChars(char[])
+ *
  * @since 3.7
  */
 public char[] getTextChars () {
@@ -1994,9 +1996,9 @@ public void setText (String string) {
 }
 
 /**
- * Sets the contents of the receiver to the characters in the array. If the receiver has style
- * SINGLE and the argument contains multiple lines of text, the result of this
- * operation is undefined and may vary from platform to platform.
+ * Sets the contents of the receiver to the characters in the array. If the receiver
+ * has style <code>SWT.SINGLE</code> and the argument contains multiple lines of text
+ * then the result of this operation is undefined and may vary between platforms.
  *
  * @param text a character array that contains the new text
  *
@@ -2007,7 +2009,9 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #getTextChars()
+ *
  * @since 3.7
  */
 public void setTextChars (char[] text) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
index 2c50b522e4..c3a9f8ab64 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
@@ -1416,7 +1416,13 @@ public void addFocusListener(FocusListener listener) {
  * be notified when gesture events are generated for the control,
  * by sending it one of the messages defined in the
  * <code>GestureListener</code> interface.
- *
+ * <p>
+ * NOTE: If <code>setTouchEnabled(true)</code> has previously been
+ * invoked on the receiver then <code>setTouchEnabled(false)</code>
+ * must be invoked on it to specify that gesture events should be
+ * sent instead of touch events.
+ * </p>
+ * 
  * @param listener the listener which should be notified
  *
  * @exception IllegalArgumentException <ul>
@@ -1429,6 +1435,7 @@ public void addFocusListener(FocusListener listener) {
  *
  * @see GestureListener
  * @see #removeGestureListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -1676,8 +1683,9 @@ void addRelation (Control control) {
  * one of the messages defined in the <code>TouchListener</code>
  * interface.
  * <p>
- * NOTE: You must also call <code>setTouchEnabled</code> to notify the 
- * windowing toolkit that you want touch events to be generated.
+ * NOTE: You must also call <code>setTouchEnabled(true)</code> to 
+ * specify that touch events should be sent, which will cause gesture
+ * events to not be sent.
  * </p>
  * 
  * @param listener the listener which should be notified
@@ -1692,6 +1700,7 @@ void addRelation (Control control) {
  *
  * @see TouchListener
  * @see #removeTouchListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -2700,19 +2709,23 @@ public String getToolTipText () {
 }
 
 /**
- * Returns <code>true</code> if this control is receiving OS-level touch events,
- * otherwise <code>false</code>
- * <p>
- * Note that this method will return false if the current platform does not support touch-based input.
- * If this method does return true, gesture events will not be sent to the control.
+ * Returns <code>true</code> if this control is set to send touch events, or
+ * <code>false</code> if it is set to send gesture events instead.  This method
+ * also returns <code>false</code> if a touch-based input device is not detected
+ * (this can be determined with <code>Display#getTouchEnabled()</code>).  Use
+ * {@link #setTouchEnabled(boolean)} to switch the events that a control sends
+ * between touch events and gesture events.
  *
- * @return <code>true</code> if the widget is currently receiving touch events; <code>false</code> otherwise.
+ * @return <code>true</code> if the control is set to send touch events, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see #setTouchEnabled
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public boolean getTouchEnabled() {
@@ -4289,15 +4302,19 @@ void setToolTipText (Shell shell, String newString) {
 }
 
 /**
- * Sets whether the receiver should accept touch events. By default, a Control does not accept touch
- * events. No error or exception is thrown if the underlying hardware does not support touch input.
+ * Sets whether this control should send touch events (by default controls do not).
+ * Setting this to <code>false</code> causes the receiver to send gesture events
+ * instead.  No exception is thrown if a touch-based input device is not
+ * detected (this can be determined with <code>Display#getTouchEnabled()</code>).
  * 
  * @param enabled the new touch-enabled state
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
- *    
+ *
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public void setTouchEnabled(boolean enabled) {
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 7300ddefd4..74d016e63f 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
@@ -1690,10 +1690,10 @@ static boolean isValidClass (Class clazz) {
 }
 
 /**
- * Returns the single instance of the application menu bar or null
- * when there is no application menu bar for the platform.
+ * Returns the single instance of the application menu bar, or
+ * <code>null</code> if there is no application menu bar for the platform.
  *
- * @return the application menu bar or <code>null</code>
+ * @return the application menu bar, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -2205,10 +2205,10 @@ public Image getSystemImage (int id) {
 }
 
 /**
- * Returns the single instance of the system-provided menu for the application.
- * On platforms where no menu is provided for the application this method returns null.
+ * Returns the single instance of the system-provided menu for the application, or
+ * <code>null</code> on platforms where no menu is provided for the application.
  *
- * @return the system menu or <code>null</code>
+ * @return the system menu, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -2379,8 +2379,10 @@ public Thread getThread () {
 }
 
 /**	 
- * Returns true if a touch-aware input device is attached to the system,
- * enabled, and ready for use.
+ * Returns a boolean indicating whether a touch-aware input device is
+ * attached to the system and is ready for use.
+ *
+ * @return <code>true</code> if a touch-aware input device is detected, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
index f983552290..8ce0cde2ba 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
@@ -351,6 +351,8 @@ public boolean getEnabled () {
 /**
  * Gets the identifier associated with the receiver.
  *
+ * @return the receiver's identifier
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
index 116bfeaf7f..6c18baf905 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
@@ -772,13 +772,13 @@ Composite findDeferredControl () {
 }
 
 /**
- * Returns the instance of the ToolBar object representing the tool bar that can appear on the
- * trim of the shell. This will return <code>null</code> if the platform does not support tool bars that
- * not part of the content area of the shell, or if the style of the shell does not support a 
- * tool bar. 
+ * Returns a ToolBar object representing the tool bar that can be shown in the receiver's
+ * trim. This will return <code>null</code> if the platform does not support tool bars that
+ * are not part of the content area of the shell, or if the Shell's style does not support 
+ * having a tool bar. 
  * <p>
  * 
- * @return a ToolBar object representing the window's tool bar or null.
+ * @return a ToolBar object representing the Shell's tool bar, or <ocde>null</code>.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1037,7 +1037,8 @@ Shell getModalShell () {
 /**
  * Gets the receiver's modified state.
  *
- * </ul>
+ * @return <code>true</code> if the receiver is marked as modified, or <code>false</code> otherwise
+ * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -1068,9 +1069,9 @@ public boolean getVisible () {
 
 /** 
  * Returns the region that defines the shape of the shell,
- * or null if the shell has the default shape.
+ * or <code>null</code> if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell (or null)
+ * @return the region that defines the shape of the shell, or <code>null</code>
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java
index 17d6f36fc2..25c926a5ef 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java
@@ -1046,7 +1046,7 @@ public String getText (int start, int end) {
  * Returns the widget's text as a character array.
  * <p>
  * The text for a text widget is the characters in the widget, or
- * a zero length array if this has never been set.
+ * a zero-length array if this has never been set.
  * </p>
  *
  * @return a character array that contains the widget's text
@@ -1055,7 +1055,9 @@ public String getText (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #setTextChars(char[])
+ *
  * @since 3.7
  */
 public char [] getTextChars () {
@@ -2110,9 +2112,9 @@ public void setText (String string) {
 }
 
 /**
- * Sets the contents of the receiver to the characters in the array. If the receiver has style
- * SINGLE and the argument contains multiple lines of text, the result of this
- * operation is undefined and may vary from platform to platform.
+ * Sets the contents of the receiver to the characters in the array. If the receiver
+ * has style <code>SWT.SINGLE</code> and the argument contains multiple lines of text
+ * then the result of this operation is undefined and may vary between platforms.
  *
  * @param text a character array that contains the new text
  *
@@ -2123,7 +2125,9 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #getTextChars()
+ *
  * @since 3.7
  */
 public void setTextChars (char [] text) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java
index 2ba0a50bf4..13f9e37602 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java
@@ -175,7 +175,13 @@ public void addFocusListener(FocusListener listener) {
  * be notified when gesture events are generated for the control,
  * by sending it one of the messages defined in the
  * <code>GestureListener</code> interface.
- *
+ * <p>
+ * NOTE: If <code>setTouchEnabled(true)</code> has previously been
+ * invoked on the receiver then <code>setTouchEnabled(false)</code>
+ * must be invoked on it to specify that gesture events should be
+ * sent instead of touch events.
+ * </p>
+ * 
  * @param listener the listener which should be notified
  *
  * @exception IllegalArgumentException <ul>
@@ -188,6 +194,7 @@ public void addFocusListener(FocusListener listener) {
  *
  * @see GestureListener
  * @see #removeGestureListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -423,8 +430,9 @@ public void addPaintListener(PaintListener listener) {
  * one of the messages defined in the <code>TouchListener</code>
  * interface.
  * <p>
- * NOTE: You must also call <code>setTouchEnabled</code> to notify the 
- * windowing toolkit that you want touch events to be generated.
+ * NOTE: You must also call <code>setTouchEnabled(true)</code> to 
+ * specify that touch events should be sent, which will cause gesture
+ * events to not be sent.
  * </p>
  * 
  * @param listener the listener which should be notified
@@ -439,6 +447,7 @@ public void addPaintListener(PaintListener listener) {
  *
  * @see TouchListener
  * @see #removeTouchListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -1399,19 +1408,23 @@ public String getToolTipText () {
 	return toolTipText;
 }
 /**
- * Returns <code>true</code> if this control is receiving OS-level touch events,
- * otherwise <code>false</code>
- * <p>
- * Note that this method will return false if the current platform does not support touch-based input.
- * If this method does return true, gesture events will not be sent to the control.
+ * Returns <code>true</code> if this control is set to send touch events, or
+ * <code>false</code> if it is set to send gesture events instead.  This method
+ * also returns <code>false</code> if a touch-based input device is not detected
+ * (this can be determined with <code>Display#getTouchEnabled()</code>).  Use
+ * {@link #setTouchEnabled(boolean)} to switch the events that a control sends
+ * between touch events and gesture events.
  *
- * @return <code>true</code> if the widget is currently receiving touch events; <code>false</code> otherwise.
+ * @return <code>true</code> if the control is set to send touch events, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see #setTouchEnabled
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public boolean getTouchEnabled() {
@@ -3168,15 +3181,19 @@ public void setToolTipText (String string) {
 	display.setToolTipText (handle, toolTipText = string);
 }
 /**
- * Sets whether the receiver should accept touch events. By default, a Control does not accept touch
- * events. No error or exception is thrown if the underlying hardware does not support touch input.
+ * Sets whether this control should send touch events (by default controls do not).
+ * Setting this to <code>false</code> causes the receiver to send gesture events
+ * instead.  No exception is thrown if a touch-based input device is not
+ * detected (this can be determined with <code>Display#getTouchEnabled()</code>).
  * 
  * @param enabled the new touch-enabled state
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
- *    
+ *
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public void setTouchEnabled(boolean enabled) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java
index 4848ed3e1c..18b4425317 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java
@@ -1264,10 +1264,10 @@ public Shell getActiveShell () {
 }
 
 /**
- * Returns the single instance of the application menu bar or null
- * when there is no application menu bar for the platform.
+ * Returns the single instance of the application menu bar, or
+ * <code>null</code> if there is no application menu bar for the platform.
  *
- * @return the application menu bar or <code>null</code>
+ * @return the application menu bar, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -1975,10 +1975,10 @@ public Image getSystemImage (int style) {
 	return Image.motif_new (this, SWT.ICON, imagePixmap, maskPixmap);
 }
 /**
- * Returns the single instance of the system-provided menu for the application.
- * On platforms where no menu is provided for the application this method returns null.
+ * Returns the single instance of the system-provided menu for the application, or
+ * <code>null</code> on platforms where no menu is provided for the application.
  *
- * @return the system menu or <code>null</code>
+ * @return the system menu, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -2039,8 +2039,10 @@ public Thread getThread () {
 	}
 }
 /**	 
- * Returns true if a touch-aware input device is attached to the system,
- * enabled, and ready for use.
+ * Returns a boolean indicating whether a touch-aware input device is
+ * attached to the system and is ready for use.
+ *
+ * @return <code>true</code> if a touch-aware input device is detected, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
index d62bb44642..541c64531c 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
@@ -377,6 +377,8 @@ public boolean getEnabled () {
 /**
  * Gets the identifier associated with the receiver.
  *
+ * @return the receiver's identifier
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
index 641966a298..2aacdfcca7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
@@ -1105,7 +1105,8 @@ public Point getMinimumSize () {
 /**
  * Gets the receiver's modified state.
  *
- * </ul>
+ * @return <code>true</code> if the receiver is marked as modified, or <code>false</code> otherwise
+ * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -1119,9 +1120,9 @@ public boolean getModified () {
 }
 /** 
  * Returns the region that defines the shape of the shell,
- * or null if the shell has the default shape.
+ * or <code>null</code> if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell (or null)
+ * @return the region that defines the shape of the shell, or <code>null</code>
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1209,13 +1210,13 @@ public Point getSize () {
 }
 
 /**
- * Returns the instance of the ToolBar object representing the tool bar that can appear on the
- * trim of the shell. This will return <code>null</code> if the platform does not support tool bars that
- * not part of the content area of the shell, or if the style of the shell does not support a 
- * tool bar. 
+ * Returns a ToolBar object representing the tool bar that can be shown in the receiver's
+ * trim. This will return <code>null</code> if the platform does not support tool bars that
+ * are not part of the content area of the shell, or if the Shell's style does not support 
+ * having a tool bar. 
  * <p>
  * 
- * @return a ToolBar object representing the window's tool bar or null.
+ * @return a ToolBar object representing the Shell's tool bar, or <ocde>null</code>.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java
index 3434eda106..7e41ae3fa6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java
@@ -939,7 +939,7 @@ public String getText (int start, int end) {
  * Returns the widget's text as a character array.
  * <p>
  * The text for a text widget is the characters in the widget, or
- * a zero length array if this has never been set.
+ * a zero-length array if this has never been set.
  * </p>
  *
  * @return a character array that contains the widget's text
@@ -948,7 +948,9 @@ public String getText (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #setTextChars(char[])
+ *
  * @since 3.7
  */
 public char [] getTextChars () {
@@ -1557,9 +1559,9 @@ public void setText (String string) {
 	display.setWarnings(warnings);
 }
 /**
- * Sets the contents of the receiver to the characters in the array. If the receiver has style
- * SINGLE and the argument contains multiple lines of text, the result of this
- * operation is undefined and may vary from platform to platform.
+ * Sets the contents of the receiver to the characters in the array. If the receiver
+ * has style <code>SWT.SINGLE</code> and the argument contains multiple lines of text
+ * then the result of this operation is undefined and may vary between platforms.
  *
  * @param text a character array that contains the new text
  *
@@ -1570,7 +1572,9 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #getTextChars()
+ *
  * @since 3.7
  */
 public void setTextChars (char [] text) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
index 07c4b26b28..961b385186 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
@@ -180,7 +180,13 @@ public void addFocusListener (FocusListener listener) {
  * be notified when gesture events are generated for the control,
  * by sending it one of the messages defined in the
  * <code>GestureListener</code> interface.
- *
+ * <p>
+ * NOTE: If <code>setTouchEnabled(true)</code> has previously been
+ * invoked on the receiver then <code>setTouchEnabled(false)</code>
+ * must be invoked on it to specify that gesture events should be
+ * sent instead of touch events.
+ * </p>
+ * 
  * @param listener the listener which should be notified
  *
  * @exception IllegalArgumentException <ul>
@@ -193,6 +199,7 @@ public void addFocusListener (FocusListener listener) {
  *
  * @see GestureListener
  * @see #removeGestureListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -437,8 +444,9 @@ public void addPaintListener (PaintListener listener) {
  * one of the messages defined in the <code>TouchListener</code>
  * interface.
  * <p>
- * NOTE: You must also call <code>setTouchEnabled</code> to notify the 
- * windowing toolkit that you want touch events to be generated.
+ * NOTE: You must also call <code>setTouchEnabled(true)</code> to 
+ * specify that touch events should be sent, which will cause gesture
+ * events to not be sent.
  * </p>
  * 
  * @param listener the listener which should be notified
@@ -453,6 +461,7 @@ public void addPaintListener (PaintListener listener) {
  *
  * @see TouchListener
  * @see #removeTouchListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -1239,19 +1248,23 @@ public String getToolTipText () {
 }
 
 /**
- * Returns <code>true</code> if this control is receiving OS-level touch events,
- * otherwise <code>false</code>
- * <p>
- * Note that this method will return false if the current platform does not support touch-based input.
- * If this method does return true, gesture events will not be sent to the control.
+ * Returns <code>true</code> if this control is set to send touch events, or
+ * <code>false</code> if it is set to send gesture events instead.  This method
+ * also returns <code>false</code> if a touch-based input device is not detected
+ * (this can be determined with <code>Display#getTouchEnabled()</code>).  Use
+ * {@link #setTouchEnabled(boolean)} to switch the events that a control sends
+ * between touch events and gesture events.
  *
- * @return <code>true</code> if the widget is currently receiving touch events; <code>false</code> otherwise.
+ * @return <code>true</code> if the control is set to send touch events, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see #setTouchEnabled
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public boolean getTouchEnabled() {
@@ -3076,15 +3089,19 @@ public void setSize (int width, int height) {
 }
 
 /**
- * Sets whether the receiver should accept touch events. By default, a Control does not accept touch
- * events. No error or exception is thrown if the underlying hardware does not support touch input.
+ * Sets whether this control should send touch events (by default controls do not).
+ * Setting this to <code>false</code> causes the receiver to send gesture events
+ * instead.  No exception is thrown if a touch-based input device is not
+ * detected (this can be determined with <code>Display#getTouchEnabled()</code>).
  * 
  * @param enabled the new touch-enabled state
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
- *    
+ *
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public void setTouchEnabled(boolean enabled) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
index 5ad5bf5cca..2e14eac5ac 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
@@ -908,10 +908,10 @@ public static Display getDefault () {
 }
 
 /**
- * Returns the single instance of the application menu bar or null
- * when there is no application menu bar for the platform.
+ * Returns the single instance of the application menu bar, or
+ * <code>null</code> if there is no application menu bar for the platform.
  *
- * @return the application menu bar or <code>null</code>
+ * @return the application menu bar, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -1368,10 +1368,10 @@ public Image getSystemImage (int id) {
 }
 
 /**
- * Returns the single instance of the system-provided menu for the application.
- * On platforms where no menu is provided for the application this method returns null.
+ * Returns the single instance of the system-provided menu for the application, or
+ * <code>null</code> on platforms where no menu is provided for the application.
  *
- * @return the system menu or <code>null</code>
+ * @return the system menu, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -1475,8 +1475,10 @@ public Thread getThread () {
 }
 
 /**	 
- * Returns true if a touch-aware input device is attached to the system,
- * enabled, and ready for use.
+ * Returns a boolean indicating whether a touch-aware input device is
+ * attached to the system and is ready for use.
+ *
+ * @return <code>true</code> if a touch-aware input device is detected, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
index 8714aa782b..626a7763c3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
@@ -321,6 +321,8 @@ public boolean getEnabled () {
 /**
  * Gets the identifier associated with the receiver.
  *
+ * @return the receiver's identifier
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
index 4a2bab316c..860948f986 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
@@ -701,7 +701,8 @@ public Point getMinimumSize () {
 /**
  * Gets the receiver's modified state.
  *
- * </ul>
+ * @return <code>true</code> if the receiver is marked as modified, or <code>false</code> otherwise
+ * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -716,9 +717,9 @@ public boolean getModified () {
 
 /** 
  * Returns the region that defines the shape of the shell,
- * or null if the shell has the default shape.
+ * or <code>null</code> if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell (or null)
+ * @return the region that defines the shape of the shell, or <code>null</code>
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -793,13 +794,13 @@ public Point getSize () {
 }
 
 /**
- * Returns the instance of the ToolBar object representing the tool bar that can appear on the
- * trim of the shell. This will return <code>null</code> if the platform does not support tool bars that
- * not part of the content area of the shell, or if the style of the shell does not support a 
- * tool bar. 
+ * Returns a ToolBar object representing the tool bar that can be shown in the receiver's
+ * trim. This will return <code>null</code> if the platform does not support tool bars that
+ * are not part of the content area of the shell, or if the Shell's style does not support 
+ * having a tool bar. 
  * <p>
  * 
- * @return a ToolBar object representing the window's tool bar or null.
+ * @return a ToolBar object representing the Shell's tool bar, or <ocde>null</code>.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
index 1d4dd289f7..4cf18d3017 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
@@ -833,7 +833,7 @@ public String getText (int start, int end) {
  * Returns the widget's text as a character array.
  * <p>
  * The text for a text widget is the characters in the widget, or
- * a zero length array if this has never been set.
+ * a zero-length array if this has never been set.
  * </p>
  *
  * @return a character array that contains the widget's text
@@ -842,7 +842,9 @@ public String getText (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #setTextChars(char[])
+ *
  * @since 3.7
  */
 public char [] getTextChars () {
@@ -1539,9 +1541,9 @@ public void setText (String string) {
 	OS.free (ptr);
 }
 /**
- * Sets the contents of the receiver to the characters in the array. If the receiver has style
- * SINGLE and the argument contains multiple lines of text, the result of this
- * operation is undefined and may vary from platform to platform.
+ * Sets the contents of the receiver to the characters in the array. If the receiver
+ * has style <code>SWT.SINGLE</code> and the argument contains multiple lines of text
+ * then the result of this operation is undefined and may vary between platforms.
  *
  * @param text a character array that contains the new text
  *
@@ -1552,7 +1554,9 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #getTextChars()
+ *
  * @since 3.7
  */
 public void setTextChars (char [] text) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java
index d1515d7e6d..28500a5141 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java
@@ -187,7 +187,13 @@ public void addFocusListener (FocusListener listener) {
  * be notified when gesture events are generated for the control,
  * by sending it one of the messages defined in the
  * <code>GestureListener</code> interface.
- *
+ * <p>
+ * NOTE: If <code>setTouchEnabled(true)</code> has previously been
+ * invoked on the receiver then <code>setTouchEnabled(false)</code>
+ * must be invoked on it to specify that gesture events should be
+ * sent instead of touch events.
+ * </p>
+ * 
  * @param listener the listener which should be notified
  *
  * @exception IllegalArgumentException <ul>
@@ -200,6 +206,7 @@ public void addFocusListener (FocusListener listener) {
  *
  * @see GestureListener
  * @see #removeGestureListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -444,8 +451,9 @@ public void addPaintListener (PaintListener listener) {
  * one of the messages defined in the <code>TouchListener</code>
  * interface.
  * <p>
- * NOTE: You must also call <code>setTouchEnabled</code> to notify the 
- * windowing toolkit that you want touch events to be generated.
+ * NOTE: You must also call <code>setTouchEnabled(true)</code> to 
+ * specify that touch events should be sent, which will cause gesture
+ * events to not be sent.
  * </p>
  * 
  * @param listener the listener which should be notified
@@ -460,6 +468,7 @@ public void addPaintListener (PaintListener listener) {
  *
  * @see TouchListener
  * @see #removeTouchListener
+ * @see #setTouchEnabled
  * 
  * @since 3.7
  */
@@ -1327,19 +1336,23 @@ public String getToolTipText () {
 }
 
 /**
- * Returns <code>true</code> if this control is receiving OS-level touch events,
- * otherwise <code>false</code>
- * <p>
- * Note that this method will return false if the current platform does not support touch-based input.
- * If this method does return true, gesture events will not be sent to the control.
+ * Returns <code>true</code> if this control is set to send touch events, or
+ * <code>false</code> if it is set to send gesture events instead.  This method
+ * also returns <code>false</code> if a touch-based input device is not detected
+ * (this can be determined with <code>Display#getTouchEnabled()</code>).  Use
+ * {@link #setTouchEnabled(boolean)} to switch the events that a control sends
+ * between touch events and gesture events.
  *
- * @return <code>true</code> if the widget is currently receiving touch events; <code>false</code> otherwise.
+ * @return <code>true</code> if the control is set to send touch events, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see #setTouchEnabled
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public boolean getTouchEnabled() {
@@ -3302,15 +3315,19 @@ public void setTransform (Transform t) {
 }
 
 /**
- * Sets whether the receiver should accept touch events. By default, a Control does not accept touch
- * events. No error or exception is thrown if the underlying hardware does not support touch input.
+ * Sets whether this control should send touch events (by default controls do not).
+ * Setting this to <code>false</code> causes the receiver to send gesture events
+ * instead.  No exception is thrown if a touch-based input device is not
+ * detected (this can be determined with <code>Display#getTouchEnabled()</code>).
  * 
  * @param enabled the new touch-enabled state
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
- *    
+ *
+ * @see Display#getTouchEnabled
+ *
  * @since 3.7
  */
 public void setTouchEnabled(boolean enabled) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java
index 5ac2a6d5cb..462a724795 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java
@@ -926,10 +926,10 @@ public Shell getActiveShell () {
 }
 
 /**
- * Returns the single instance of the application menu bar or null
- * when there is no application menu bar for the platform.
+ * Returns the single instance of the application menu bar, or
+ * <code>null</code> if there is no application menu bar for the platform.
  *
- * @return the application menu bar or <code>null</code>
+ * @return the application menu bar, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -1664,10 +1664,10 @@ public Image getSystemImage (int id) {
 }
 
 /**
- * Returns the single instance of the system-provided menu for the application.
- * On platforms where no menu is provided for the application this method returns null.
+ * Returns the single instance of the system-provided menu for the application, or
+ * <code>null</code> on platforms where no menu is provided for the application.
  *
- * @return the system menu or <code>null</code>
+ * @return the system menu, or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -1734,8 +1734,10 @@ public Thread getThread () {
 }
 
 /**	 
- * Returns true if a touch-aware input device is attached to the system,
- * enabled, and ready for use.
+ * Returns a boolean indicating whether a touch-aware input device is
+ * attached to the system and is ready for use.
+ *
+ * @return <code>true</code> if a touch-aware input device is detected, or <code>false</code> otherwise
  *
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java
index e1b6464a5b..b645d90b6f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java
@@ -317,6 +317,8 @@ public boolean getEnabled () {
 /**
  * Gets the identifier associated with the receiver.
  *
+ * @return the receiver's identifier
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Shell.java
index ef4f236c47..1f6e42f426 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Shell.java
@@ -804,7 +804,8 @@ public Point getMinimumSize () {
 /**
  * Gets the receiver's modified state.
  *
- * </ul>
+ * @return <code>true</code> if the receiver is marked as modified, or <code>false</code> otherwise
+ * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
@@ -819,9 +820,9 @@ public boolean getModified () {
 
 /** 
  * Returns the region that defines the shape of the shell,
- * or null if the shell has the default shape.
+ * or <code>null</code> if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell (or null)
+ * @return the region that defines the shape of the shell, or <code>null</code>
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -843,13 +844,13 @@ public Shell getShell () {
 }
 
 /**
- * Returns the instance of the ToolBar object representing the tool bar that can appear on the
- * trim of the shell. This will return <code>null</code> if the platform does not support tool bars that
- * not part of the content area of the shell, or if the style of the shell does not support a 
- * tool bar. 
+ * Returns a ToolBar object representing the tool bar that can be shown in the receiver's
+ * trim. This will return <code>null</code> if the platform does not support tool bars that
+ * are not part of the content area of the shell, or if the Shell's style does not support 
+ * having a tool bar. 
  * <p>
  * 
- * @return a ToolBar object representing the window's tool bar or null.
+ * @return a ToolBar object representing the Shell's tool bar, or <ocde>null</code>.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java
index ddf188ac6a..250c891d40 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java
@@ -748,7 +748,7 @@ public String getText (int start, int end) {
  * Returns the widget's text as a character array.
  * <p>
  * The text for a text widget is the characters in the widget, or
- * a zero length array if this has never been set.
+ * a zero-length array if this has never been set.
  * </p>
  *
  * @return a character array that contains the widget's text
@@ -757,7 +757,9 @@ public String getText (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #setTextChars(char[])
+ *
  * @since 3.7
  */
 public char [] getTextChars () {
@@ -1396,9 +1398,9 @@ public void setText (String string) {
 }
 
 /**
- * Sets the contents of the receiver to the characters in the array. If the receiver has style
- * SINGLE and the argument contains multiple lines of text, the result of this
- * operation is undefined and may vary from platform to platform.
+ * Sets the contents of the receiver to the characters in the array. If the receiver
+ * has style <code>SWT.SINGLE</code> and the argument contains multiple lines of text
+ * then the result of this operation is undefined and may vary between platforms.
  *
  * @param text a character array that contains the new text
  *
@@ -1409,7 +1411,9 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
+ *
  * @see #getTextChars()
+ *
  * @since 3.7
  */
 public void setTextChars (char [] text) {