Bug 314492 - Do the annual copyright/javadoc bashAFTER_JAVADOC_BASH_FOR_36RC3

173 files changed, 2435 insertions, 347 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java
index ab856c3af9..1a85e8f725 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java
@@ -1557,13 +1557,46 @@ public class Accessible {
 	 * indicating that something has changed within a custom control.
 	 *
 	 * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send
-	 * @param eventData an object containing event-specific data
+	 * @param eventData an object containing event-specific data, or null if there is no event-specific data
 	 * 
 	 * @exception SWTException <ul>
 	 *    <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li>
 	 *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li>
 	 * </ul>
 	 * 
+	 * @see ACC#EVENT_ACTION_CHANGED
+	 * @see ACC#EVENT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE
+	 * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED
+	 * @see ACC#EVENT_DOCUMENT_RELOAD
+	 * @see ACC#EVENT_HYPERLINK_ACTIVATED
+	 * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED
+	 * @see ACC#EVENT_LOCATION_CHANGED
+	 * @see ACC#EVENT_NAME_CHANGED
+	 * @see ACC#EVENT_PAGE_CHANGED
+	 * @see ACC#EVENT_SECTION_CHANGED
+	 * @see ACC#EVENT_SELECTION_CHANGED
+	 * @see ACC#EVENT_STATE_CHANGED
+	 * @see ACC#EVENT_TABLE_CAPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_SUMMARY_CHANGED
+	 * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_TEXT_CARET_MOVED
+	 * @see ACC#EVENT_TEXT_CHANGED
+	 * @see ACC#EVENT_TEXT_COLUMN_CHANGED
+	 * @see ACC#EVENT_TEXT_SELECTION_CHANGED
+	 * @see ACC#EVENT_VALUE_CHANGED
+	 * 
 	 * @since 3.6
 	 */
 	public void sendEvent(int event, Object eventData) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java
index bb3c5cc05f..0ab7cc9a77 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java
@@ -2981,13 +2981,46 @@ public class Accessible {
 	 * indicating that something has changed within a custom control.
 	 *
 	 * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send
-	 * @param eventData an object containing event-specific data
+	 * @param eventData an object containing event-specific data, or null if there is no event-specific data
 	 * 
 	 * @exception SWTException <ul>
 	 *    <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li>
 	 *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li>
 	 * </ul>
 	 * 
+	 * @see ACC#EVENT_ACTION_CHANGED
+	 * @see ACC#EVENT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE
+	 * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED
+	 * @see ACC#EVENT_DOCUMENT_RELOAD
+	 * @see ACC#EVENT_HYPERLINK_ACTIVATED
+	 * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED
+	 * @see ACC#EVENT_LOCATION_CHANGED
+	 * @see ACC#EVENT_NAME_CHANGED
+	 * @see ACC#EVENT_PAGE_CHANGED
+	 * @see ACC#EVENT_SECTION_CHANGED
+	 * @see ACC#EVENT_SELECTION_CHANGED
+	 * @see ACC#EVENT_STATE_CHANGED
+	 * @see ACC#EVENT_TABLE_CAPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_SUMMARY_CHANGED
+	 * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_TEXT_CARET_MOVED
+	 * @see ACC#EVENT_TEXT_CHANGED
+	 * @see ACC#EVENT_TEXT_COLUMN_CHANGED
+	 * @see ACC#EVENT_TEXT_SELECTION_CHANGED
+	 * @see ACC#EVENT_VALUE_CHANGED
+	 * 
 	 * @since 3.6
 	 */
 	public void sendEvent(int event, Object eventData) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java
index 066ad1bc10..41eb5f5e4f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java
@@ -576,13 +576,46 @@ public class Accessible {
 	 * indicating that something has changed within a custom control.
 	 *
 	 * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send
-	 * @param eventData an object containing event-specific data
+	 * @param eventData an object containing event-specific data, or null if there is no event-specific data
 	 * 
 	 * @exception SWTException <ul>
 	 *    <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li>
 	 *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li>
 	 * </ul>
 	 * 
+	 * @see ACC#EVENT_ACTION_CHANGED
+	 * @see ACC#EVENT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE
+	 * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED
+	 * @see ACC#EVENT_DOCUMENT_RELOAD
+	 * @see ACC#EVENT_HYPERLINK_ACTIVATED
+	 * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED
+	 * @see ACC#EVENT_LOCATION_CHANGED
+	 * @see ACC#EVENT_NAME_CHANGED
+	 * @see ACC#EVENT_PAGE_CHANGED
+	 * @see ACC#EVENT_SECTION_CHANGED
+	 * @see ACC#EVENT_SELECTION_CHANGED
+	 * @see ACC#EVENT_STATE_CHANGED
+	 * @see ACC#EVENT_TABLE_CAPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_SUMMARY_CHANGED
+	 * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_TEXT_CARET_MOVED
+	 * @see ACC#EVENT_TEXT_CHANGED
+	 * @see ACC#EVENT_TEXT_COLUMN_CHANGED
+	 * @see ACC#EVENT_TEXT_SELECTION_CHANGED
+	 * @see ACC#EVENT_VALUE_CHANGED
+	 * 
 	 * @since 3.6
 	 */
 	public void sendEvent(int event, Object eventData) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java
index 683d944a36..f1b21b906f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java
@@ -770,13 +770,46 @@ public class Accessible {
 	 * indicating that something has changed within a custom control.
 	 *
 	 * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send
-	 * @param eventData an object containing event-specific data
+	 * @param eventData an object containing event-specific data, or null if there is no event-specific data
 	 * 
 	 * @exception SWTException <ul>
 	 *    <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li>
 	 *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li>
 	 * </ul>
 	 * 
+	 * @see ACC#EVENT_ACTION_CHANGED
+	 * @see ACC#EVENT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE
+	 * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED
+	 * @see ACC#EVENT_DOCUMENT_RELOAD
+	 * @see ACC#EVENT_HYPERLINK_ACTIVATED
+	 * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED
+	 * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED
+	 * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED
+	 * @see ACC#EVENT_LOCATION_CHANGED
+	 * @see ACC#EVENT_NAME_CHANGED
+	 * @see ACC#EVENT_PAGE_CHANGED
+	 * @see ACC#EVENT_SECTION_CHANGED
+	 * @see ACC#EVENT_SELECTION_CHANGED
+	 * @see ACC#EVENT_STATE_CHANGED
+	 * @see ACC#EVENT_TABLE_CAPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED
+	 * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED
+	 * @see ACC#EVENT_TABLE_SUMMARY_CHANGED
+	 * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED
+	 * @see ACC#EVENT_TEXT_CARET_MOVED
+	 * @see ACC#EVENT_TEXT_CHANGED
+	 * @see ACC#EVENT_TEXT_COLUMN_CHANGED
+	 * @see ACC#EVENT_TEXT_SELECTION_CHANGED
+	 * @see ACC#EVENT_VALUE_CHANGED
+	 * 
 	 * @since 3.6
 	 */
 	public void sendEvent(int event, Object eventData) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
index f9c17e81d6..6ad9d48963 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
@@ -25,6 +25,12 @@ import org.eclipse.swt.internal.carbon.OS;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java
index ac7ab05d94..e69e101ff5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java
@@ -24,6 +24,12 @@ import org.eclipse.swt.internal.cocoa.*;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
index 21ef001cee..2ab0e06ce8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
@@ -23,6 +23,12 @@ package org.eclipse.swt.dnd;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
index 6a6dabc616..63ce761cb3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
@@ -25,6 +25,12 @@ import org.eclipse.swt.internal.gtk.*;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
index da99125db1..f61960f492 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
@@ -27,6 +27,12 @@ import org.eclipse.swt.internal.motif.XTextProperty;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
index 568f1e51df..056d74aad0 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
@@ -26,6 +26,12 @@ import org.eclipse.swt.internal.photon.OS;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java
index 3dfc44cbaa..8fef1f9440 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java
@@ -25,6 +25,12 @@ import org.eclipse.swt.internal.wpf.*;
  *     String textData = "Hello World";
  * </code></pre>
  * 
+ * <p>Note the <code>TextTransfer</code> does not change the content of the text
+ * data. For a better integration with the platform, the application should convert
+ * the line delimiters used in the text data to the standard line delimiter used by the
+ * platform.
+ * </p>
+ * 
  * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java
index 8e86a7e2c2..477401e4f2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java
@@ -321,12 +321,13 @@ public static boolean launch (String fileName) {
 /**
  * Launches the operating system executable associated with the file or
  * URL (http:// or https://).  If the file is an executable then the
- * executable is launched.  If a valid working directory is specified
- * it is used as working directory for the launched program.
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
  * Note that a <code>Display</code> must already exist to guarantee
  * that this method returns an appropriate result.
  *
- * @param fileName the file or program name or URL (http:// or https://)
+ * @param fileName the file name or program name or URL (http:// or https://)
  * @param workingDir the name of the working directory or null
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java
index 7663476ee2..df4ee14df2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java
@@ -265,12 +265,13 @@ public static boolean launch (String fileName) {
 /**
  * Launches the operating system executable associated with the file or
  * URL (http:// or https://).  If the file is an executable then the
- * executable is launched.  If a valid working directory is specified
- * it is used as working directory for the launched program.
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
  * Note that a <code>Display</code> must already exist to guarantee
  * that this method returns an appropriate result.
  *
- * @param fileName the file or program name or URL (http:// or https://)
+ * @param fileName the file name or program name or URL (http:// or https://)
  * @param workingDir the name of the working directory or null
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java
index ae9a27baac..77cf60cece 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java
@@ -95,12 +95,13 @@ public static boolean launch (String fileName) {
 /**
  * Launches the operating system executable associated with the file or
  * URL (http:// or https://).  If the file is an executable then the
- * executable is launched.  If a valid working directory is specified
- * it is used as working directory for the launched program.
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
  * Note that a <code>Display</code> must already exist to guarantee
  * that this method returns an appropriate result.
  *
- * @param fileName the file or program name or URL (http:// or https://)
+ * @param fileName the file name or program name or URL (http:// or https://)
  * @param workingDir the name of the working directory or null
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java
index 5fbec60dc1..6f78ce277c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java
@@ -1027,23 +1027,24 @@ public static boolean launch(String fileName) {
 }
 
 /**
-* Launches the operating system executable associated with the file or
-* URL (http:// or https://).  If the file is an executable then the
-* executable is launched.  If a valid working directory is specified 
-* it is used as the working directory for the launched program.
-* Note that a <code>Display</code> must already exist to guarantee
-* that this method returns an appropriate result.
-*
-* @param fileName the file or program name or URL (http:// or https://)
-* @param workingDir the name of the working directory or null
-* @return <code>true</code> if the file is launched, otherwise <code>false</code>
-* 
-* @exception IllegalArgumentException <ul>
-*    <li>ERROR_NULL_ARGUMENT when fileName is null</li>
-* </ul>
-* 
-* @since 3.6
-*/
+ * Launches the operating system executable associated with the file or
+ * URL (http:// or https://).  If the file is an executable then the
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
+ * Note that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
+ *
+ * @param fileName the file name or program name or URL (http:// or https://)
+ * @param workingDir the name of the working directory or null
+ * @return <code>true</code> if the file is launched, otherwise <code>false</code>
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT when fileName is null</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public static boolean launch (String fileName, String workingDir) {
 	return launch(Display.getCurrent(), fileName, workingDir);
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java
index a13fe75f61..58a8d97e20 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java
@@ -750,24 +750,24 @@ public static boolean launch(String fileName) {
 }
 
 /**
-* Launches the operating system executable associated with the file or
-* URL (http:// or https://).  If the file is an executable then the
-* executable is launched.  If a valid working directory is specified 
-* it is used as the working directory for the launched program.
-* Note that a <code>Display</code> must already exist to guarantee
-* that this method returns an appropriate result.
-*
-* @param fileName the file or program name or URL (http:// or https://)
-* @param workingDir the name of the working directory or null
-* @return <code>true</code> if the file is launched, otherwise <code>false</code>
-* 
-* @exception IllegalArgumentException <ul>
-*    <li>ERROR_NULL_ARGUMENT when fileName is null</li>
-*    <li>ERROR_INVALID_ARGUMENT when workingDir is not valid</li>
-* </ul>
-* 
-* @since 3.6
-*/
+ * Launches the operating system executable associated with the file or
+ * URL (http:// or https://).  If the file is an executable then the
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
+ * Note that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
+ *
+ * @param fileName the file name or program name or URL (http:// or https://)
+ * @param workingDir the name of the working directory or null
+ * @return <code>true</code> if the file is launched, otherwise <code>false</code>
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT when fileName is null</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public static boolean launch (String fileName, String workingDir) {
 	return launch(Display.getCurrent(), fileName, workingDir);
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java
index 72f1eac66a..741fa4666f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java
@@ -178,18 +178,18 @@ public static boolean launch (String fileName) {
 /**
  * Launches the operating system executable associated with the file or
  * URL (http:// or https://).  If the file is an executable then the
- * executable is launched.  If a valid working directory is specified 
- * it is used as the working directory for the launched program.
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
  * Note that a <code>Display</code> must already exist to guarantee
  * that this method returns an appropriate result.
  *
- * @param fileName the file or program name or URL (http:// or https://)
+ * @param fileName the file name or program name or URL (http:// or https://)
  * @param workingDir the name of the working directory or null
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
  * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT when fileName is null</li>
- *    <li>ERROR_INVALID_ARGUMENT when workingDir is not valid</li>
  * </ul>
  * 
  * @since 3.6
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java
index c0d0c106ed..c4993e7766 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java
@@ -242,18 +242,18 @@ public static boolean launch (String fileName) {
 /**
  * Launches the operating system executable associated with the file or
  * URL (http:// or https://).  If the file is an executable then the
- * executable is launched.  If a valid working directory is specified 
- * it is used as the working directory for the launched program.
+ * executable is launched. The program is launched with the specified
+ * working directory only when the <code>workingDir</code> exists and
+ * <code>fileName</code> is an executable.
  * Note that a <code>Display</code> must already exist to guarantee
  * that this method returns an appropriate result.
  *
- * @param fileName the file or program name or URL (http:// or https://)
+ * @param fileName the file name or program name or URL (http:// or https://)
  * @param workingDir the name of the working directory or null
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
  * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT when fileName is null</li>
- *    <li>ERROR_INVALID_ARGUMENT when workingDir is not valid</li>
  * </ul>
  * 
  * @since 3.6
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
index 147a45f282..4a2cb56ccf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
@@ -680,7 +680,7 @@ void init(PathData data) {
  * <p>
  * This method gets the dispose state for the Path.
  * When a Path has been disposed, it is an error to
- * invoke any other method using the Path.
+ * invoke any other method (except {@link #dispose()}) using the Path.
  *
  * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
index 978d8279d8..9e94116ef0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
@@ -185,7 +185,7 @@ void destroy() {
  * <p>
  * This method gets the dispose state for the Pattern.
  * When a Pattern has been disposed, it is an error to
- * invoke any other method using the Pattern.
+ * invoke any other method (except {@link #dispose()}) using the Pattern.
  *
  * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
index 5072156713..067008c5ac 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
@@ -213,7 +213,7 @@ public void invert() {
  * <p>
  * This method gets the dispose state for the Transform.
  * When a Transform has been disposed, it is an error to
- * invoke any other method using the Transform.
+ * invoke any other method (except {@link #dispose()}) using the Transform.
  *
  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java
index a8d82e0856..ca1b545dcb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java
@@ -246,7 +246,7 @@ void init( int red, int green, int blue) {
  * <p>
  * This method gets the dispose state for the color.
  * When a color has been disposed, it is an error to
- * invoke any other method using the color.
+ * invoke any other method (except {@link #dispose()}) using the color.
  *
  * @return <code>true</code> when the color is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java
index e3fa79059b..3fd6125ee1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java
@@ -74,6 +74,10 @@ Cursor(Device device) {
  * <p>
  * You must dispose the cursor when it is no longer required. 
  * </p>
+ * NOTE:
+ * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)}
+ * instead of using this constructor. This way you can avoid the 
+ * overhead of disposing the Cursor resource.
  *
  * @param device the device on which to allocate the cursor
  * @param style the style of cursor to allocate
@@ -604,7 +608,7 @@ public int hashCode () {
  * <p>
  * This method gets the dispose state for the cursor.
  * When a cursor has been disposed, it is an error to
- * invoke any other method using the cursor.
+ * invoke any other method (except {@link #dispose()}) using the cursor.
  *
  * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java
index c45930b1fa..5f1e41e9e6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java
@@ -413,7 +413,7 @@ int createCFString(String str) {
  * <p>
  * This method gets the dispose state for the font.
  * When a font has been disposed, it is an error to
- * invoke any other method using the font.
+ * invoke any other method (except {@link #dispose()}) using the font.
  *
  * @return <code>true</code> when the font is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java
index 36e4f46bae..806758f07a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java
@@ -2543,7 +2543,7 @@ public boolean isClipped() {
  * <p>
  * This method gets the dispose state for the GC.
  * When a GC has been disposed, it is an error to
- * invoke any other method using the GC.
+ * invoke any other method (except {@link #dispose()}) using the GC.
  *
  * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java
index 8f8d57e2c8..cf0e30a926 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java
@@ -925,7 +925,7 @@ public int internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data 
+ * @param data the platform specific GC data
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -939,7 +939,7 @@ public void internal_dispose_GC (int context, GCData data) {
  * <p>
  * This method gets the dispose state for the image.
  * When an image has been disposed, it is an error to
- * invoke any other method using the image.
+ * invoke any other method (except {@link #dispose()}) using the image.
  *
  * @return <code>true</code> when the image is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
index 8715722063..6f0dc4e311 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
@@ -721,7 +721,7 @@ void init(PathData data) {
  * <p>
  * This method gets the dispose state for the Path.
  * When a Path has been disposed, it is an error to
- * invoke any other method using the Path.
+ * invoke any other method (except {@link #dispose()}) using the Path.
  *
  * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
index 94fb2fcef7..c2d0dd368a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
@@ -276,7 +276,7 @@ int drawPatternProc (int ref, int context) {
  * <p>
  * This method gets the dispose state for the Pattern.
  * When a Pattern has been disposed, it is an error to
- * invoke any other method using the Pattern.
+ * invoke any other method (except {@link #dispose()}) using the Pattern.
  *
  * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java
index 20539077fd..6eb7585fb0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java
@@ -417,7 +417,7 @@ public boolean intersects(Rectangle rect) {
  * <p>
  * This method gets the dispose state for the region.
  * When a region has been disposed, it is an error to
- * invoke any other method using the region.
+ * invoke any other method (except {@link #dispose()}) using the region.
  *
  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java
index 6b3005efb3..4167bf31e4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java
@@ -1565,6 +1565,17 @@ public int[] getSegments() {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1722,6 +1733,17 @@ public int getWidth () {
 	return wrapWidth == 0 ? -1 : wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout();	
 	return wrapIndent;
@@ -1744,7 +1766,7 @@ static boolean isUnderlineSupported (TextStyle style) {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1885,7 +1907,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1894,6 +1916,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1948,7 +1972,7 @@ public void setOrientation(int orientation) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1957,12 +1981,18 @@ public void setOrientation(int orientation) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1980,6 +2010,23 @@ public void setSegments(int[] segments) {
 	this.segments = segments;
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
@@ -2215,6 +2262,20 @@ public void setWidth (int width) {
 	setLayoutControl(OS.kATSULineWidthTag, OS.Long2Fix(Math.max(0, width)), 4);
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout ();
 	if (wrapIndent < 0) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
index c35a4aabed..0a627750d2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
@@ -208,7 +208,7 @@ public void invert() {
  * <p>
  * This method gets the dispose state for the Transform.
  * When a Transform has been disposed, it is an error to
- * invoke any other method using the Transform.
+ * invoke any other method (except {@link #dispose()}) using the Transform.
  *
  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java
index 0211c05643..cf64bd55ff 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java
@@ -103,6 +103,12 @@ public Button (Composite parent, int style) {
  * <code>widgetSelected</code> is called when the control is selected by the user.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
index a44ed95978..781853d25b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
@@ -283,7 +283,7 @@ void reskinChildren (int flags) {
  * the source area to the destination and then causing the area
  * of the source which is not covered by the destination to
  * be repainted. Children that intersect the rectangle are
- * optionally moved during the operation. In addition, outstanding
+ * optionally moved during the operation. In addition, all outstanding
  * paint events are flushed before the source area is copied to
  * ensure that the contents of the canvas are drawn correctly.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java
index c9140595d2..574b9b0ac8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java
@@ -46,7 +46,7 @@ import org.eclipse.swt.internal.carbon.Rect;
  * <dt><b>Styles:</b></dt>
  * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Selection, Verify</dd>
+ * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java
index fa60b9cf74..c5d5c65487 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java
@@ -268,6 +268,33 @@ void createScrolledHandle (int parentHandle) {
 	OS.HIObjectSetAccessibilityIgnored (handle, true);
 }
 
+/** 
+ * Fills the interior of the rectangle specified by the arguments,
+ * with the receiver's background. 
+ *
+ * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from
+ * the <code>gc</code> origin to the origin of the parent image background. This is useful
+ * to ensure proper alignment of the image background.</p>
+ * 
+ * @param gc the gc where the rectangle is to be filled
+ * @param x the x coordinate of the rectangle to be filled
+ * @param y the y coordinate of the rectangle to be filled
+ * @param width the width of the rectangle to be filled
+ * @param height the height of the rectangle to be filled
+ * @param offsetX the image background x offset 
+ * @param offsetY the image background y offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @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>
+ * 
+ * @since 3.6
+ */
 public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) {
 	checkWidget ();
 	if (gc == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -813,6 +840,64 @@ public void layout (Control [] changed) {
 	layout (changed, SWT.NONE);
 }
 
+/**
+ * Forces a lay out (that is, sets the size and location) of all widgets that 
+ * are in the parent hierarchy of the changed control up to and including the 
+ * receiver. 
+ * <p>
+ * The parameter <code>flags</code> may be a combination of:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be laid out</dd>
+ * <dt><b>SWT.CHANGED</b></dt>
+ * <dd>the layout must flush its caches</dd>
+ * <dt><b>SWT.DEFER</b></dt>
+ * <dd>layout will be deferred</dd>
+ * </dl>
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code>
+ * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the 
+ * hierarchy must not rely on any information cached about the changed control or
+ * any of its ancestors.  The layout may (potentially) optimize the
+ * work it is doing by assuming that none of the peers of the changed
+ * control have changed state since the last layout.
+ * If an ancestor does not have a layout, skip it.
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code>
+ * indicates that the whole widget tree should be laid out. And the flag
+ * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached
+ * information for all controls that are laid out. 
+ * </p>
+ * <p>
+ * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by
+ * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call
+ * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when
+ * appropriate (usually before the next event is handled). When this flag is set,
+ * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>.
+ * </p>
+ * <p>
+ * Note: Layout is different from painting. If a child is
+ * moved or resized such that an area in the parent is
+ * exposed, then the parent will paint. If no child is
+ * affected, the parent will not paint.
+ * </p>
+ * 
+ * @param changed a control that has had a state change which requires a recalculation of its size
+ * @param flags the flags specifying how the layout should happen
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> 
+ *    <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</li>
+ * </ul>
+ * @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>
+ *
+ * @since 3.6
+ */
 public void layout (Control [] changed, int flags) {
 	checkWidget ();
 	if (changed != null) {
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 3582442b25..c06d8de1a1 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
@@ -36,7 +36,8 @@ import org.eclipse.swt.accessibility.Accessible;
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
+ *     Paint, Resize, Traverse</dd>
  * </dl>
  * </p><p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -712,7 +713,7 @@ void destroyWidget () {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -754,7 +755,7 @@ public boolean dragDetect (Event event) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1286,6 +1287,11 @@ int getMininumHeight () {
  * 
  * @return the receiver's monitor
  * 
+ * @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>
+ * 
  * @since 3.0
  */
 public Monitor getMonitor () {
@@ -4251,7 +4257,7 @@ boolean traverseMnemonic (char key) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -4289,7 +4295,7 @@ public boolean traverse (int traversal, Event event) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -4406,7 +4412,8 @@ boolean traverse (int traversal, char character, int keyCode, int keyLocation, i
  * traversal action. The argument should be one of the constants:
  * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, 
  * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, 
- * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>.
+ * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>,
+ * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>.
  *
  * @param traversal the type of traversal
  * @return true if the traversal succeeded
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 b92c9b377b..552e27fc96 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
@@ -91,7 +91,7 @@ import org.eclipse.swt.graphics.*;
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>Close, Dispose, Settings</dd>
+ * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd>
  * </dl>
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
@@ -2095,6 +2095,18 @@ public Image getSystemImage (int id) {
 	return null;
 }
 
+/**
+ * Returns the single instance of the system taskBar or null
+ * when there is no system taskBar available for the platform.
+ *
+ * @return the system taskBar or <code>null</code>
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.6
+ */
 public TaskBar getSystemTaskBar () {
 	checkDevice ();
 	return null;
@@ -3820,6 +3832,8 @@ public static void setAppName (String name) {
  * Sets the application version to the argument.
  *
  * @param version the new app version
+ * 
+ * @since 3.6
  */
 public static void setAppVersion (String version) {
 	APP_VERSION = version;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
index 1fcd663a9d..a74de593d8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
@@ -674,6 +674,18 @@ void setFontStyle (Font font) {
  * include the mnemonic character and line delimiters. The only delimiter
  * the HREF attribute supports is the quotation mark (").
  * </p>
+ * <p>
+ * Mnemonics are indicated by an '&amp;' that causes the next
+ * character to be the mnemonic. The receiver can have a    
+ * mnemonic in the text preceding each link. When the user presses a
+ * key sequence that matches the mnemonic, focus is assigned
+ * to the link that follows the text. Mnemonics in links and in
+ * the trailing text are ignored. On most platforms,
+ * the mnemonic appears underlined but may be emphasised in a
+ * platform specific manner.  The mnemonic indicator character
+ * '&amp;' can be escaped by doubling it in the string, causing
+ * a single '&amp;' to be displayed.
+ * </p> 
  * 
  * @param string the new text
  *
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 427638f987..6611e9355b 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
@@ -184,7 +184,13 @@ public void addHelpListener (HelpListener listener) {
  * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
- *
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
+ * 
  * @param listener the listener which should be notified when the menu item is selected by the user
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
index 3b81bf9b20..b4eeb50836 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
@@ -370,8 +370,7 @@ public Point getSize () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -387,6 +386,19 @@ public int getThumb () {
     return OS.GetControlViewSize (handle);
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb relative to its parent.
+ * 
+ * @return the thumb bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbBounds () {
 	checkWidget();
 	int rgnHandle = OS.NewRgn ();
@@ -402,6 +414,20 @@ public Rectangle getThumbBounds () {
 	return result;
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb track relative to its parent. This rectangle
+ * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}.
+ * 
+ * @return the thumb track bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbTrackBounds () {
 	checkWidget();
 	HIThemeTrackDrawInfo info = new HIThemeTrackDrawInfo();
@@ -741,10 +767,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java
index b94b1e0601..008dfe83e8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java
@@ -297,8 +297,7 @@ public int getSelection () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -459,10 +458,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
index 59a2729307..025be821e0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
@@ -1049,11 +1049,11 @@ public void setIncrement (int value) {
 
 /**
  * Sets the maximum value that the receiver will allow.  This new
- * value will be ignored if it is not greater than the receiver's current
+ * value will be ignored if it is less than the receiver's current
  * minimum value.  If the new maximum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new maximum, which must be greater than the current minimum
+ * @param value the new maximum, which must be greater than or equal to the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1071,11 +1071,11 @@ public void setMaximum (int value) {
 
 /**
  * Sets the minimum value that the receiver will allow.  This new
- * value will be ignored if it is not less than the receiver's
+ * value will be ignored if it is greater than the receiver's
  * current maximum value.  If the new minimum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new minimum, which must be less than the current maximum
+ * @param value the new minimum, which must be less than or equal to the current maximum
  *
  * @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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
index 55dca25922..e567770875 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
@@ -225,10 +225,10 @@ public Color getBackground (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @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 6a8f4cec50..0a1f28245a 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
@@ -42,7 +42,7 @@ import org.eclipse.swt.graphics.*;
  * <dt><b>Styles:</b></dt>
  * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Verify</dd>
+ * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles MULTI and SINGLE may be specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java
index 9a8c9e5ab9..c2bd67b18e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java
@@ -187,6 +187,12 @@ int actionProc (int theControl, int partCode) {
  * the event object detail field contains the value <code>SWT.ARROW</code>.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified when the control is selected by the user,
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
index 12621663f6..9a2292bd29 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
@@ -375,10 +375,10 @@ public Color getBackground (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1186,8 +1186,6 @@ public void setFont (int index, Font font) {
  *
  * @param color the new color (or null)
  *
- * @since 2.0
- * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
index d96fa8254e..631dfb329b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
@@ -665,6 +665,7 @@ int drawItemProc (int browser, int item, int property, int itemState, int theRec
  * <code>true</code> when sent the message <code>isDisposed()</code>.
  * Any internal connections between the widgets in the tree will
  * have been removed to facilitate garbage collection.
+ * This method does nothing if the widget is already disposed.
  * <p>
  * NOTE: This method is not called recursively on the descendants
  * of the receiver. This means that, widget implementers can not
@@ -981,7 +982,7 @@ boolean isActive () {
  * <p>
  * This method gets the dispose state for the widget.
  * When a widget has been disposed, it is an error to
- * invoke any other method using the widget.
+ * invoke any other method (except {@link #dispose()}) using the widget.
  * </p>
  *
  * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise
@@ -1577,8 +1578,31 @@ protected void removeListener (int eventType, SWTEventListener handler) {
 }
 
 /**
+ * Marks the widget to be skinned. 
+ * <p>
+ * The skin event is sent to the receiver's display when appropriate (usually before the next event
+ * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin
+ * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> 
+ * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it 
+ * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor 
+ * while specifying the <code>SWT.ALL</code> flag.  
+ * </p>
+ * <p>
+ * The parameter <code>flags</code> may be either:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be skinned</dd>
+ * <dt><b>SWT.NONE</b></dt>
+ * <dd>only the receiver should be skinned</dd>
+ * </dl>
+ * </p>
+ * @param flags the flags specifying how to reskin
  * 
- * @param flags
+ * @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>
  * @since 3.6
  */
 public void reskin (int flags) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
index 3b22aeaf86..175dd4843a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
@@ -246,7 +246,7 @@ void init(int red, int green, int blue) {
  * <p>
  * This method gets the dispose state for the color.
  * When a color has been disposed, it is an error to
- * invoke any other method using the color.
+ * invoke any other method (except {@link #dispose()}) using the color.
  *
  * @return <code>true</code> when the color is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
index 5453a7c820..7f4ba3922d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
@@ -90,6 +90,10 @@ Cursor(Device device) {
  * <p>
  * You must dispose the cursor when it is no longer required. 
  * </p>
+ * NOTE:
+ * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)}
+ * instead of using this constructor. This way you can avoid the 
+ * overhead of disposing the Cursor resource.
  *
  * @param device the device on which to allocate the cursor
  * @param style the style of cursor to allocate
@@ -426,7 +430,7 @@ public int hashCode () {
  * <p>
  * This method gets the dispose state for the cursor.
  * When a cursor has been disposed, it is an error to
- * invoke any other method using the cursor.
+ * invoke any other method (except {@link #dispose()}) using the cursor.
  *
  * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
index c23e63777a..b1be7e9c16 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
@@ -352,7 +352,7 @@ void init(String name, float height, int style, String nsName) {
  * <p>
  * This method gets the dispose state for the font.
  * When a font has been disposed, it is an error to
- * invoke any other method using the font.
+ * invoke any other method (except {@link #dispose()}) using the font.
  *
  * @return <code>true</code> when the font is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
index 96a786d06e..602f6800a6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
@@ -2959,7 +2959,7 @@ public boolean isClipped() {
  * <p>
  * This method gets the dispose state for the GC.
  * When a GC has been disposed, it is an error to
- * invoke any other method using the GC.
+ * invoke any other method (except {@link #dispose()}) using the GC.
  *
  * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
index 1a5d6fb667..3a38788510 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
@@ -1159,7 +1159,7 @@ public int /*long*/ internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data 
+ * @param data the platform specific GC data
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -1183,7 +1183,7 @@ public void internal_dispose_GC (int /*long*/ context, GCData data) {
  * <p>
  * This method gets the dispose state for the image.
  * When an image has been disposed, it is an error to
- * invoke any other method using the image.
+ * invoke any other method (except {@link #dispose()}) using the image.
  *
  * @return <code>true</code> when the image is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
index 431a97a093..1de065c702 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
@@ -708,7 +708,7 @@ void init(PathData data) {
  * <p>
  * This method gets the dispose state for the Path.
  * When a Path has been disposed, it is an error to
- * invoke any other method using the Path.
+ * invoke any other method (except {@link #dispose()}) using the Path.
  *
  * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
index 1670e9ab87..4d72b20f4f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
@@ -195,7 +195,7 @@ void destroy() {
  * <p>
  * This method gets the dispose state for the Pattern.
  * When a Pattern has been disposed, it is an error to
- * invoke any other method using the Pattern.
+ * invoke any other method (except {@link #dispose()}) using the Pattern.
  *
  * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
index 52be267307..68351dc271 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
@@ -631,7 +631,7 @@ public boolean intersects(Rectangle rect) {
  * <p>
  * This method gets the dispose state for the region.
  * When a region has been disposed, it is an error to
- * invoke any other method using the region.
+ * invoke any other method (except {@link #dispose()}) using the region.
  *
  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java
index 3657f11714..ecf88c9b1e 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java
@@ -1341,6 +1341,17 @@ public int[] getSegments() {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1492,6 +1503,17 @@ public int getWidth () {
 	return wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout();	
 	return wrapIndent;
@@ -1523,7 +1545,7 @@ void initClasses () {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1676,7 +1698,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1685,6 +1707,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1701,6 +1725,20 @@ public void setIndent (int indent) {
 	}
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout ();
 	if (wrapIndent < 0) return;
@@ -1769,7 +1807,7 @@ public void setOrientation(int orientation) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1778,12 +1816,18 @@ public void setOrientation(int orientation) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1807,6 +1851,23 @@ public void setSegments(int[] segments) {
 	}
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
index 6fdb13de11..dc6c63e9a2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
@@ -243,7 +243,7 @@ public void invert() {
  * <p>
  * This method gets the dispose state for the Transform.
  * When a Transform has been disposed, it is an error to
- * invoke any other method using the Transform.
+ * invoke any other method (except {@link #dispose()}) using the Transform.
  *
  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java
index 7c2f8abab2..40d56b0bc2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java
@@ -104,6 +104,12 @@ public Button (Composite parent, int style) {
  * <code>widgetSelected</code> is called when the control is selected by the user.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java
index ea50a2e451..3312be1507 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java
@@ -278,7 +278,7 @@ void reskinChildren (int flags) {
  * the source area to the destination and then causing the area
  * of the source which is not covered by the destination to
  * be repainted. Children that intersect the rectangle are
- * optionally moved during the operation. In addition, outstanding
+ * optionally moved during the operation. In addition, all outstanding
  * paint events are flushed before the source area is copied to
  * ensure that the contents of the canvas are drawn correctly.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java
index c03cfcb60e..56f58424fa 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java
@@ -41,7 +41,7 @@ import org.eclipse.swt.internal.cocoa.*;
  * <dt><b>Styles:</b></dt>
  * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Selection, Verify</dd>
+ * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java
index 1d8527e434..3d19efb529 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java
@@ -295,6 +295,33 @@ void createHandle () {
 	}
 }
 
+/** 
+ * Fills the interior of the rectangle specified by the arguments,
+ * with the receiver's background. 
+ *
+ * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from
+ * the <code>gc</code> origin to the origin of the parent image background. This is useful
+ * to ensure proper alignment of the image background.</p>
+ * 
+ * @param gc the gc where the rectangle is to be filled
+ * @param x the x coordinate of the rectangle to be filled
+ * @param y the y coordinate of the rectangle to be filled
+ * @param width the width of the rectangle to be filled
+ * @param height the height of the rectangle to be filled
+ * @param offsetX the image background x offset 
+ * @param offsetY the image background y offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @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>
+ * 
+ * @since 3.6
+ */
 public void drawBackground(GC gc, int x, int y, int width, int height, int offsetX, int offsetY) {
 	checkWidget ();
 	if (gc == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -710,6 +737,64 @@ public void layout (Control [] changed) {
 	layout (changed, SWT.NONE);
 }
 
+/**
+ * Forces a lay out (that is, sets the size and location) of all widgets that 
+ * are in the parent hierarchy of the changed control up to and including the 
+ * receiver. 
+ * <p>
+ * The parameter <code>flags</code> may be a combination of:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be laid out</dd>
+ * <dt><b>SWT.CHANGED</b></dt>
+ * <dd>the layout must flush its caches</dd>
+ * <dt><b>SWT.DEFER</b></dt>
+ * <dd>layout will be deferred</dd>
+ * </dl>
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code>
+ * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the 
+ * hierarchy must not rely on any information cached about the changed control or
+ * any of its ancestors.  The layout may (potentially) optimize the
+ * work it is doing by assuming that none of the peers of the changed
+ * control have changed state since the last layout.
+ * If an ancestor does not have a layout, skip it.
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code>
+ * indicates that the whole widget tree should be laid out. And the flag
+ * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached
+ * information for all controls that are laid out. 
+ * </p>
+ * <p>
+ * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by
+ * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call
+ * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when
+ * appropriate (usually before the next event is handled). When this flag is set,
+ * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>.
+ * </p>
+ * <p>
+ * Note: Layout is different from painting. If a child is
+ * moved or resized such that an area in the parent is
+ * exposed, then the parent will paint. If no child is
+ * affected, the parent will not paint.
+ * </p>
+ * 
+ * @param changed a control that has had a state change which requires a recalculation of its size
+ * @param flags the flags specifying how the layout should happen
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> 
+ *    <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</li>
+ * </ul>
+ * @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>
+ *
+ * @since 3.6
+ */
 public void layout (Control [] changed, int flags) {
 	checkWidget ();
 	if (changed != null) {
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 4a13222355..a6f811461b 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
@@ -26,7 +26,8 @@ import org.eclipse.swt.internal.cocoa.*;
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
+ *     Paint, Resize, Traverse</dd>
  * </dl>
  * </p><p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -965,7 +966,7 @@ void doCommandBySelector (int /*long*/ id, int /*long*/ sel, int /*long*/ select
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1007,7 +1008,7 @@ public boolean dragDetect (Event event) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1559,6 +1560,11 @@ int getMininumHeight () {
  * 
  * @return the receiver's monitor
  * 
+ * @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>
+ * 
  * @since 3.0
  */
 public Monitor getMonitor () {
@@ -4054,7 +4060,7 @@ boolean traverseMnemonic (char key) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -4092,7 +4098,7 @@ public boolean traverse (int traversal, Event event) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -4209,7 +4215,8 @@ boolean traverse (int traversal, char character, int keyCode, int keyLocation, i
  * traversal action. The argument should be one of the constants:
  * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, 
  * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, 
- * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>.
+ * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>,
+ * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>.
  *
  * @param traversal the type of traversal
  * @return true if the traversal succeeded
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 a1d4eda1c8..8daac5cad8 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
@@ -78,7 +78,7 @@ import org.eclipse.swt.internal.cocoa.*;
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>Close, Dispose, Settings</dd>
+ * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd>
  * </dl>
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
@@ -1874,6 +1874,18 @@ public Tray getSystemTray () {
 	return tray = new Tray (this, SWT.NONE);
 }
 
+/**
+ * Returns the single instance of the system taskBar or null
+ * when there is no system taskBar available for the platform.
+ *
+ * @return the system taskBar or <code>null</code>
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.6
+ */
 public TaskBar getSystemTaskBar () {
 	checkDevice ();
 	if (taskBar != null) return taskBar;
@@ -3832,6 +3844,8 @@ public static void setAppName (String name) {
  * Sets the application version to the argument.
  *
  * @param version the new app version
+ * 
+ * @since 3.6
  */
 public static void setAppVersion (String version) {
 	APP_VERSION = version;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java
index d702ad1739..6f46287341 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java
@@ -629,6 +629,18 @@ void setOrientation () {
  * include the mnemonic character and line delimiters. The only delimiter
  * the HREF attribute supports is the quotation mark (").
  * </p>
+ * <p>
+ * Mnemonics are indicated by an '&amp;' that causes the next
+ * character to be the mnemonic. The receiver can have a    
+ * mnemonic in the text preceding each link. When the user presses a
+ * key sequence that matches the mnemonic, focus is assigned
+ * to the link that follows the text. Mnemonics in links and in
+ * the trailing text are ignored. On most platforms,
+ * the mnemonic appears underlined but may be emphasised in a
+ * platform specific manner.  The mnemonic indicator character
+ * '&amp;' can be escaped by doubling it in the string, causing
+ * a single '&amp;' to be displayed.
+ * </p> 
  * 
  * @param string the new text
  *
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 2dafb6776c..4f5fbbc397 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
@@ -184,7 +184,13 @@ public void addHelpListener (HelpListener listener) {
  * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
- *
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
+ * 
  * @param listener the listener which should be notified when the menu item is selected by the user
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java
index f92d6fe6e8..2b287f8bb2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java
@@ -284,8 +284,7 @@ public Point getSize () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -301,6 +300,19 @@ public int getThumb () {
 	return thumb;
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb relative to its parent.
+ * 
+ * @return the thumb bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbBounds () {
 	checkWidget();
 	NSRect rect = view.rectForPart(OS.NSScrollerKnob);
@@ -308,6 +320,20 @@ public Rectangle getThumbBounds () {
 	return new Rectangle((int)rect.x, (int)rect.y, (int)rect.width, (int)rect.height);
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb track relative to its parent. This rectangle
+ * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}.
+ * 
+ * @return the thumb track bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbTrackBounds () {
 	checkWidget();
 	NSRect rect = view.rectForPart(OS.NSScrollerKnobSlot);
@@ -616,10 +642,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java
index f62d24c951..502957e5b1 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java
@@ -283,8 +283,7 @@ public int getSelection () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -475,10 +474,13 @@ void updateBar (int selection, int minimum, int maximum, int thumb) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java
index a436e58f48..cbf4d1d5b3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java
@@ -791,11 +791,11 @@ public void setIncrement (int value) {
 
 /**
  * Sets the maximum value that the receiver will allow.  This new
- * value will be ignored if it is not greater than the receiver's current
+ * value will be ignored if it is less than the receiver's current
  * minimum value.  If the new maximum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new maximum, which must be greater than the current minimum
+ * @param value the new maximum, which must be greater than or equal to the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -813,11 +813,11 @@ public void setMaximum (int value) {
 
 /**
  * Sets the minimum value that the receiver will allow.  This new
- * value will be ignored if it is not less than the receiver's
+ * value will be ignored if it is greater than the receiver's
  * current maximum value.  If the new minimum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new minimum, which must be less than the current maximum
+ * @param value the new minimum, which must be less than or equal to the current maximum
  *
  * @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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
index 91095b8629..fd993ba6da 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
@@ -250,10 +250,10 @@ public Color getBackground (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @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/TaskBar.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java
index ad1a61a64a..9e425f5d89 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java
@@ -109,6 +109,19 @@ public int getItemCount () {
 	return itemCount;
 }
 
+/**
+ * Returns the <code>TaskItem</code> for the given <code>Shell</code> or the <code>TaskItem</code> 
+ * for the application if the <code>Shell</code> parameter is <code>null</code>.
+ * If the requested item is not supported by the platform it returns <code>null</code>.
+ * 
+ * @param shell the shell for which the task item is requested, or null to request the application item
+ * @return the task item for the given shell or the application
+ *
+ * @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>
+ */
 public TaskItem getItem (Shell shell) {
 	checkWidget ();
 	for (int i = 0; i < itemCount; i++) {
@@ -128,7 +141,7 @@ public TaskItem getItem (Shell shell) {
 }
 
 /**
- * Returns an array of <code>TaskBarItem</code>s which are the items
+ * Returns an array of <code>TaskItem</code>s which are the items
  * in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java
index 128e006af4..921bb7263f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java
@@ -16,7 +16,7 @@ import org.eclipse.swt.graphics.*;
 import org.eclipse.swt.internal.cocoa.*;
 
 /**
- * Instances of this class represent a taskbar item.
+ * Instances of this class represent a task item.
  * 
  * <dl>
  * <dt><b>Styles:</b></dt>
@@ -96,16 +96,49 @@ void destroyWidget () {
 	releaseHandle ();
 }
 
+/**
+ * Returns the receiver's pop up menu if it has one, or null
+ * if it does not.
+ *
+ * @return the receiver's menu
+ *
+ * @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>
+ */
 public Menu getMenu () {
 	checkWidget ();
 	return menu;
 } 
 
+/**
+ * Returns the receiver's overlay image if it has one, or null
+ * if it does not.
+ *
+ * @return the receiver's overlay image
+ *
+ * @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>
+ */
 public Image getOverlayImage () {
 	checkWidget ();
 	return overlayImage;
 }
 
+/**
+ * Returns the receiver's overlay text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's overlay text
+ *
+ * @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>
+ */
 public String getOverlayText () {
 	checkWidget ();
 	return overlayText;
@@ -127,11 +160,31 @@ public TaskBar getParent () {
 	return parent;
 }
 
+/**
+ * Returns the receiver's progress.
+ *
+ * @return the receiver's progress
+ *
+ * @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>
+ */
 public int getProgress () {
 	checkWidget ();
 	return progress;
 }
 
+/**
+ * Returns the receiver's progress state.
+ *
+ * @return the receiver's progress 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>
+ * </ul>
+ */
 public int getProgressState () {
 	checkWidget ();
 	return progressState;
@@ -151,6 +204,37 @@ void releaseWidget () {
 	shell = null;
 }
 
+/**
+ * Sets the receiver's pop up menu to the argument. The way the menu is
+ * shown is platform specific.
+ * 
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return the NULL.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * set this feature on the <code>TaskItem</code> for application.<br>
+ * On Windows, this feature will only work on RCP applications.</p>
+ *
+ * <p>
+ * The menu should be fully created before this method is called.
+ * Dynamic changes to the menu after the method is called will not be reflected
+ * in the native menu.</p> 
+ *
+ * @param menu the new pop up menu
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_MENU_NOT_POP_UP - the menu is not a pop up menu</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the menu has been disposed</li> 
+ * </ul>
+ * @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>
+ */
 public void setMenu (Menu menu) {
 	checkWidget ();
 	if (menu != null) {
@@ -162,6 +246,33 @@ public void setMenu (Menu menu) {
 	this.menu = menu;
 }
 
+/**
+ * Sets the receiver's overlay image, which may be null
+ * indicating that no image should be displayed. The bounds
+ * for the overlay image is determined by the platform and in 
+ * general it should be a small image.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return the NULL.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param overlayImage the new overlay image (may be null)
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the overlayImage has been disposed</li> 
+ * </ul>
+ * @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>
+ */
 public void setOverlayImage (Image image) {
 	checkWidget ();
 	if (image != null && image.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -170,6 +281,32 @@ public void setOverlayImage (Image image) {
 	updateImage ();
 }
 
+/**
+ * Sets the receiver's overlay text. The space available to display the
+ * overlay text is platform dependent and in general it should be no longer
+ * than a few characters.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return an empty string.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param overlayText the new overlay text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the overlayText is null</li>
+ * </ul>
+ * @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>
+ */
 public void setOverlayText (String string) {
 	checkWidget ();
 	if (string == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -178,6 +315,31 @@ public void setOverlayText (String string) {
 	updateImage ();
 }
 
+/**
+ * Sets the receiver's progress, the progress represents a percentage and
+ * should be in range from 0 to 100. The progress is only shown when the progress
+ * state is different than <code>SWT#DEFAULT</code>.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return zero.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param progress the new progress
+ *
+ * @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 {@link #setProgressState(int)}
+ */
 public void setProgress (int progress) {
 	checkWidget ();
 	progress = Math.max (0, Math.min (progress, PROGRESS_MAX));
@@ -186,6 +348,41 @@ public void setProgress (int progress) {
 	updateImage ();
 }
 
+/**
+ * Sets the receiver's progress state, the state can be one of
+ * the following:
+ * <p><ul>
+ * <li>{@link SWT#DEFAULT}</li>
+ * <li>{@link SWT#NORMAL}</li>
+ * <li>{@link SWT#PAUSED}</li>
+ * <li>{@link SWT#ERROR}</li>
+ * <li>{@link SWT#INDETERMINATE}</li>
+ * </ul></p>
+ * 
+ * The percentage of progress shown by the states <code>SWT#NORMAL</code>, <code>SWT#PAUSED</code>, 
+ * <code>SWT#ERROR</code> is set with <code>setProgress()</code>. <br>
+ * The state <code>SWT#DEFAULT</code> indicates that no progress should be shown.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return <code>SWT#DEFAULT</code>.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param progressState the new progress 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>
+ * </ul>
+ * 
+ * #see {@link #setProgress(int)}
+ */
 public void setProgressState (int progressState) {
 	checkWidget ();
 	if (this.progressState == progressState) return;
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 5ad98300ca..ca72a9bca5 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
@@ -30,7 +30,7 @@ import org.eclipse.swt.internal.cocoa.*;
  * <dt><b>Styles:</b></dt>
  * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Verify</dd>
+ * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles MULTI and SINGLE may be specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
index e76a5a53fc..c2698365b7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
@@ -241,6 +241,12 @@ boolean accessibilityIsIgnored(int /*long*/ id, int /*long*/ sel) {
  * the event object detail field contains the value <code>SWT.ARROW</code>.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified when the control is selected by the user,
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
index eaf464d5e1..7f53aea0c4 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
@@ -422,10 +422,10 @@ public Color getBackground (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1230,8 +1230,6 @@ public void setFont (int index, Font font) {
  *
  * @param color the new color (or null)
  *
- * @since 2.0
- * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java
index 9a48de1d7b..b5f2dc7b49 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java
@@ -325,8 +325,31 @@ void becomeKeyWindow (int /*long*/ id, int /*long*/ sel) {
 }
 
 /**
+ * Marks the widget to be skinned. 
+ * <p>
+ * The skin event is sent to the receiver's display when appropriate (usually before the next event
+ * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin
+ * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> 
+ * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it 
+ * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor 
+ * while specifying the <code>SWT.ALL</code> flag.  
+ * </p>
+ * <p>
+ * The parameter <code>flags</code> may be either:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be skinned</dd>
+ * <dt><b>SWT.NONE</b></dt>
+ * <dd>only the receiver should be skinned</dd>
+ * </dl>
+ * </p>
+ * @param flags the flags specifying how to reskin
  * 
- * @param flags
+ * @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>
  * @since 3.6
  */
 public void reskin (int flags) {
@@ -575,6 +598,7 @@ void destroyWidget () {
  * <code>true</code> when sent the message <code>isDisposed()</code>.
  * Any internal connections between the widgets in the tree will
  * have been removed to facilitate garbage collection.
+ * This method does nothing if the widget is already disposed.
  * <p>
  * NOTE: This method is not called recursively on the descendants
  * of the receiver. This means that, widget implementers can not
@@ -928,7 +952,7 @@ boolean isActive () {
  * <p>
  * This method gets the dispose state for the widget.
  * When a widget has been disposed, it is an error to
- * invoke any other method using the widget.
+ * invoke any other method (except {@link #dispose()}) using the widget.
  * </p>
  *
  * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
index f696a8cec8..b102d6f774 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
@@ -443,7 +443,7 @@ void init(PathData data) {
  * <p>
  * This method gets the dispose state for the Path.
  * When a Path has been disposed, it is an error to
- * invoke any other method using the Path.
+ * invoke any other method (except {@link #dispose()}) using the Path.
  *
  * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
index 44eb166b21..738287d944 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
@@ -172,7 +172,7 @@ void destroy() {
  * <p>
  * This method gets the dispose state for the Pattern.
  * When a Pattern has been disposed, it is an error to
- * invoke any other method using the Pattern.
+ * invoke any other method (except {@link #dispose()}) using the Pattern.
  *
  * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
index ea89969116..79f89ac4ef 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
@@ -199,7 +199,7 @@ public void invert() {
  * <p>
  * This method gets the dispose state for the Transform.
  * When a Transform has been disposed, it is an error to
- * invoke any other method using the Transform.
+ * invoke any other method (except {@link #dispose()}) using the Transform.
  *
  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java
index 329a02df7a..56a5e0a549 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java
@@ -108,13 +108,26 @@ public int getItemCount () {
 	return itemCount;
 }
 
+/**
+ * Returns the <code>TaskItem</code> for the given <code>Shell</code> or the <code>TaskItem</code> 
+ * for the application if the <code>Shell</code> parameter is <code>null</code>.
+ * If the requested item is not supported by the platform it returns <code>null</code>.
+ * 
+ * @param shell the shell for which the task item is requested, or null to request the application item
+ * @return the task item for the given shell or the application
+ *
+ * @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>
+ */
 public TaskItem getItem (Shell shell) {
 	checkWidget ();
 	return null;
 }
 
 /**
- * Returns an array of <code>TaskBarItem</code>s which are the items
+ * Returns an array of <code>TaskItem</code>s which are the items
  * in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java
index 92fabc18d2..4c76d8805c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java
@@ -15,7 +15,7 @@ import org.eclipse.swt.*;
 import org.eclipse.swt.graphics.*;
 
 /**
- * Instances of this class represent a taskbar item.
+ * Instances of this class represent a task item.
  * 
  * <dl>
  * <dt><b>Styles:</b></dt>
@@ -84,16 +84,49 @@ void destroyWidget () {
 	releaseHandle ();
 }
 
+/**
+ * Returns the receiver's pop up menu if it has one, or null
+ * if it does not.
+ *
+ * @return the receiver's menu
+ *
+ * @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>
+ */
 public Menu getMenu () {
 	checkWidget ();
 	return menu;
 } 
 
+/**
+ * Returns the receiver's overlay image if it has one, or null
+ * if it does not.
+ *
+ * @return the receiver's overlay image
+ *
+ * @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>
+ */
 public Image getOverlayImage () {
 	checkWidget();
 	return overlayImage;
 }
 
+/**
+ * Returns the receiver's overlay text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's overlay text
+ *
+ * @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>
+ */
 public String getOverlayText () {
 	checkWidget();
 	return overlayText;
@@ -115,11 +148,31 @@ public TaskBar getParent () {
 	return parent;
 }
 
+/**
+ * Returns the receiver's progress.
+ *
+ * @return the receiver's progress
+ *
+ * @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>
+ */
 public int getProgress () {
 	checkWidget ();
 	return progress;
 }
 
+/**
+ * Returns the receiver's progress state.
+ *
+ * @return the receiver's progress 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>
+ * </ul>
+ */
 public int getProgressState () {
 	checkWidget ();
 	return progressState;
@@ -136,6 +189,37 @@ void releaseWidget () {
 	overlayText = null;
 }
 
+/**
+ * Sets the receiver's pop up menu to the argument. The way the menu is
+ * shown is platform specific.
+ * 
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return the NULL.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * set this feature on the <code>TaskItem</code> for application.<br>
+ * On Windows, this feature will only work on RCP applications.</p>
+ *
+ * <p>
+ * The menu should be fully created before this method is called.
+ * Dynamic changes to the menu after the method is called will not be reflected
+ * in the native menu.</p> 
+ *
+ * @param menu the new pop up menu
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_MENU_NOT_POP_UP - the menu is not a pop up menu</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the menu has been disposed</li> 
+ * </ul>
+ * @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>
+ */
 public void setMenu (Menu menu) {
 	checkWidget ();
 	if (menu != null) {
@@ -148,12 +232,26 @@ public void setMenu (Menu menu) {
 }
 
 /**
- * Sets the receiver's overlay image.
+ * Sets the receiver's overlay image, which may be null
+ * indicating that no image should be displayed. The bounds
+ * for the overlay image is determined by the platform and in 
+ * general it should be a small image.
  *
- * @param overlayImage the new overlay image
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return the NULL.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param overlayImage the new overlay image (may be null)
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the overlayImage has been disposed</li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -166,18 +264,104 @@ public void setOverlayImage (Image overlayImage) {
 	this.overlayImage = overlayImage;
 }
 
+/**
+ * Sets the receiver's overlay text. The space available to display the
+ * overlay text is platform dependent and in general it should be no longer
+ * than a few characters.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return an empty string.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param overlayText the new overlay text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the overlayText is null</li>
+ * </ul>
+ * @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>
+ */
 public void setOverlayText (String overlayText) {
 	checkWidget ();
 	if (overlayText == null) error (SWT.ERROR_NULL_ARGUMENT);
 	this.overlayText = overlayText;
 }
 
+/**
+ * Sets the receiver's progress state, the state can be one of
+ * the following:
+ * <p><ul>
+ * <li>{@link SWT#DEFAULT}</li>
+ * <li>{@link SWT#NORMAL}</li>
+ * <li>{@link SWT#PAUSED}</li>
+ * <li>{@link SWT#ERROR}</li>
+ * <li>{@link SWT#INDETERMINATE}</li>
+ * </ul></p>
+ * 
+ * The percentage of progress shown by the states <code>SWT#NORMAL</code>, <code>SWT#PAUSED</code>, 
+ * <code>SWT#ERROR</code> is set with <code>setProgress()</code>. <br>
+ * The state <code>SWT#DEFAULT</code> indicates that no progress should be shown.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return <code>SWT#DEFAULT</code>.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param progressState the new progress 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>
+ * </ul>
+ * 
+ * #see {@link #setProgress(int)}
+ */
 public void setProgressState (int progressState) {
 	checkWidget ();
 	if (this.progressState == progressState) return;
 	this.progressState = progressState;
 }
 
+/**
+ * Sets the receiver's progress, the progress represents a percentage and
+ * should be in range from 0 to 100. The progress is only shown when the progress
+ * state is different than <code>SWT#DEFAULT</code>.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return zero.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param progress the new progress
+ *
+ * @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 {@link #setProgressState(int)}
+ */
 public void setProgress (int progress) {
 	checkWidget ();
 	progress = Math.max(0, Math.min(progress, PROGRESS_MAX));
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java
index 06f73fc22a..a0f8fbcea6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java
@@ -1157,6 +1157,17 @@ public int[] getSegments() {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1261,6 +1272,17 @@ public int getWidth () {
 	return wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout();
 	return wrapIndent;
@@ -1272,7 +1294,7 @@ public int getWrapIndent () {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1484,7 +1506,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1493,6 +1515,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1564,7 +1588,7 @@ public void setSpacing (int spacing) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1573,12 +1597,18 @@ public void setSpacing (int spacing) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1596,6 +1626,23 @@ public void setSegments(int[] segments) {
 	this.segments = segments;
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
@@ -1776,6 +1823,20 @@ public void setWidth (int width) {
 	this.wrapWidth = width;
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout();
 	if (wrapIndent < 0) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
index fc37502654..abdf2bccaa 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
@@ -428,10 +428,10 @@ public Color getBackground (int columnIndex) {
 	return cellBackgrounds [columnIndex];
 }
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
index 6d2a6705e7..966b66986e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
@@ -843,10 +843,10 @@ public Color getBackground (int columnIndex) {
 	return cellBackgrounds [columnIndex];
 }
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2495,8 +2495,6 @@ public void setFont (int columnIndex, Font font) {
  *
  * @param color the new color (or null)
  *
- * @since 2.0
- * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
index 5e671bc180..7a57f02670 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
@@ -269,7 +269,7 @@ void init(int red, int green, int blue) {
  * <p>
  * This method gets the dispose state for the color.
  * When a color has been disposed, it is an error to
- * invoke any other method using the color.
+ * invoke any other method (except {@link #dispose()}) using the color.
  *
  * @return <code>true</code> when the color is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java
index 9f46a49441..96dfe32955 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java
@@ -92,6 +92,10 @@ Cursor (Device device) {
  * <p>
  * You must dispose the cursor when it is no longer required. 
  * </p>
+ * NOTE:
+ * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)}
+ * instead of using this constructor. This way you can avoid the 
+ * overhead of disposing the Cursor resource.
  *
  * @param device the device on which to allocate the cursor
  * @param style the style of cursor to allocate
@@ -507,7 +511,7 @@ public int hashCode() {
  * <p>
  * This method gets the dispose state for the cursor.
  * When a cursor has been disposed, it is an error to
- * invoke any other method using the cursor.
+ * invoke any other method (except {@link #dispose()}) using the cursor.
  *
  * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
index 97236c4406..2619dbb0d7 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
@@ -268,7 +268,7 @@ void init(String name, float height, int style, byte[] fontString) {
  * <p>
  * This method gets the dispose state for the font.
  * When a font has been disposed, it is an error to
- * invoke any other method using the font.
+ * invoke any other method (except {@link #dispose()}) using the font.
  *
  * @return <code>true</code> when the font is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java
index 2393461310..ac76e2c42e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java
@@ -2892,7 +2892,7 @@ public boolean isClipped() {
  * <p>
  * This method gets the dispose state for the GC.
  * When a GC has been disposed, it is an error to
- * invoke any other method using the GC.
+ * invoke any other method (except {@link #dispose()}) using the GC.
  *
  * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java
index 9a0e5e1aa0..a2785ceb3f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java
@@ -1097,7 +1097,7 @@ public int /*long*/ internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data 
+ * @param data the platform specific GC data
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -1111,7 +1111,7 @@ public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) {
  * <p>
  * This method gets the dispose state for the image.
  * When an image has been disposed, it is an error to
- * invoke any other method using the image.
+ * invoke any other method (except {@link #dispose()}) using the image.
  *
  * @return <code>true</code> when the image is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java
index 0d7e5ce58f..a2b8995ec7 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java
@@ -414,7 +414,7 @@ public boolean intersects(Rectangle rect) {
  * <p>
  * This method gets the dispose state for the region.
  * When a region has been disposed, it is an error to
- * invoke any other method using the region.
+ * invoke any other method (except {@link #dispose()}) using the region.
  *
  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java
index c90cce286e..372b628ae6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java
@@ -1543,6 +1543,17 @@ public int[] getSegments() {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1694,6 +1705,17 @@ public int getWidth () {
 	return wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout ();
 	return wrapIndent;
@@ -1705,7 +1727,7 @@ public int getWrapIndent () {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1832,7 +1854,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1841,6 +1863,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1917,7 +1941,7 @@ public void setSpacing (int spacing) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1926,12 +1950,18 @@ public void setSpacing (int spacing) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1949,6 +1979,23 @@ public void setSegments(int[] segments) {
 	this.segments = segments;
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
@@ -2183,6 +2230,20 @@ void setWidth () {
 	}
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout();
 	if (wrapIndent < 0) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java
index decf696388..f16b2d4038 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java
@@ -118,6 +118,12 @@ static int checkStyle (int style) {
  * <code>widgetSelected</code> is called when the control is selected by the user.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
index 405a09a611..3fd382caa5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
@@ -219,7 +219,7 @@ void reskinChildren (int flags) {
  * the source area to the destination and then causing the area
  * of the source which is not covered by the destination to
  * be repainted. Children that intersect the rectangle are
- * optionally moved during the operation. In addition, outstanding
+ * optionally moved during the operation. In addition, all outstanding
  * paint events are flushed before the source area is copied to
  * ensure that the contents of the canvas are drawn correctly.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java
index 65220987b8..d692fc38df 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java
@@ -42,7 +42,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Selection, Verify</dd>
+ * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
index 10f99d3988..483032f3b0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
@@ -330,6 +330,33 @@ void deregister () {
 	if (socketHandle != 0) display.removeWidget (socketHandle);
 }
 
+/** 
+ * Fills the interior of the rectangle specified by the arguments,
+ * with the receiver's background. 
+ *
+ * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from
+ * the <code>gc</code> origin to the origin of the parent image background. This is useful
+ * to ensure proper alignment of the image background.</p>
+ * 
+ * @param gc the gc where the rectangle is to be filled
+ * @param x the x coordinate of the rectangle to be filled
+ * @param y the y coordinate of the rectangle to be filled
+ * @param width the width of the rectangle to be filled
+ * @param height the height of the rectangle to be filled
+ * @param offsetX the image background x offset 
+ * @param offsetY the image background y offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @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>
+ * 
+ * @since 3.6
+ */
 public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) {
 	checkWidget ();
 	if (gc == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -958,6 +985,64 @@ public void layout (Control [] changed) {
 	layout (changed, SWT.NONE);
 }
 
+/**
+ * Forces a lay out (that is, sets the size and location) of all widgets that 
+ * are in the parent hierarchy of the changed control up to and including the 
+ * receiver. 
+ * <p>
+ * The parameter <code>flags</code> may be a combination of:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be laid out</dd>
+ * <dt><b>SWT.CHANGED</b></dt>
+ * <dd>the layout must flush its caches</dd>
+ * <dt><b>SWT.DEFER</b></dt>
+ * <dd>layout will be deferred</dd>
+ * </dl>
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code>
+ * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the 
+ * hierarchy must not rely on any information cached about the changed control or
+ * any of its ancestors.  The layout may (potentially) optimize the
+ * work it is doing by assuming that none of the peers of the changed
+ * control have changed state since the last layout.
+ * If an ancestor does not have a layout, skip it.
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code>
+ * indicates that the whole widget tree should be laid out. And the flag
+ * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached
+ * information for all controls that are laid out. 
+ * </p>
+ * <p>
+ * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by
+ * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call
+ * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when
+ * appropriate (usually before the next event is handled). When this flag is set,
+ * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>.
+ * </p>
+ * <p>
+ * Note: Layout is different from painting. If a child is
+ * moved or resized such that an area in the parent is
+ * exposed, then the parent will paint. If no child is
+ * affected, the parent will not paint.
+ * </p>
+ * 
+ * @param changed a control that has had a state change which requires a recalculation of its size
+ * @param flags the flags specifying how the layout should happen
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> 
+ *    <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</li>
+ * </ul>
+ * @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>
+ *
+ * @since 3.6
+ */
 public void layout (Control [] changed, int flags) {
 	checkWidget ();
 	if (changed != null) {
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 c71351da74..ae09ff2f67 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
@@ -28,7 +28,8 @@ import org.eclipse.swt.internal.gtk.*;
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
+ *     Paint, Resize, Traverse</dd>
  * </dl>
  * </p><p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -1964,7 +1965,7 @@ public void removeTraverseListener(TraverseListener listener) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2006,7 +2007,7 @@ public boolean dragDetect (Event event) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2421,6 +2422,11 @@ public Menu getMenu () {
  * 
  * @return the receiver's monitor
  * 
+ * @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>
+ * 
  * @since 3.0
  */
 public Monitor getMonitor () {
@@ -3039,7 +3045,7 @@ int /*long*/ imHandle () {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data
+ * @param data the platform specific GC data 
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -4327,7 +4333,8 @@ void sort (int [] items) {
  * traversal action. The argument should be one of the constants:
  * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, 
  * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, 
- * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>.
+ * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>,
+ * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>.
  *
  * @param traversal the type of traversal
  * @return true if the traversal succeeded
@@ -4365,7 +4372,7 @@ public boolean traverse (int traversal) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -4403,7 +4410,7 @@ public boolean traverse (int traversal, Event event) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
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 74c5fa262b..09e289f727 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
@@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*;
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>Close, Dispose, Settings</dd>
+ * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd>
  * </dl>
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
@@ -2305,6 +2305,18 @@ public Font getSystemFont () {
 	return systemFont = Font.gtk_new (this, defaultFont);
 }
 
+/**
+ * Returns the single instance of the system taskBar or null
+ * when there is no system taskBar available for the platform.
+ *
+ * @return the system taskBar or <code>null</code>
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.6
+ */
 public TaskBar getSystemTaskBar () {
 	checkDevice ();
 	return null;
@@ -3674,6 +3686,8 @@ public static void setAppName (String name) {
  * Sets the application version to the argument.
  *
  * @param version the new app version
+ * 
+ * @since 3.6
  */
 public static void setAppVersion (String version) {
 	APP_VERSION = version;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
index efe2611a3c..6495b79f72 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
@@ -712,6 +712,18 @@ void setFontDescription (int /*long*/ font) {
  * include the mnemonic character and line delimiters. The only delimiter
  * the HREF attribute supports is the quotation mark (").
  * </p>
+ * <p>
+ * Mnemonics are indicated by an '&amp;' that causes the next
+ * character to be the mnemonic. The receiver can have a    
+ * mnemonic in the text preceding each link. When the user presses a
+ * key sequence that matches the mnemonic, focus is assigned
+ * to the link that follows the text. Mnemonics in links and in
+ * the trailing text are ignored. On most platforms,
+ * the mnemonic appears underlined but may be emphasised in a
+ * platform specific manner.  The mnemonic indicator character
+ * '&amp;' can be escaped by doubling it in the string, causing
+ * a single '&amp;' to be displayed.
+ * </p> 
  * 
  * @param string the new text
  *
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 38e6ac81c3..d98c2823ac 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
@@ -197,7 +197,13 @@ public void addHelpListener (HelpListener listener) {
  * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
- *
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
+ * 
  * @param listener the listener which should be notified when the menu item is selected by the user
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
index 560c841dfa..07580ec938 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
@@ -306,8 +306,7 @@ public Point getSize () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -325,6 +324,19 @@ public int getThumb () {
 	return (int) adjustment.page_size;
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb relative to its parent.
+ * 
+ * @return the thumb bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbBounds () {
 	checkWidget();
 	int slider_start = OS.GTK_RANGE_SLIDER_START (handle);
@@ -354,6 +366,20 @@ public Rectangle getThumbBounds () {
 	return rect;
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb track relative to its parent. This rectangle
+ * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}.
+ * 
+ * @return the thumb track bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbTrackBounds () {
 	checkWidget();
 	int x = 0, y = 0, width, height;
@@ -746,10 +772,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
index f240cae42a..957b79229d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
@@ -365,8 +365,7 @@ public int getSelection () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -538,10 +537,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
index 73c533f1af..c87d7cdf7b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
@@ -912,11 +912,11 @@ public void setIncrement (int value) {
 
 /**
  * Sets the maximum value that the receiver will allow.  This new
- * value will be ignored if it is not greater than the receiver's current
+ * value will be ignored if it is less than the receiver's current
  * minimum value.  If the new maximum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new maximum, which must be greater than the current minimum
+ * @param value the new maximum, which must be greater than or equal to the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -939,11 +939,11 @@ public void setMaximum (int value) {
 
 /**
  * Sets the minimum value that the receiver will allow.  This new
- * value will be ignored if it is not less than the receiver's
+ * value will be ignored if it is greater than the receiver's
  * current maximum value.  If the new minimum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new minimum, which must be less than the current maximum
+ * @param value the new minimum, which must be less than or equal to the current maximum
  *
  * @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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
index f34843751d..3307d505eb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
@@ -252,10 +252,10 @@ public Color getBackground () {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @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 c0a7aa320f..3b107ce1ed 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
@@ -32,7 +32,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Verify</dd>
+ * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles MULTI and SINGLE may be specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
index d741c89cde..4c5c7d95e6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
@@ -141,6 +141,12 @@ public ToolItem (ToolBar parent, int style, int index) {
  * the event object detail field contains the value <code>SWT.ARROW</code>.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified when the control is selected by the user,
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
index 1102499b31..c40dea482d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
@@ -479,10 +479,10 @@ public Rectangle getBounds (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1449,8 +1449,6 @@ public void setFont (int index, Font font) {
  *
  * @param color the new color (or null)
  *
- * @since 2.0
- * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
index 5da5ebe8c8..48e06014dd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
@@ -435,6 +435,7 @@ void destroyWidget () {
  * <code>true</code> when sent the message <code>isDisposed()</code>.
  * Any internal connections between the widgets in the tree will
  * have been removed to facilitate garbage collection.
+ * This method does nothing if the widget is already disposed.
  * <p>
  * NOTE: This method is not called recursively on the descendants
  * of the receiver. This means that, widget implementers can not
@@ -949,7 +950,7 @@ boolean isActive () {
  * <p>
  * This method gets the dispose state for the widget.
  * When a widget has been disposed, it is an error to
- * invoke any other method using the widget.
+ * invoke any other method (except {@link #dispose()}) using the widget.
  * </p>
  *
  * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise
@@ -1184,8 +1185,31 @@ int /*long*/ rendererRenderProc (int /*long*/ cell, int /*long*/ window, int /*l
 }
 
 /**
+ * Marks the widget to be skinned. 
+ * <p>
+ * The skin event is sent to the receiver's display when appropriate (usually before the next event
+ * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin
+ * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> 
+ * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it 
+ * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor 
+ * while specifying the <code>SWT.ALL</code> flag.  
+ * </p>
+ * <p>
+ * The parameter <code>flags</code> may be either:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be skinned</dd>
+ * <dt><b>SWT.NONE</b></dt>
+ * <dd>only the receiver should be skinned</dd>
+ * </dl>
+ * </p>
+ * @param flags the flags specifying how to reskin
  * 
- * @param flags
+ * @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>
  * @since 3.6
  */
 public void reskin (int flags) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java
index 6f5e63f03c..73cd8bf4f5 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java
@@ -316,7 +316,7 @@ void init(int red, int green, int blue) {
  * <p>
  * This method gets the dispose state for the color.
  * When a color has been disposed, it is an error to
- * invoke any other method using the color.
+ * invoke any other method (except {@link #dispose()}) using the color.
  *
  * @return <code>true</code> when the color is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java
index df20a5435c..672ea191e3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java
@@ -91,6 +91,10 @@ Cursor (Device device) {
  * <p>
  * You must dispose the cursor when it is no longer required. 
  * </p>
+ * NOTE:
+ * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)}
+ * instead of using this constructor. This way you can avoid the 
+ * overhead of disposing the Cursor resource.
  *
  * @param device the device on which to allocate the cursor
  * @param style the style of cursor to allocate
@@ -418,7 +422,7 @@ public int hashCode () {
  * <p>
  * This method gets the dispose state for the cursor.
  * When a cursor has been disposed, it is an error to
- * invoke any other method using the cursor.
+ * invoke any other method (except {@link #dispose()}) using the cursor.
  *
  * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
index 5e46f67d2c..a00669c096 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
@@ -512,7 +512,7 @@ void init (FontData[] fds) {
  * <p>
  * This method gets the dispose state for the font.
  * When a font has been disposed, it is an error to
- * invoke any other method using the font.
+ * invoke any other method (except {@link #dispose()}) using the font.
  *
  * @return <code>true</code> when the font is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java
index c82db1989c..a49e46975d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java
@@ -3414,7 +3414,7 @@ public boolean isClipped() {
  * <p>
  * This method gets the dispose state for the GC.
  * When a GC has been disposed, it is an error to
- * invoke any other method using the GC.
+ * invoke any other method (except {@link #dispose()}) using the GC.
  *
  * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java
index 2ec6fd8882..340d524787 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java
@@ -1171,7 +1171,7 @@ public int internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data 
+ * @param data the platform specific GC data
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -1188,7 +1188,7 @@ public void internal_dispose_GC (int gc, GCData data) {
  * <p>
  * This method gets the dispose state for the image.
  * When an image has been disposed, it is an error to
- * invoke any other method using the image.
+ * invoke any other method (except {@link #dispose()}) using the image.
  *
  * @return <code>true</code> when the image is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java
index 252deb9f03..acf228a010 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java
@@ -387,7 +387,7 @@ public boolean intersects (Rectangle rect) {
  * <p>
  * This method gets the dispose state for the region.
  * When a region has been disposed, it is an error to
- * invoke any other method using the region.
+ * invoke any other method (except {@link #dispose()}) using the region.
  *
  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java
index c73b3ea2b2..2e427560e2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java
@@ -1312,6 +1312,17 @@ public int[] getSegments() {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1430,6 +1441,17 @@ public int getWidth () {
 	return wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout();
 	return wrapIndent;
@@ -1441,7 +1463,7 @@ public int getWrapIndent () {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1659,7 +1681,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1668,6 +1690,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1739,7 +1763,7 @@ public void setSpacing (int spacing) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1748,12 +1772,18 @@ public void setSpacing (int spacing) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1771,6 +1801,23 @@ public void setSegments(int[] segments) {
 	this.segments = segments;
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
@@ -1951,6 +1998,20 @@ public void setWidth (int width) {
 	this.wrapWidth = width;
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout();
 	if (wrapIndent < 0) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java
index 2c10e59b0b..5522a1b451 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java
@@ -175,6 +175,12 @@ void _setText (String string) {
  * <code>widgetSelected</code> is called when the control is selected by the user.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
index 2b4568a6c1..eb758937bc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
@@ -169,7 +169,7 @@ void reskinChildren (int flags) {
  * the source area to the destination and then causing the area
  * of the source which is not covered by the destination to
  * be repainted. Children that intersect the rectangle are
- * optionally moved during the operation. In addition, outstanding
+ * optionally moved during the operation. In addition, all outstanding
  * paint events are flushed before the source area is copied to
  * ensure that the contents of the canvas are drawn correctly.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java
index 8ad4709e7a..2fe3d38758 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java
@@ -42,7 +42,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Selection, Verify</dd>
+ * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java
index 92c32c6bd6..ad42e78fd4 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java
@@ -303,6 +303,33 @@ void deregister () {
 void drawBackground (GC gc, int x, int y, int width, int height) {
 	drawBackground(gc, x, y, width, height, 0, 0);
 }
+/** 
+ * Fills the interior of the rectangle specified by the arguments,
+ * with the receiver's background. 
+ *
+ * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from
+ * the <code>gc</code> origin to the origin of the parent image background. This is useful
+ * to ensure proper alignment of the image background.</p>
+ * 
+ * @param gc the gc where the rectangle is to be filled
+ * @param x the x coordinate of the rectangle to be filled
+ * @param y the y coordinate of the rectangle to be filled
+ * @param width the width of the rectangle to be filled
+ * @param height the height of the rectangle to be filled
+ * @param offsetX the image background x offset 
+ * @param offsetY the image background y offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @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>
+ * 
+ * @since 3.6
+ */
 public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) {
 	checkWidget ();
 	if (gc == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -760,6 +787,64 @@ public void layout (Control [] changed) {
 	layout (changed, SWT.NONE);
 }
 
+/**
+ * Forces a lay out (that is, sets the size and location) of all widgets that 
+ * are in the parent hierarchy of the changed control up to and including the 
+ * receiver. 
+ * <p>
+ * The parameter <code>flags</code> may be a combination of:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be laid out</dd>
+ * <dt><b>SWT.CHANGED</b></dt>
+ * <dd>the layout must flush its caches</dd>
+ * <dt><b>SWT.DEFER</b></dt>
+ * <dd>layout will be deferred</dd>
+ * </dl>
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code>
+ * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the 
+ * hierarchy must not rely on any information cached about the changed control or
+ * any of its ancestors.  The layout may (potentially) optimize the
+ * work it is doing by assuming that none of the peers of the changed
+ * control have changed state since the last layout.
+ * If an ancestor does not have a layout, skip it.
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code>
+ * indicates that the whole widget tree should be laid out. And the flag
+ * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached
+ * information for all controls that are laid out. 
+ * </p>
+ * <p>
+ * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by
+ * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call
+ * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when
+ * appropriate (usually before the next event is handled). When this flag is set,
+ * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>.
+ * </p>
+ * <p>
+ * Note: Layout is different from painting. If a child is
+ * moved or resized such that an area in the parent is
+ * exposed, then the parent will paint. If no child is
+ * affected, the parent will not paint.
+ * </p>
+ * 
+ * @param changed a control that has had a state change which requires a recalculation of its size
+ * @param flags the flags specifying how the layout should happen
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> 
+ *    <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</li>
+ * </ul>
+ * @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>
+ *
+ * @since 3.6
+ */
 public void layout (Control [] changed, int flags) {
 	checkWidget ();
 	if (changed != null) {
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 3b9f7e468c..7a704b3ac0 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
@@ -26,7 +26,8 @@ import org.eclipse.swt.accessibility.*;
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
+ *     Paint, Resize, Traverse</dd>
  * </dl>
  * </p><p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -650,7 +651,7 @@ int defaultForeground () {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -691,7 +692,7 @@ public boolean dragDetect (Event event) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1170,6 +1171,11 @@ int getMinimumHeight () {
  * 
  * @return the receiver's monitor
  * 
+ * @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>
+ * 
  * @since 3.0
  */
 public Monitor getMonitor () {
@@ -3316,7 +3322,7 @@ int traversalCode (int key, XKeyEvent xEvent) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -3353,7 +3359,7 @@ public boolean traverse (int traversal, Event event) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -3490,7 +3496,8 @@ boolean traverse (Event event) {
  * traversal action. The argument should be one of the constants:
  * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, 
  * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, 
- * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>.
+ * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>,
+ * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>.
  *
  * @param traversal the type of traversal
  * @return true if the traversal succeeded
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 8b6748ad44..20bf3904ce 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
@@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*;
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>Close, Dispose, Settings</dd>
+ * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd>
  * </dl>
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
@@ -1956,6 +1956,18 @@ public Image getSystemImage (int style) {
 	if (imagePixmap == 0) return null;
 	return Image.motif_new (this, SWT.ICON, imagePixmap, maskPixmap);
 }
+/**
+ * Returns the single instance of the system taskBar or null
+ * when there is no system taskBar available for the platform.
+ *
+ * @return the system taskBar or <code>null</code>
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.6
+ */
 public TaskBar getSystemTaskBar () {
 	checkDevice ();
 	return null;
@@ -2477,9 +2489,9 @@ public int internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data
+ * @param data the platform specific GC data 
  * 
- *  @noreference This method is not intended to be referenced by clients.
+ * @noreference This method is not intended to be referenced by clients.
  */
 public void internal_dispose_GC (int gc, GCData data) {
 	OS.XFreeGC(xDisplay, gc);
@@ -3416,6 +3428,8 @@ public static void setAppName (String name) {
  * Sets the application version to the argument.
  *
  * @param version the new app version
+ * 
+ * @since 3.6
  */
 public static void setAppVersion (String version) {
 	APP_VERSION = version;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
index 8d82436f87..3d3e43beb4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
@@ -441,6 +441,18 @@ void setForegroundPixel (int pixel) {
  * include the mnemonic character and line delimiters. The only delimiter
  * the HREF attribute supports is the quotation mark (").
  * </p>
+ * <p>
+ * Mnemonics are indicated by an '&amp;' that causes the next
+ * character to be the mnemonic. The receiver can have a    
+ * mnemonic in the text preceding each link. When the user presses a
+ * key sequence that matches the mnemonic, focus is assigned
+ * to the link that follows the text. Mnemonics in links and in
+ * the trailing text are ignored. On most platforms,
+ * the mnemonic appears underlined but may be emphasised in a
+ * platform specific manner.  The mnemonic indicator character
+ * '&amp;' can be escaped by doubling it in the string, causing
+ * a single '&amp;' to be displayed.
+ * </p> 
  * 
  * @param string the new text
  *
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 9731e46e12..5dc8c8abf7 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
@@ -230,7 +230,13 @@ public void addHelpListener (HelpListener listener) {
  * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
- *
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
+ * 
  * @param listener the listener which should be notified when the menu item is selected by the user
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
index 1a5def919b..6415bafe0b 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
@@ -294,8 +294,7 @@ public Point getSize () {
 	return new Point (argList [1] + borders, argList [3] + borders);
 }
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -312,6 +311,19 @@ public int getThumb () {
 	OS.XtGetValues (handle, argList, argList.length / 2);
 	return argList [1];
 }
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb relative to its parent.
+ * 
+ * @return the thumb bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbBounds () {
 	checkWidget();
 	int [] argList = {
@@ -358,6 +370,20 @@ public Rectangle getThumbBounds () {
 	rect.y -= root_y [0];
 	return rect;
 }
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb track relative to its parent. This rectangle
+ * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}.
+ * 
+ * @return the thumb track bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbTrackBounds () {
 	checkWidget();
 	int [] argList = {
@@ -676,10 +702,13 @@ public void setSelection (int selection) {
 	display.setWarnings (warnings);
 }
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java
index 0ac37fc1cc..0255d5343d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java
@@ -258,8 +258,7 @@ public int getSelection () {
 	return argList [1];
 }
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -440,10 +439,13 @@ public void setSelection (int value) {
 	display.setWarnings (warnings);
 }
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
index 1a4266f5ce..11433a7914 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
@@ -697,11 +697,11 @@ public void setIncrement (int value) {
 }
 /**
  * Sets the maximum value that the receiver will allow.  This new
- * value will be ignored if it is not greater than the receiver's current
+ * value will be ignored if it is less than the receiver's current
  * minimum value.  If the new maximum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new maximum, which must be greater than the current minimum
+ * @param value the new maximum, which must be greater than or equal to the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -720,11 +720,11 @@ public void setMaximum (int value) {
 }
 /**
  * Sets the minimum value that the receiver will allow.  This new
- * value will be ignored if it is not less than the receiver's
+ * value will be ignored if it is greater than the receiver's
  * current maximum value.  If the new minimum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new minimum, which must be less than the current maximum
+ * @param value the new minimum, which must be less than or equal to the current maximum
  *
  * @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 bb1201790a..3e72a30b02 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
@@ -32,7 +32,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Verify</dd>
+ * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles MULTI and SINGLE may be specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java
index 9908c4690e..3acbc239c6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java
@@ -140,6 +140,12 @@ public ToolItem (ToolBar parent, int style, int index) {
  * the event object detail field contains the value <code>SWT.ARROW</code>.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified when the control is selected by the user,
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
index 997e427c90..34256cbe9c 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
@@ -340,6 +340,7 @@ void destroyWidget () {
  * <code>true</code> when sent the message <code>isDisposed()</code>.
  * Any internal connections between the widgets in the tree will
  * have been removed to facilitate garbage collection.
+ * This method does nothing if the widget is already disposed.
  * <p>
  * NOTE: This method is not called recursively on the descendants
  * of the receiver. This means that, widget implementers can not
@@ -550,7 +551,7 @@ boolean hooks (int eventType) {
  * <p>
  * This method gets the dispose state for the widget.
  * When a widget has been disposed, it is an error to
- * invoke any other method using the widget.
+ * invoke any other method (except {@link #dispose()}) using the widget.
  * </p>
  *
  * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise
@@ -769,8 +770,31 @@ protected void removeListener (int eventType, SWTEventListener handler) {
 	eventTable.unhook (eventType, handler);
 }
 /**
+ * Marks the widget to be skinned. 
+ * <p>
+ * The skin event is sent to the receiver's display when appropriate (usually before the next event
+ * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin
+ * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> 
+ * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it 
+ * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor 
+ * while specifying the <code>SWT.ALL</code> flag.  
+ * </p>
+ * <p>
+ * The parameter <code>flags</code> may be either:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be skinned</dd>
+ * <dt><b>SWT.NONE</b></dt>
+ * <dd>only the receiver should be skinned</dd>
+ * </dl>
+ * </p>
+ * @param flags the flags specifying how to reskin
  * 
- * @param flags
+ * @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>
  * @since 3.6
  */
 public void reskin (int flags) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
index c7c70a3acc..5c3ea28c05 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
@@ -213,7 +213,7 @@ void init(int red, int green, int blue) {
  * <p>
  * This method gets the dispose state for the color.
  * When a color has been disposed, it is an error to
- * invoke any other method using the color.
+ * invoke any other method (except {@link #dispose()}) using the color.
  *
  * @return <code>true</code> when the color is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java
index 3ad36af8ea..ba1491e739 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java
@@ -81,6 +81,10 @@ Cursor(Device device) {
  * <p>
  * You must dispose the cursor when it is no longer required. 
  * </p>
+ * NOTE:
+ * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)}
+ * instead of using this constructor. This way you can avoid the 
+ * overhead of disposing the Cursor resource.
  *
  * @param device the device on which to allocate the cursor
  * @param style the style of cursor to allocate
@@ -439,7 +443,7 @@ public int hashCode () {
  * <p>
  * This method gets the dispose state for the cursor.
  * When a cursor has been disposed, it is an error to
- * invoke any other method using the cursor.
+ * invoke any other method (except {@link #dispose()}) using the cursor.
  *
  * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
index e94abad930..36ad265242 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
@@ -205,7 +205,7 @@ public int hashCode () {
  * <p>
  * This method gets the dispose state for the font.
  * When a font has been disposed, it is an error to
- * invoke any other method using the font.
+ * invoke any other method (except {@link #dispose()}) using the font.
  *
  * @return <code>true</code> when the font is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java
index c7444289a4..3b01e29575 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java
@@ -2547,7 +2547,7 @@ public boolean isClipped() {
  * <p>
  * This method gets the dispose state for the GC.
  * When a GC has been disposed, it is an error to
- * invoke any other method using the GC.
+ * invoke any other method (except {@link #dispose()}) using the GC.
  *
  * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java
index 92fae7681d..93bb5dca74 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java
@@ -953,7 +953,7 @@ public int internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data 
+ * @param data the platform specific GC data
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -967,7 +967,7 @@ public void internal_dispose_GC (int pmMC, GCData data) {
  * <p>
  * This method gets the dispose state for the image.
  * When an image has been disposed, it is an error to
- * invoke any other method using the image.
+ * invoke any other method (except {@link #dispose()}) using the image.
  *
  * @return <code>true</code> when the image is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java
index 39ac4316ff..9fb0d6d072 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java
@@ -452,7 +452,7 @@ public boolean intersects (Rectangle rect) {
  * <p>
  * This method gets the dispose state for the region.
  * When a region has been disposed, it is an error to
- * invoke any other method using the region.
+ * invoke any other method (except {@link #dispose()}) using the region.
  *
  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java
index 291029074d..ec08b7c8d9 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java
@@ -116,6 +116,12 @@ static int checkStyle (int style) {
  * <code>widgetSelected</code> is called when the control is selected by the user.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
index 44d3d8a528..eda2398f0e 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
@@ -202,7 +202,7 @@ void reskinChildren (int flags) {
  * the source area to the destination and then causing the area
  * of the source which is not covered by the destination to
  * be repainted. Children that intersect the rectangle are
- * optionally moved during the operation. In addition, outstanding
+ * optionally moved during the operation. In addition, all outstanding
  * paint events are flushed before the source area is copied to
  * ensure that the contents of the canvas are drawn correctly.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java
index 8fc948adb5..0999db44db 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java
@@ -42,7 +42,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Selection, Verify</dd>
+ * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java
index 776c6453b5..cc5652c11a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java
@@ -285,6 +285,33 @@ void createScrolledHandle (int parentHandle) {
 	createScrollBars ();
 }
 
+/** 
+ * Fills the interior of the rectangle specified by the arguments,
+ * with the receiver's background. 
+ *
+ * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from
+ * the <code>gc</code> origin to the origin of the parent image background. This is useful
+ * to ensure proper alignment of the image background.</p>
+ * 
+ * @param gc the gc where the rectangle is to be filled
+ * @param x the x coordinate of the rectangle to be filled
+ * @param y the y coordinate of the rectangle to be filled
+ * @param width the width of the rectangle to be filled
+ * @param height the height of the rectangle to be filled
+ * @param offsetX the image background x offset 
+ * @param offsetY the image background y offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @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>
+ * 
+ * @since 3.6
+ */
 public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) {
 	drawBackground(gc, offsetX, offsetY, width, height);
 }
@@ -767,6 +794,64 @@ public void layout (Control [] changed) {
 	layout (changed, SWT.NONE);
 }
 
+/**
+ * Forces a lay out (that is, sets the size and location) of all widgets that 
+ * are in the parent hierarchy of the changed control up to and including the 
+ * receiver. 
+ * <p>
+ * The parameter <code>flags</code> may be a combination of:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be laid out</dd>
+ * <dt><b>SWT.CHANGED</b></dt>
+ * <dd>the layout must flush its caches</dd>
+ * <dt><b>SWT.DEFER</b></dt>
+ * <dd>layout will be deferred</dd>
+ * </dl>
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code>
+ * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the 
+ * hierarchy must not rely on any information cached about the changed control or
+ * any of its ancestors.  The layout may (potentially) optimize the
+ * work it is doing by assuming that none of the peers of the changed
+ * control have changed state since the last layout.
+ * If an ancestor does not have a layout, skip it.
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code>
+ * indicates that the whole widget tree should be laid out. And the flag
+ * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached
+ * information for all controls that are laid out. 
+ * </p>
+ * <p>
+ * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by
+ * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call
+ * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when
+ * appropriate (usually before the next event is handled). When this flag is set,
+ * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>.
+ * </p>
+ * <p>
+ * Note: Layout is different from painting. If a child is
+ * moved or resized such that an area in the parent is
+ * exposed, then the parent will paint. If no child is
+ * affected, the parent will not paint.
+ * </p>
+ * 
+ * @param changed a control that has had a state change which requires a recalculation of its size
+ * @param flags the flags specifying how the layout should happen
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> 
+ *    <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</li>
+ * </ul>
+ * @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>
+ *
+ * @since 3.6
+ */
 public void layout (Control [] changed, int flags) {
 	checkWidget ();
 	if (changed != null) {
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 0dfb6bff88..2dffaa1725 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
@@ -26,7 +26,8 @@ import org.eclipse.swt.accessibility.*;
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
+ *     Paint, Resize, Traverse</dd>
  * </dl>
  * </p><p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -613,7 +614,7 @@ boolean drawGripper (int x, int y, int width, int height, boolean vertical) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -655,7 +656,7 @@ public boolean dragDetect (Event event) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1046,6 +1047,11 @@ public Menu getMenu () {
  * 
  * @return the receiver's monitor
  * 
+ * @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>
+ * 
  * @since 3.0
  */
 public Monitor getMonitor () {
@@ -3158,7 +3164,7 @@ int traversalCode (int key_sym, PhKeyEvent_t ke) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -3196,7 +3202,7 @@ public boolean traverse (int traversal, Event event) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -3344,7 +3350,8 @@ boolean traverse (Event event) {
  * traversal action. The argument should be one of the constants:
  * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, 
  * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, 
- * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>.
+ * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>,
+ * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>.
  *
  * @param traversal the type of traversal
  * @return true if the traversal succeeded
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 fee5904f56..36adcfddbb 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
@@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*;
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>Close, Dispose, Settings</dd>
+ * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd>
  * </dl>
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
@@ -955,6 +955,8 @@ public static void setAppName (String name) {
  * Sets the application version to the argument.
  *
  * @param version the new app version
+ * 
+ * @since 3.6
  */
 public static void setAppVersion (String version) {
 	APP_VERSION = version;
@@ -1348,6 +1350,18 @@ public Image getSystemImage (int id) {
 	return null;
 }
 
+/**
+ * Returns the single instance of the system taskBar or null
+ * when there is no system taskBar available for the platform.
+ *
+ * @return the system taskBar or <code>null</code>
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.6
+ */
 public TaskBar getSystemTaskBar () {
 	checkDevice ();
 	return null;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
index 4864a59b91..70e15590d5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
@@ -595,6 +595,18 @@ public void setFont (Font font) {
  * include the mnemonic character and line delimiters. The only delimiter
  * the HREF attribute supports is the quotation mark (").
  * </p>
+ * <p>
+ * Mnemonics are indicated by an '&amp;' that causes the next
+ * character to be the mnemonic. The receiver can have a    
+ * mnemonic in the text preceding each link. When the user presses a
+ * key sequence that matches the mnemonic, focus is assigned
+ * to the link that follows the text. Mnemonics in links and in
+ * the trailing text are ignored. On most platforms,
+ * the mnemonic appears underlined but may be emphasised in a
+ * platform specific manner.  The mnemonic indicator character
+ * '&amp;' can be escaped by doubling it in the string, causing
+ * a single '&amp;' to be displayed.
+ * </p> 
  * 
  * @param string the new text
  *
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 4553d5e9bf..ec4107da36 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
@@ -197,7 +197,13 @@ public void addHelpListener (HelpListener listener) {
  * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
- *
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
+ * 
  * @param listener the listener which should be notified when the menu item is selected by the user
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
index 42117cd7ab..5e0608d8f0 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
@@ -319,8 +319,7 @@ public Point getSize () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -338,12 +337,39 @@ public int getThumb () {
 	return args [1];
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb relative to its parent.
+ * 
+ * @return the thumb bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbBounds () {
 	checkWidget();
 	//TODO implement getThumbBounds()
 	return null;
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb track relative to its parent. This rectangle
+ * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}.
+ * 
+ * @return the thumb track bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbTrackBounds () {
 	checkWidget();
 	//TODO implement getThumbTrackBounds()
@@ -637,10 +663,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
index 8de4424e49..5825034e52 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
@@ -282,8 +282,7 @@ public Point getSize () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -488,10 +487,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
index e8e5d1ad1a..217890c630 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
@@ -670,11 +670,11 @@ public void setIncrement (int value) {
 
 /**
  * Sets the maximum value that the receiver will allow.  This new
- * value will be ignored if it is not greater than the receiver's current
+ * value will be ignored if it is less than the receiver's current
  * minimum value.  If the new maximum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new maximum, which must be greater than the current minimum
+ * @param value the new maximum, which must be greater than or equal to the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -689,11 +689,11 @@ public void setMaximum (int value) {
 
 /**
  * Sets the minimum value that the receiver will allow.  This new
- * value will be ignored if it is not less than the receiver's
+ * value will be ignored if it is greater than the receiver's
  * current maximum value.  If the new minimum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new minimum, which must be less than the current maximum
+ * @param value the new minimum, which must be less than or equal to the current maximum
  *
  * @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 4fdf962a41..b41ca625ac 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
@@ -32,7 +32,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Verify</dd>
+ * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles MULTI and SINGLE may be specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java
index ee265148db..74ea3c3991 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java
@@ -137,6 +137,12 @@ public ToolItem (ToolBar parent, int style, int index) {
  * the event object detail field contains the value <code>SWT.ARROW</code>.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified when the control is selected by the user,
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
index 986994e6eb..47cd148ec9 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
@@ -422,6 +422,7 @@ void destroyWidget () {
  * <code>true</code> when sent the message <code>isDisposed()</code>.
  * Any internal connections between the widgets in the tree will
  * have been removed to facilitate garbage collection.
+ * This method does nothing if the widget is already disposed.
  * <p>
  * NOTE: This method is not called recursively on the descendants
  * of the receiver. This means that, widget implementers can not
@@ -641,7 +642,7 @@ void hookEvents () {
  * <p>
  * This method gets the dispose state for the widget.
  * When a widget has been disposed, it is an error to
- * invoke any other method using the widget.
+ * invoke any other method (except {@link #dispose()}) using the widget.
  * </p>
  *
  * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise
@@ -916,8 +917,31 @@ protected void removeListener (int eventType, SWTEventListener handler) {
 }
 
 /**
+ * Marks the widget to be skinned. 
+ * <p>
+ * The skin event is sent to the receiver's display when appropriate (usually before the next event
+ * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin
+ * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> 
+ * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it 
+ * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor 
+ * while specifying the <code>SWT.ALL</code> flag.  
+ * </p>
+ * <p>
+ * The parameter <code>flags</code> may be either:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be skinned</dd>
+ * <dt><b>SWT.NONE</b></dt>
+ * <dd>only the receiver should be skinned</dd>
+ * </dl>
+ * </p>
+ * @param flags the flags specifying how to reskin
  * 
- * @param flags
+ * @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>
  * @since 3.6
  */
 public void reskin (int flags) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java
index f2044be0b2..a1664eed8c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java
@@ -235,7 +235,7 @@ void init(int red, int green, int blue) {
  * <p>
  * This method gets the dispose state for the color.
  * When a color has been disposed, it is an error to
- * invoke any other method using the color.
+ * invoke any other method (except {@link #dispose()}) using the color.
  *
  * @return <code>true</code> when the color is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java
index 438360f567..865d702d34 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java
@@ -73,6 +73,10 @@ Cursor(Device device) {
  * <p>
  * You must dispose the cursor when it is no longer required. 
  * </p>
+ * NOTE:
+ * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)}
+ * instead of using this constructor. This way you can avoid the 
+ * overhead of disposing the Cursor resource.
  *
  * @param device the device on which to allocate the cursor
  * @param style the style of cursor to allocate
@@ -426,7 +430,7 @@ public int hashCode () {
  * <p>
  * This method gets the dispose state for the cursor.
  * When a cursor has been disposed, it is an error to
- * invoke any other method using the cursor.
+ * invoke any other method (except {@link #dispose()}) using the cursor.
  *
  * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java
index 7531b4d58b..0d8afcc377 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java
@@ -252,7 +252,7 @@ void init (FontData fd) {
  * <p>
  * This method gets the dispose state for the font.
  * When a font has been disposed, it is an error to
- * invoke any other method using the font.
+ * invoke any other method (except {@link #dispose()}) using the font.
  *
  * @return <code>true</code> when the font is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java
index 07df9561fc..42114a9f44 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java
@@ -2111,7 +2111,7 @@ public boolean isClipped() {
  * <p>
  * This method gets the dispose state for the GC.
  * When a GC has been disposed, it is an error to
- * invoke any other method using the GC.
+ * invoke any other method (except {@link #dispose()}) using the GC.
  *
  * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java
index 04b487a87f..adffe22d71 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java
@@ -1018,7 +1018,7 @@ public int internal_new_GC (GCData data) {
  * </p>
  *
  * @param hDC the platform specific GC handle
- * @param data the platform specific GC data 
+ * @param data the platform specific GC data
  * 
  * @noreference This method is not intended to be referenced by clients.
  */
@@ -1049,7 +1049,7 @@ public void internal_dispose_GC (int dc, GCData data) {
  * <p>
  * This method gets the dispose state for the image.
  * When an image has been disposed, it is an error to
- * invoke any other method using the image.
+ * invoke any other method (except {@link #dispose()}) using the image.
  *
  * @return <code>true</code> when the image is disposed and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java
index 4716a12656..660c61b9a9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java
@@ -608,7 +608,7 @@ void init(PathData data) {
  * <p>
  * This method gets the dispose state for the Path.
  * When a Path has been disposed, it is an error to
- * invoke any other method using the Path.
+ * invoke any other method (except {@link #dispose()}) using the Path.
  *
  * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java
index 6a28e5a41c..fdc45f41fb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java
@@ -197,7 +197,7 @@ void destroy() {
  * <p>
  * This method gets the dispose state for the Pattern.
  * When a Pattern has been disposed, it is an error to
- * invoke any other method using the Pattern.
+ * invoke any other method (except {@link #dispose()}) using the Pattern.
  *
  * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java
index 33d56243ae..ef2497bfcc 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java
@@ -496,7 +496,7 @@ public boolean intersects (Rectangle rect) {
  * <p>
  * This method gets the dispose state for the region.
  * When a region has been disposed, it is an error to
- * invoke any other method using the region.
+ * invoke any other method (except {@link #dispose()}) using the region.
  *
  * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java
index b4877cc31c..990b831407 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java
@@ -1244,6 +1244,17 @@ public int[] getSegments () {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1431,6 +1442,17 @@ public int getWidth () {
 	return wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout();
 	return wrapIndent;
@@ -1442,7 +1464,7 @@ public int getWrapIndent () {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1560,7 +1582,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1569,6 +1591,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1621,7 +1645,7 @@ public void setOrientation (int orientation) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1630,12 +1654,18 @@ public void setOrientation (int orientation) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1653,6 +1683,23 @@ public void setSegments(int[] segments) {
 	this.segments = segments;
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
@@ -1854,6 +1901,20 @@ public void setWidth (int width) {
 	this.wrapWidth = width;
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout();
 	if (wrapIndent < 0) return;	
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java
index 2649deb7d8..820eda47bb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java
@@ -217,7 +217,7 @@ public void invert() {
  * <p>
  * This method gets the dispose state for the Transform.
  * When a Transform has been disposed, it is an error to
- * invoke any other method using the Transform.
+ * invoke any other method (except {@link #dispose()}) using the Transform.
  *
  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java
index 99237de68e..67c04ace69 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java
@@ -102,6 +102,12 @@ public Button (Composite parent, int style) {
  * <code>widgetSelected</code> is called when the control is selected by the user.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java
index 43a26983bc..952705e958 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java
@@ -216,7 +216,7 @@ public void drawBackground (GC gc, int x, int y, int width, int height) {
  * the source area to the destination and then causing the area
  * of the source which is not covered by the destination to
  * be repainted. Children that intersect the rectangle are
- * optionally moved during the operation. In addition, outstanding
+ * optionally moved during the operation. In addition, all outstanding
  * paint events are flushed before the source area is copied to
  * ensure that the contents of the canvas are drawn correctly.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java
index 796bce5b02..2c07ac1929 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java
@@ -41,7 +41,7 @@ import org.eclipse.swt.internal.wpf.OS;
  * <dt><b>Styles:</b></dt>
  * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Selection, Verify</dd>
+ * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java
index 5f3999e80b..cd63a46bbd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java
@@ -752,6 +752,64 @@ public void layout (Control [] changed) {
 	layout (changed, SWT.NONE);
 }
 
+/**
+ * Forces a lay out (that is, sets the size and location) of all widgets that 
+ * are in the parent hierarchy of the changed control up to and including the 
+ * receiver. 
+ * <p>
+ * The parameter <code>flags</code> may be a combination of:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be laid out</dd>
+ * <dt><b>SWT.CHANGED</b></dt>
+ * <dd>the layout must flush its caches</dd>
+ * <dt><b>SWT.DEFER</b></dt>
+ * <dd>layout will be deferred</dd>
+ * </dl>
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code>
+ * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the 
+ * hierarchy must not rely on any information cached about the changed control or
+ * any of its ancestors.  The layout may (potentially) optimize the
+ * work it is doing by assuming that none of the peers of the changed
+ * control have changed state since the last layout.
+ * If an ancestor does not have a layout, skip it.
+ * </p>
+ * <p>
+ * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code>
+ * indicates that the whole widget tree should be laid out. And the flag
+ * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached
+ * information for all controls that are laid out. 
+ * </p>
+ * <p>
+ * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by
+ * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call
+ * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when
+ * appropriate (usually before the next event is handled). When this flag is set,
+ * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>.
+ * </p>
+ * <p>
+ * Note: Layout is different from painting. If a child is
+ * moved or resized such that an area in the parent is
+ * exposed, then the parent will paint. If no child is
+ * affected, the parent will not paint.
+ * </p>
+ * 
+ * @param changed a control that has had a state change which requires a recalculation of its size
+ * @param flags the flags specifying how the layout should happen
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> 
+ *    <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</li>
+ * </ul>
+ * @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>
+ *
+ * @since 3.6
+ */
 public void layout (Control [] changed, int flags) {
 	checkWidget ();
 	if (changed != null) {
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 cc30af6bfb..f84cf790ad 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
@@ -28,7 +28,8 @@ import org.eclipse.swt.effects.*;
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
+ *     Paint, Resize, Traverse</dd>
  * </dl>
  * </p><p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -674,7 +675,7 @@ void destroyWidget () {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -716,7 +717,7 @@ public boolean dragDetect (Event event) {
  * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *   <li>ERROR_NULL_ARGUMENT when the event is null</li>
+ *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1122,6 +1123,11 @@ public Menu getMenu () {
  * 
  * @return the receiver's monitor
  * 
+ * @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>
+ * 
  * @since 3.0
  */
 public Monitor getMonitor () {
@@ -3426,7 +3432,7 @@ boolean translateTraversal (int e) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -3464,7 +3470,7 @@ public boolean traverse (int traversal, Event event) {
  * this from <code>event</code>
  * @param event the KeyDown event
  * 
- * @return true if the traversal succeeded
+ * @return <code>true</code> if the traversal succeeded
  *
  * @exception IllegalArgumentException <ul>
  *   <li>ERROR_NULL_ARGUMENT if the event is null</li>
@@ -3612,7 +3618,8 @@ boolean traverse (Event event) {
  * traversal action. The argument should be one of the constants:
  * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, 
  * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, 
- * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>.
+ * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>,
+ * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>.
  *
  * @param traversal the type of traversal
  * @return true if the traversal succeeded
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 23d1b8e855..3b70638f54 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
@@ -78,7 +78,7 @@ import org.eclipse.swt.graphics.*;
  * <dt><b>Styles:</b></dt>
  * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
- * <dd>Close, Dispose, Settings</dd>
+ * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd>
  * </dl>
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
@@ -1643,6 +1643,18 @@ public Image getSystemImage (int id) {
 	return null;
 }
 
+/**
+ * Returns the single instance of the system taskBar or null
+ * when there is no system taskBar available for the platform.
+ *
+ * @return the system taskBar or <code>null</code>
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.6
+ */
 public TaskBar getSystemTaskBar () {
 	checkDevice ();
 	return null;
@@ -2822,10 +2834,16 @@ public void setData (Object data) {
 }
 
 /**
- * On platforms which support it, sets the application name
- * to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.  Specifying
- * <code>null</code> for the name clears it.
+ * Sets the application name to the argument.
+ * <p>
+ * The application name can be used in several ways,
+ * depending on the platform and tools being used.
+ * On Motif, for example, this can be used to set
+ * the name used for resource lookup. Accessibility
+ * tools may also ask for the application name.
+ * </p><p>
+ * Specifying <code>null</code> for the name clears it.
+ * </p>
  *
  * @param name the new app name or <code>null</code>
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java
index 4a6895c4c8..60aad80fc3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java
@@ -376,6 +376,18 @@ void setForegroundBrush (int brush) {
  * include the mnemonic character and line delimiters. The only delimiter
  * the HREF attribute supports is the quotation mark (").
  * </p>
+ * <p>
+ * Mnemonics are indicated by an '&amp;' that causes the next
+ * character to be the mnemonic. The receiver can have a    
+ * mnemonic in the text preceding each link. When the user presses a
+ * key sequence that matches the mnemonic, focus is assigned
+ * to the link that follows the text. Mnemonics in links and in
+ * the trailing text are ignored. On most platforms,
+ * the mnemonic appears underlined but may be emphasised in a
+ * platform specific manner.  The mnemonic indicator character
+ * '&amp;' can be escaped by doubling it in the string, causing
+ * a single '&amp;' to be displayed.
+ * </p> 
  * 
  * @param string the new text
  *
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 bd7a4e0320..a533ba9b62 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
@@ -182,7 +182,13 @@ public void addHelpListener (HelpListener listener) {
  * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
- *
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
+ * 
  * @param listener the listener which should be notified when the menu item is selected by the user
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java
index c023abe452..cd9f021d24 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java
@@ -322,8 +322,7 @@ public Point getSize () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -339,6 +338,19 @@ public int getThumb () {
 	return (int) OS.ScrollBar_ViewportSize (handle);
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb relative to its parent.
+ * 
+ * @return the thumb bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbBounds () {
 	checkWidget();
 	int track = OS.ScrollBar_Track(handle);
@@ -355,6 +367,20 @@ public Rectangle getThumbBounds () {
 	return rect;
 }
 
+/**
+ * Returns a rectangle describing the size and location of the
+ * receiver's thumb track relative to its parent. This rectangle
+ * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}.
+ * 
+ * @return the thumb track bounds, relative to the {@link #getParent() parent}
+ *
+ * @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>
+ * 
+ * @since 3.6
+ */
 public Rectangle getThumbTrackBounds () {
 	checkWidget();
 	int track = OS.ScrollBar_Track(handle);
@@ -624,10 +650,13 @@ public void setSelection (int selection) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java
index c806643d73..2e59ae1674 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java
@@ -255,8 +255,7 @@ public int getSelection () {
 }
 
 /**
- * Returns the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.
+ * Returns the receiver's thumb value.
  *
  * @return the thumb value
  *
@@ -429,10 +428,13 @@ public void setSelection (int value) {
 }
 
 /**
- * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values.  This new
- * value will be ignored if it is less than one, and will be
+ * Sets the thumb value. The thumb value should be used to represent 
+ * the size of the visual portion of the current range. This value is
+ * usually the same as the page increment value.
+ * <p>
+ * This new value will be ignored if it is less than one, and will be 
  * clamped if it exceeds the receiver's current range.
+ * </p>
  *
  * @param value the new thumb value, which must be at least one and not
  * larger than the size of the current range
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java
index 93685904bf..e91e0ce044 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java
@@ -765,11 +765,11 @@ public void setIncrement (int value) {
 
 /**
  * Sets the maximum value that the receiver will allow.  This new
- * value will be ignored if it is not greater than the receiver's current
+ * value will be ignored if it is less than the receiver's current
  * minimum value.  If the new maximum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new maximum, which must be greater than the current minimum
+ * @param value the new maximum, which must be greater than or equal to the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -785,11 +785,11 @@ public void setMaximum (int value) {
 
 /**
  * Sets the minimum value that the receiver will allow.  This new
- * value will be ignored if it is not less than the receiver's
+ * value will be ignored if it is greater than the receiver's
  * current maximum value.  If the new minimum is applied then the receiver's
  * selection value will be adjusted if necessary to fall within its new range.
  *
- * @param value the new minimum, which must be less than the current maximum
+ * @param value the new minimum, which must be less than or equal to the current maximum
  *
  * @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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java
index 6e4946d3bc..15751546ad 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java
@@ -333,10 +333,10 @@ public Color getBackground (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @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 b5295c1d40..322862c64f 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
@@ -31,7 +31,7 @@ import org.eclipse.swt.events.*;
  * <dt><b>Styles:</b></dt>
  * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
- * <dd>DefaultSelection, Modify, Verify</dd>
+ * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd>
  * </dl>
  * <p>
  * Note: Only one of the styles MULTI and SINGLE may be specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java
index 5dda1d3821..203dba1a30 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java
@@ -136,6 +136,12 @@ public ToolItem (ToolBar parent, int style, int index) {
  * the event object detail field contains the value <code>SWT.ARROW</code>.
  * <code>widgetDefaultSelected</code> is not called.
  * </p>
+ * <p>
+ * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is
+ * also called when the receiver loses selection because another item in the same radio group 
+ * was selected by the user. During <code>widgetSelected</code> the application can use
+ * <code>getSelection()</code> to determine the current selected state of the receiver.
+ * </p>
  *
  * @param listener the listener which should be notified when the control is selected by the user,
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java
index 24e2c25c4e..0540cc5750 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java
@@ -575,10 +575,10 @@ public Color getBackground (int index) {
 }
 
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1305,8 +1305,6 @@ public void setFont (int index, Font font) {
  *
  * @param color the new color (or null)
  *
- * @since 2.0
- * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java
index c016e42a06..41a636eb0a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java
@@ -429,6 +429,7 @@ void destroyWidget () {
  * <code>true</code> when sent the message <code>isDisposed()</code>.
  * Any internal connections between the widgets in the tree will
  * have been removed to facilitate garbage collection.
+ * This method does nothing if the widget is already disposed.
  * <p>
  * NOTE: This method is not called recursively on the descendants
  * of the receiver. This means that, widget implementers can not
@@ -732,7 +733,7 @@ boolean hooks (int eventType) {
  * <p>
  * This method gets the dispose state for the widget.
  * When a widget has been disposed, it is an error to
- * invoke any other method using the widget.
+ * invoke any other method (except {@link #dispose()}) using the widget.
  * </p>
  *
  * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise
@@ -1008,8 +1009,31 @@ protected void removeListener (int eventType, SWTEventListener listener) {
 }
 
 /**
+ * Marks the widget to be skinned. 
+ * <p>
+ * The skin event is sent to the receiver's display when appropriate (usually before the next event
+ * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin
+ * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> 
+ * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it 
+ * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor 
+ * while specifying the <code>SWT.ALL</code> flag.  
+ * </p>
+ * <p>
+ * The parameter <code>flags</code> may be either:
+ * <dl>
+ * <dt><b>SWT.ALL</b></dt>
+ * <dd>all children in the receiver's widget tree should be skinned</dd>
+ * <dt><b>SWT.NONE</b></dt>
+ * <dd>only the receiver should be skinned</dd>
+ * </dl>
+ * </p>
+ * @param flags the flags specifying how to reskin
  * 
- * @param flags
+ * @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>
  * @since 3.6
  */
 public void reskin (int flags) {