Javadoc Basher output pre M9
diff --git a/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java b/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java
index 9df1cec..7bbf8f5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java
@@ -18,10 +18,36 @@
 import org.eclipse.swt.widgets.Display;
 import org.eclipse.swt.widgets.Shell;
 
+/**
+ * This class provides a bridge between SWT and AWT, so that it
+ * is possible to embedded AWT components in SWT and vice versa.
+ * 
+ * @since 3.0
+ */
 public class SWT_AWT {
 
+	/**
+	 * The name of the embedded Frame class. The default class name
+	 * for the platform will be used if <code>null</code>. 
+	 */
 	public static String embeddedFrameClass;
 
+/**
+ * Creates a new <code>java.awt.Frame</code>. This frame is the root for
+ * the AWT components that will be embedded within the composite. In order
+ * for the embedding to succeed, the composite must have been created
+ * with the SWT.EMBEDDED style.
+ * 
+ * @param parent the parent <code>Composite</code> of the new <code>java.awt.Frame</code>
+ * @return a <code>java.awt.Frame</code> to be the parent of the embedded AWT components
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent Composite does not have the SWT.EMBEDDED style</li> 
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public static Frame new_Frame (final Composite parent) {
 	if (parent == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	if ((parent.getStyle () & SWT.EMBEDDED) == 0) {
@@ -31,6 +57,21 @@
 	return null;
 }
 
+/**
+ * Creates a new <code>Shell</code>. This Shell is the root for
+ * the SWT widgets that will be embedded within the AWT canvas. 
+ * 
+ * @param display the display for the new Shell
+ * @param parent the parent <code>java.awt.Canvas</code> of the new Shell
+ * @return a <code>Shell</code> to be the parent of the embedded SWT widgets
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the display is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public static Shell new_Shell (final Display display, final Canvas parent) {
 	if (display == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	if (parent == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT AWT/gtk/org/eclipse/swt/awt/SWT_AWT.java b/bundles/org.eclipse.swt/Eclipse SWT AWT/gtk/org/eclipse/swt/awt/SWT_AWT.java
index 2b81e8a..d2c2a1b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT AWT/gtk/org/eclipse/swt/awt/SWT_AWT.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT AWT/gtk/org/eclipse/swt/awt/SWT_AWT.java
@@ -32,8 +32,18 @@
 import java.awt.event.ComponentAdapter;
 import java.awt.event.ComponentEvent;
 
+/**
+ * This class provides a bridge between SWT and AWT, so that it
+ * is possible to embedded AWT components in SWT and vice versa.
+ * 
+ * @since 3.0
+ */
 public class SWT_AWT {
 
+	/**
+	 * The name of the embedded Frame class. The default class name
+	 * for the platform will be used if <code>null</code>. 
+	 */
 	public static String embeddedFrameClass;
 
 static boolean loaded;
@@ -47,6 +57,22 @@
 	Library.loadLibrary("swt-awt");
 }
 
+/**
+ * Creates a new <code>java.awt.Frame</code>. This frame is the root for
+ * the AWT components that will be embedded within the composite. In order
+ * for the embedding to succeed, the composite must have been created
+ * with the SWT.EMBEDDED style.
+ * 
+ * @param parent the parent <code>Composite</code> of the new <code>java.awt.Frame</code>
+ * @return a <code>java.awt.Frame</code> to be the parent of the embedded AWT components
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent Composite does not have the SWT.EMBEDDED style</li> 
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public static Frame new_Frame (final Composite parent) {
 	if (parent == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	if ((parent.getStyle () & SWT.EMBEDDED) == 0) {
@@ -122,6 +148,21 @@
 	return frame;
 }
 
+/**
+ * Creates a new <code>Shell</code>. This Shell is the root for
+ * the SWT widgets that will be embedded within the AWT canvas. 
+ * 
+ * @param display the display for the new Shell
+ * @param parent the parent <code>java.awt.Canvas</code> of the new Shell
+ * @return a <code>Shell</code> to be the parent of the embedded SWT widgets
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the display is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public static Shell new_Shell (final Display display, final Canvas parent) {
 	if (display == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	if (parent == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT AWT/motif/org/eclipse/swt/awt/SWT_AWT.java b/bundles/org.eclipse.swt/Eclipse SWT AWT/motif/org/eclipse/swt/awt/SWT_AWT.java
index d8aec46..d1402c2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT AWT/motif/org/eclipse/swt/awt/SWT_AWT.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT AWT/motif/org/eclipse/swt/awt/SWT_AWT.java
@@ -32,8 +32,18 @@
 import java.awt.event.ComponentAdapter;
 import java.awt.event.ComponentEvent;
 
+/**
+ * This class provides a bridge between SWT and AWT, so that it
+ * is possible to embedded AWT components in SWT and vice versa.
+ * 
+ * @since 3.0
+ */
 public class SWT_AWT {
 
+	/**
+	 * The name of the embedded Frame class. The default class name
+	 * for the platform will be used if <code>null</code>. 
+	 */
 	public static String embeddedFrameClass;
 
 static boolean loaded;
@@ -47,6 +57,22 @@
 	Library.loadLibrary("swt-awt");
 }
 
+/**
+ * Creates a new <code>java.awt.Frame</code>. This frame is the root for
+ * the AWT components that will be embedded within the composite. In order
+ * for the embedding to succeed, the composite must have been created
+ * with the SWT.EMBEDDED style.
+ * 
+ * @param parent the parent <code>Composite</code> of the new <code>java.awt.Frame</code>
+ * @return a <code>java.awt.Frame</code> to be the parent of the embedded AWT components
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent Composite does not have the SWT.EMBEDDED style</li> 
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public static Frame new_Frame (final Composite parent) {
 	if (parent == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	if ((parent.getStyle () & SWT.EMBEDDED) == 0) {
@@ -125,6 +151,21 @@
 	return frame;
 }
 
+/**
+ * Creates a new <code>Shell</code>. This Shell is the root for
+ * the SWT widgets that will be embedded within the AWT canvas. 
+ * 
+ * @param display the display for the new Shell
+ * @param parent the parent <code>java.awt.Canvas</code> of the new Shell
+ * @return a <code>Shell</code> to be the parent of the embedded SWT widgets
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the display is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public static Shell new_Shell (final Display display, final Canvas parent) {
 	if (display == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	if (parent == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
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 6ab6121..c344674 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
@@ -201,8 +201,9 @@
 	}
 
 	/**
-	 * Gets the control for this Accessible object. 
+	 * Returns the control for this Accessible object. 
 	 *
+	 * @return the receiver's control
 	 * @since 3.0
 	 */
 	public Control getControl() {
@@ -253,8 +254,8 @@
 	 *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li>
 	 * </ul>
 	 * 
-	 * @see ACC#NOTIFY_TEXT_INSERT
-	 * @see ACC#NOTIFY_TEXT_DELETE
+	 * @see ACC#TEXT_INSERT
+	 * @see ACC#TEXT_DELETE
 	 * 
 	 * @since 3.0
 	 */
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 6ed8fa1..a608734 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
@@ -17,12 +17,23 @@
 import org.eclipse.swt.widgets.*;
 
 /**
- * NOTE: The API in the accessibility package is NOT finalized.
- * Use at your own risk, because it will most certainly change.
- * The methods in AccessibleListener are more stable than those
- * in AccessibleControlListener, however please take nothing for
- * granted. The only reason this API is being released at this
- * time is so that other teams can try it out.
+ * Instances of this class provide a bridge between application
+ * code and assistive technology clients. Many platforms provide
+ * default accessible behavior for most widgets, and this class
+ * allows that default behavior to be overridden. Applications
+ * can get the default Accessible object for a control by sending
+ * it <code>getAccessible</code>, and then add an accessible listener
+ * to override simple items like the name and help string, or they
+ * can add an accessible control listener to override complex items.
+ * As a rule of thumb, an application would only want to use the
+ * accessible control listener to implement accessibility for a
+ * custom control.
+ * 
+ * @see Control#getAccessible
+ * @see AccessibleListener
+ * @see AccessibleEvent
+ * @see AccessibleControlListener
+ * @see AccessibleControlEvent
  * 
  * @since 2.0
  */
@@ -128,8 +139,9 @@
 	}
 	
 	/**
-	 * Gets the control for this Accessible object. 
+	 * Returns the control for this Accessible object. 
 	 *
+	 * @return the receiver's control
 	 * @since 3.0
 	 */
 	public Control getControl() {
@@ -164,7 +176,7 @@
 		return result;
 	}
 	
-	/**	 
+	/**
 	 * Invokes platform specific functionality to allocate a new accessible object.
 	 * <p>
 	 * <b>IMPORTANT:</b> This method is <em>not</em> part of the public
@@ -238,7 +250,7 @@
 	 * </ul>
 	 *
 	 * @see AccessibleListener
-	 * @see #addDisposeListener
+	 * @see #addAccessibleListener
 	 */
 	public void removeAccessibleListener (AccessibleListener listener) {
 		checkWidget ();
@@ -274,7 +286,7 @@
 	}
 	
 	/**
-	 * Sends notification to accessible clients that the child selection
+	 * Sends a message to accessible clients that the child selection
 	 * within a custom container control has changed.
 	 *
 	 * @exception SWTException <ul>
@@ -292,7 +304,7 @@
 	}
 
 	/**
-	 * Sends notification to accessible clients that the focus
+	 * Sends a message to accessible clients indicating that the focus
 	 * has changed within a custom control.
 	 *
 	 * @param childID an identifier specifying a child of the control
@@ -301,7 +313,6 @@
 	 *    <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>
-	 * 
 	 */
 	public void setFocus (int childID) {
 		checkWidget ();
@@ -311,7 +322,7 @@
 	}
 	
 	/**
-	 * Sends notification to accessible clients that the text
+	 * Sends a message to accessible clients that the text
 	 * caret has moved within a custom control.
 	 *
 	 * @param index the new caret index within the control
@@ -331,7 +342,7 @@
 	}
 
 	/**
-	 * Sends notification to accessible clients that the text
+	 * Sends a message to accessible clients that the text
 	 * within a custom control has changed.
 	 *
 	 * @param type the type of change, one of <code>ACC.NOTIFY_TEXT_INSERT</code>
@@ -344,8 +355,8 @@
 	 *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li>
 	 * </ul>
 	 * 
-	 * @see ACC#NOTIFY_TEXT_INSERT
-	 * @see ACC#NOTIFY_TEXT_DELETE
+	 * @see ACC#TEXT_INSERT
+	 * @see ACC#TEXT_DELETE
 	 * 
 	 * @since 3.0
 	 */
@@ -357,7 +368,7 @@
 	}
 
 	/**
-	 * Sends notification to accessible clients that the text
+	 * Sends a message to accessible clients that the text
 	 * selection has changed within a custom control.
 	 *
 	 * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java
index 4a0a32d..a1c412e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java
@@ -28,11 +28,6 @@
  * it does not make sense to set a layout on it.
  * </p><p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
- * </p><p>
- * NOTE: The API in the browser package is NOT finalized.
- * Use at your own risk, because it will most certainly change.
- * The only reason this API is being released at this time is so that 
- * other teams can try it out.
  * </p>
  * 
  * @since 3.0
@@ -519,12 +514,38 @@
 	return ret;
 }
 
+/**
+ * Returns <code>true</code> if the receiver can navigate to the 
+ * previous session history item, and <code>false</code> otherwise.
+ *
+ * @return the receiver's back command enabled state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see #back
+ */
 public boolean isBackEnabled() {
 	checkWidget();
 	int webView = WebKit.HIWebViewGetWebView(webViewHandle);
 	return WebKit.objc_msgSend(webView, WebKit.S_canGoBack) != 0;
 }
 
+/**
+ * Returns <code>true</code> if the receiver can navigate to the 
+ * next session history item, and <code>false</code> otherwise.
+ *
+ * @return the receiver's forward command enabled state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see #forward
+ */
 public boolean isForwardEnabled() {
 	checkWidget();
 	int webView = WebKit.HIWebViewGetWebView(webViewHandle);
@@ -873,7 +894,7 @@
  * 
  * @param url the URL to be loaded
  *
- * @return true if the operation was successfull and false otherwise.
+ * @return true if the operation was successful and false otherwise.
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the url is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java
index 015a445..b0d28b5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java
@@ -28,11 +28,6 @@
  * it does not make sense to set a layout on it.
  * </p><p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
- * </p><p>
- * NOTE: The API in the browser package is NOT finalized.
- * Use at your own risk, because it will most certainly change.
- * The only reason this API is being released at this time is so that 
- * other teams can try it out.
  * </p>
  * 
  * @since 3.0
@@ -786,6 +781,19 @@
 	return dest != null ? new String(dest) : ""; //$NON-NLS-1$
 }
 
+/**
+ * Returns <code>true</code> if the receiver can navigate to the 
+ * previous session history item, and <code>false</code> otherwise.
+ *
+ * @return the receiver's back command enabled state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see #back
+ */
 public boolean isBackEnabled() {
 	checkWidget();
 	int[] result = new int[1];
@@ -801,6 +809,19 @@
 	return aCanGoBack[0];
 }
 
+/**
+ * Returns <code>true</code> if the receiver can navigate to the 
+ * next session history item, and <code>false</code> otherwise.
+ *
+ * @return the receiver's forward command enabled state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see #forward
+ */
 public boolean isForwardEnabled() {
 	checkWidget();
 	int[] result = new int[1];
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java
index 0d14c21..70906fa 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java
@@ -27,11 +27,6 @@
  * it does not make sense to set a layout on it.
  * </p><p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
- * </p><p>
- * NOTE: The API in the browser package is NOT finalized.
- * Use at your own risk, because it will most certainly change.
- * The only reason this API is being released at this time is so that 
- * other teams can try it out.
  * </p>
  * 
  * @since 3.0
@@ -459,6 +454,19 @@
 	return url;
 }
 
+/**
+ * Returns <code>true</code> if the receiver can navigate to the 
+ * previous session history item, and <code>false</code> otherwise.
+ *
+ * @return the receiver's back command enabled state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see #back
+ */
 public boolean isBackEnabled() {
 	checkWidget();
 	int ptr = OS.malloc(4);
@@ -471,6 +479,19 @@
 	return (result[0] & (1 << OS.Pt_WEB_DIRECTION_BACK)) != 0;
 }
 
+/**
+ * Returns <code>true</code> if the receiver can navigate to the 
+ * next session history item, and <code>false</code> otherwise.
+ *
+ * @return the receiver's forward command enabled state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see #forward
+ */
 public boolean isForwardEnabled() {
 	checkWidget();
 	int ptr = OS.malloc(4);
@@ -1040,7 +1061,7 @@
  * 
  * @param url the URL to be loaded
  *
- * @return true if the operation was successfull and false otherwise.
+ * @return true if the operation was successful and false otherwise.
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the url is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Clipboard.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Clipboard.java
index 5197e4e..75096af 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Clipboard.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Clipboard.java
@@ -239,7 +239,7 @@
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if data is null or datatypes is null 
  *          or the length of data is not the same as the length of dataTypes</li>
- * </ul>
+ *   </ul>
  *  @exception SWTError <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java
index 7a095c4..1e78e09 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java
@@ -40,12 +40,12 @@
 	public byte[][] data;
 	
 	/**
-	 * The result field contains the result of converting a java data type
-	 * into a platform specific value.
+	 * The result field contains the result of converting a
+	 * java data type into a platform specific value.
 	 * (Warning: This field is platform dependent)
 	 * 
- 	 * <p>The value of result is 0 if the conversion was successfully.  The value of 
-	 * result is an error code if the conversion failed.</p>
+ 	 * <p>The value of result is 1 if the conversion was successful.
+	 * The value of result is 0 if the conversion failed.</p>
 	 */
 	public int result;
 	
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 7155f19..4b7acc0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -57,7 +57,7 @@
  * 			// write data to a byte array and then ask super to convert to pMedium
  * 			ByteArrayOutputStream out = new ByteArrayOutputStream();
  * 			DataOutputStream writeOut = new DataOutputStream(out);
- * 			for (int i = 0, length = myTypes.length; i < length;  i++){
+ * 			for (int i = 0, length = myTypes.length; i &lt length;  i++){
  * 				byte[] buffer = myTypes[i].fileName.getBytes();
  * 				writeOut.writeInt(buffer.length);
  * 				writeOut.write(buffer);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java
index 622f21b..feda288 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java
@@ -119,7 +119,7 @@
  *
  * @param formatName the name of a data type
  *
- * @return the unique identifier associated with htis data type
+ * @return the unique identifier associated with this data type
  */
 public static int registerType(String formatName){
 	return 0;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Clipboard.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Clipboard.java
index 9575781..f3c8689 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Clipboard.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Clipboard.java
@@ -261,7 +261,7 @@
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if data is null or datatypes is null 
  *          or the length of data is not the same as the length of dataTypes</li>
- * </ul>
+ *   </ul>
  *  @exception SWTError <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java
index d69f819..dbc80f3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java
@@ -122,7 +122,7 @@
  *
  * @param formatName the name of a data type
  *
- * @return the unique identifier associated with htis data type
+ * @return the unique identifier associated with this data type
  */
 public static int registerType(String formatName){
 	if (formatName == null) return OS.GDK_NONE;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java
index 726d12a..f10a703 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java
@@ -55,12 +55,12 @@
 	public int /*long*/ pValue;
 
 	/**
-	 * The result field contains the result of converting a java data type
-	 * into a platform specific value.
-	 * (Warning: This field is platform dependent).
+	 * The result field contains the result of converting a
+	 * java data type into a platform specific value.
+	 * (Warning: This field is platform dependent)
 	 * 
-	 * <p>The value of result is 1 if the conversion was successfully.  The value of 
-	 * result is 0 if the conversion failed.</p>
+ 	 * <p>The value of result is 1 if the conversion was successful.
+	 * The value of result is 0 if the conversion failed.</p>
 	 */
 	public int result;
 	
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Clipboard.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Clipboard.java
index ef5498b..21394f7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Clipboard.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Clipboard.java
@@ -274,7 +274,7 @@
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if data is null or datatypes is null 
  *          or the length of data is not the same as the length of dataTypes</li>
- * </ul>
+ *   </ul>
  *  @exception SWTError <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java
index ca8c618..1447cdc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java
@@ -123,7 +123,7 @@
  *
  * @param formatName the name of a data type
  *
- * @return the unique identifier associated with htis data type
+ * @return the unique identifier associated with this data type
  */
 public static int registerType(String formatName){
 	// Use default display because we don't have a particular widget
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java
index 79617e5..99d28d8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java
@@ -55,12 +55,12 @@
 	public int pValue;
 
 	/**
-	 * The result field contains the result of converting a java data type
-	 * into a platform specific value.
-	 * (Warning: This field is platform dependent).
+	 * The result field contains the result of converting a
+	 * java data type into a platform specific value.
+	 * (Warning: This field is platform dependent)
 	 * 
-	 * <p>The value of result is 1 if the conversion was successfully.  The value of 
-	 * result is 0 if the conversion failed.</p>
+ 	 * <p>The value of result is 1 if the conversion was successful.
+	 * The value of result is 0 if the conversion failed.</p>
 	 */
 	public int result;
 	
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 6f194e3..7a628f7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -59,7 +59,7 @@
  * 			// write data to a byte array and then ask super to convert to pMedium
  * 			ByteArrayOutputStream out = new ByteArrayOutputStream();
  * 			DataOutputStream writeOut = new DataOutputStream(out);
- * 			for (int i = 0, length = myTypes.length; i < length;  i++){
+ * 			for (int i = 0, length = myTypes.length; i &lt length;  i++){
  * 				byte[] buffer = myTypes[i].fileName.getBytes();
  * 				writeOut.writeInt(buffer.length);
  * 				writeOut.write(buffer);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java
index 248a81b..93d6e68 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Clipboard.java
@@ -247,7 +247,7 @@
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if data is null or datatypes is null 
  *          or the length of data is not the same as the length of dataTypes</li>
- * </ul>
+ *   </ul>
  *  @exception SWTError <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java
index 353d085..81bb84e 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java
@@ -118,7 +118,7 @@
  *
  * @param formatName the name of a data type
  *
- * @return the unique identifier associated with htis data type
+ * @return the unique identifier associated with this data type
  */
 public static int registerType(String formatName){
 	if (formatName == "TEXT") return 10;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java
index f43c255..26fb75f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java
@@ -46,12 +46,12 @@
 	public int length;
 	
 	/**
-	 * The result field contains the result of converting a java data type
-	 * into a platform specific value.
+	 * The result field contains the result of converting a
+	 * java data type into a platform specific value.
 	 * (Warning: This field is platform dependent)
 	 * 
- 	 * <p>The value of result is 1 if the conversion was successfully.  The value of 
-	 * result is 0 if the conversion failed.</p>
+ 	 * <p>The value of result is 1 if the conversion was successful.
+	 * The value of result is 0 if the conversion failed.</p>
 	 */
 	public int result;
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/TransferData.java
index 38f6a91..6b96566 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/TransferData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/TransferData.java
@@ -49,9 +49,12 @@
 	public STGMEDIUM stgmedium;
 
 	/**
-	 * The result field contains the result of converting a java data type into a
-	 * stgmedium value.
+	 * The result field contains the result of converting a
+	 * java data type into a platform specific value.
 	 * (Warning: This field is platform dependent)
+	 * 
+ 	 * <p>The value of result is 1 if the conversion was successful.
+	 * The value of result is 0 if the conversion failed.</p>
 	 */
 	public int result = COM.E_FAIL;
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java
index eb2ef52..73a57ea 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java
@@ -213,7 +213,7 @@
  * <dd>Print the current selection</dd>
  * </dl>
  *
- * @param int the scope setting when the dialog is opened
+ * @param scope the scope setting when the dialog is opened
  */
 public void setScope(int scope) {
 	this.scope = scope;
@@ -241,7 +241,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the startPage setting when the dialog is opened
+ * @param startPage the startPage setting when the dialog is opened
  */
 public void setStartPage(int startPage) {
 	this.startPage = startPage;
@@ -269,7 +269,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the end page setting when the dialog is opened
+ * @param endPage the end page setting when the dialog is opened
  */
 public void setEndPage(int endPage) {
 	this.endPage = endPage;
@@ -289,7 +289,7 @@
  * Sets the 'Print to file' setting that the user will see
  * when the dialog is opened.
  *
- * @param boolean the 'Print to file' setting when the dialog is opened
+ * @param printToFile the 'Print to file' setting when the dialog is opened
  */
 public void setPrintToFile(boolean printToFile) {
 	this.printToFile = printToFile;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
index 7002163..204268b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
@@ -157,11 +157,11 @@
  * You must dispose the printer when it is no longer required. 
  * </p>
  *
- * @exception IllegalArgumentException <ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer() {
 	this(null);
@@ -178,10 +178,12 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the specified printer data does not represent a valid printer
+ * </ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer(PrinterData data) {
 	super (checkNull(data));
@@ -204,6 +206,10 @@
  * is usually used by passing in the client area (the 'printable
  * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
@@ -222,20 +228,10 @@
 	return new Rectangle(x+(int)paperRect.left, y+(int)paperRect.top, width+(int)(paperRect.right-pageRect.right), height+(int)(paperRect.bottom-pageRect.bottom));
 }
 
-/**
- * Creates the device in the operating system.  If the device
- * does not have a handle, this method may do nothing depending
- * on the device.
- * <p>
- * This method is called before <code>init</code>.
- * </p><p>
- * Subclasses are supposed to reimplement this method and not
- * call the <code>super</code> implementation.
- * </p>
- *
- * @param data the DeviceData which describes the receiver
- *
- * @see #init
+/**	 
+ * Creates the printer handle.
+ * This method is called internally by the instance creation
+ * mechanism of the <code>Device</code> class.
  */
 protected void create(DeviceData deviceData) {
 	data = (PrinterData)deviceData;
@@ -350,13 +346,18 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC(int context, GCData data) {
 	if (data != null) isGCCreated = false;
 }
 
+/**	 
+ * Releases any internal state prior to destroying this printer.
+ * This method is called internally by the dispose
+ * mechanism of the <code>Device</code> class.
+ */
 protected void release () {
 	if (colorspace != 0) OS.CGColorSpaceRelease(colorspace);
 	colorspace = 0;
@@ -373,6 +374,7 @@
  * will result in undefined behavior.
  * </p>
  * 
+ * @param jobName the name of the print job to start
  * @return true if the job started successfully and false otherwise.
  *
  * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java
index 06d3239..cb468c8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java
@@ -128,7 +128,7 @@
  * <dd>Print the current selection</dd>
  * </dl>
  *
- * @param int the scope setting when the dialog is opened
+ * @param scope the scope setting when the dialog is opened
  */
 public void setScope(int scope) {
 	this.scope = scope;
@@ -154,7 +154,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the startPage setting when the dialog is opened
+ * @param startPage the startPage setting when the dialog is opened
  */
 public void setStartPage(int startPage) {
 	this.startPage = startPage;
@@ -180,7 +180,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the end page setting when the dialog is opened
+ * @param endPage the end page setting when the dialog is opened
  */
 public void setEndPage(int endPage) {
 	this.endPage = endPage;
@@ -198,7 +198,7 @@
  * Sets the 'Print to file' setting that the user will see
  * when the dialog is opened.
  *
- * @param boolean the 'Print to file' setting when the dialog is opened
+ * @param printToFile the 'Print to file' setting when the dialog is opened
  */
 public void setPrintToFile(boolean printToFile) {
 	this.printToFile = printToFile;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java
index 989250d..83d8294 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java
@@ -67,11 +67,11 @@
  * You must dispose the printer when it is no longer required. 
  * </p>
  *
- * @exception IllegalArgumentException <ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer() {
 	this(getDefaultPrinterData());
@@ -88,10 +88,12 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the specified printer data does not represent a valid printer
+ * </ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer(PrinterData data) {
 	super (data);
@@ -126,7 +128,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC(int /*long*/ xGC, GCData data) {
@@ -142,6 +144,7 @@
  * will result in undefined behavior.
  * </p>
  * 
+ * @param jobName the name of the print job to start
  * @return true if the job started successfully and false otherwise.
  *
  * @exception SWTException <ul>
@@ -284,6 +287,10 @@
  * is usually used by passing in the client area (the 'printable
  * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java
index 06d3239..cb468c8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java
@@ -128,7 +128,7 @@
  * <dd>Print the current selection</dd>
  * </dl>
  *
- * @param int the scope setting when the dialog is opened
+ * @param scope the scope setting when the dialog is opened
  */
 public void setScope(int scope) {
 	this.scope = scope;
@@ -154,7 +154,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the startPage setting when the dialog is opened
+ * @param startPage the startPage setting when the dialog is opened
  */
 public void setStartPage(int startPage) {
 	this.startPage = startPage;
@@ -180,7 +180,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the end page setting when the dialog is opened
+ * @param endPage the end page setting when the dialog is opened
  */
 public void setEndPage(int endPage) {
 	this.endPage = endPage;
@@ -198,7 +198,7 @@
  * Sets the 'Print to file' setting that the user will see
  * when the dialog is opened.
  *
- * @param boolean the 'Print to file' setting when the dialog is opened
+ * @param printToFile the 'Print to file' setting when the dialog is opened
  */
 public void setPrintToFile(boolean printToFile) {
 	this.printToFile = printToFile;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
index 38e0bb8..7b636d7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
@@ -239,11 +239,11 @@
  * You must dispose the printer when it is no longer required. 
  * </p>
  *
- * @exception IllegalArgumentException <ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer() {
 	this(null);
@@ -260,10 +260,12 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the specified printer data does not represent a valid printer
+ * </ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer(PrinterData data) {
 	super(checkNull(data));
@@ -398,7 +400,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC(int xGC, GCData data) {
@@ -416,6 +418,7 @@
  * will result in undefined behavior.
  * </p>
  * 
+ * @param jobName the name of the print job to start
  * @return true if the job started successfully and false otherwise.
  *
  * @exception SWTException <ul>
@@ -608,6 +611,10 @@
  * is usually used by passing in the client area (the 'printable
  * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java
index 06d3239..cb468c8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java
@@ -128,7 +128,7 @@
  * <dd>Print the current selection</dd>
  * </dl>
  *
- * @param int the scope setting when the dialog is opened
+ * @param scope the scope setting when the dialog is opened
  */
 public void setScope(int scope) {
 	this.scope = scope;
@@ -154,7 +154,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the startPage setting when the dialog is opened
+ * @param startPage the startPage setting when the dialog is opened
  */
 public void setStartPage(int startPage) {
 	this.startPage = startPage;
@@ -180,7 +180,7 @@
  * <code>PAGE_RANGE</code>.
  * </p>
  * 
- * @param int the end page setting when the dialog is opened
+ * @param endPage the end page setting when the dialog is opened
  */
 public void setEndPage(int endPage) {
 	this.endPage = endPage;
@@ -198,7 +198,7 @@
  * Sets the 'Print to file' setting that the user will see
  * when the dialog is opened.
  *
- * @param boolean the 'Print to file' setting when the dialog is opened
+ * @param printToFile the 'Print to file' setting when the dialog is opened
  */
 public void setPrintToFile(boolean printToFile) {
 	this.printToFile = printToFile;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java
index 12f755f..726d0d7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java
@@ -68,11 +68,11 @@
  * You must dispose the printer when it is no longer required. 
  * </p>
  *
- * @exception IllegalArgumentException <ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer() {
 	this(getDefaultPrinterData());
@@ -89,10 +89,12 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the specified printer data does not represent a valid printer
+ * </ul>
+ * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if there are no valid printers
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  */
 public Printer(PrinterData data) {
 	super (data);
@@ -127,7 +129,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC(int xGC, GCData data) {
@@ -143,6 +145,7 @@
  * will result in undefined behavior.
  * </p>
  * 
+ * @param jobName the name of the print job to start
  * @return true if the job started successfully and false otherwise.
  *
  * @exception SWTException <ul>
@@ -285,6 +288,10 @@
  * is usually used by passing in the client area (the 'printable
  * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
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 c28fcde..78a3542 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
@@ -39,7 +39,9 @@
 
 /**
  * Finds the program that is associated with an extension.
- * The extension may or may not begin with a '.'.
+ * The extension may or may not begin with a '.'.  Note that
+ * a <code>Display</code> must already exist to guarantee that
+ * this method returns an appropriate result.
  *
  * @param extension the program extension
  * @return the program or <code>null</code>
@@ -70,7 +72,9 @@
 }
 
 /**
- * Answer all program extensions in the operating system.
+ * Answer all program extensions in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of extensions
  */
@@ -146,7 +150,9 @@
 }
 
 /**
- * Answers all available programs in the operating system.
+ * Answers all available programs in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of programs
  */
@@ -190,7 +196,9 @@
 /**
  * Launches the executable associated with the file in
  * the operating system.  If the file is an executable,
- * then the executable is launched.
+ * then the executable is launched.  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
  * @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 0d5f73a..633f031 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
@@ -65,7 +65,9 @@
 
 /**
  * Finds the program that is associated with an extension.
- * The extension may or may not begin with a '.'.
+ * The extension may or may not begin with a '.'.  Note that
+ * a <code>Display</code> must already exist to guarantee that
+ * this method returns an appropriate result.
  *
  * @param extension the program extension
  * @return the program or <code>null</code>
@@ -112,7 +114,9 @@
 }
 
 /**
- * Answer all program extensions in the operating system.
+ * Answer all program extensions in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of extensions
  */
@@ -152,7 +156,9 @@
 }
 
 /**
- * Answers all available programs in the operating system.
+ * Answers all available programs in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of programs
  */
@@ -313,7 +319,9 @@
 /**
  * Launches the executable associated with the file in
  * the operating system.  If the file is an executable,
- * then the executable is launched.
+ * then the executable is launched.  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
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
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 f4a758d..af31594 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
@@ -187,7 +187,9 @@
 
 /**
  * Finds the program that is associated with an extension.
- * The extension may or may not begin with a '.'.
+ * The extension may or may not begin with a '.'.  Note that
+ * a <code>Display</code> must already exist to guarantee that
+ * this method returns an appropriate result.
  *
  * @param extension the program extension
  * @return the program or <code>null</code>
@@ -292,7 +294,9 @@
 }
 
 /**
- * Answer all program extensions in the operating system.
+ * Answer all program extensions in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of extensions
  */
@@ -334,7 +338,9 @@
 }
 
 /**
- * Answers all available programs in the operating system.
+ * Answers all available programs in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of programs
  */
@@ -598,7 +604,9 @@
 /**
  * Launches the executable associated with the file in
  * the operating system.  If the file is an executable,
- * then the executable is launched.
+ * then the executable is launched.  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
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
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 098adc8..1c9cd00 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
@@ -36,7 +36,9 @@
 
 /**
  * Finds the program that is associated with an extension.
- * The extension may or may not begin with a '.'.
+ * The extension may or may not begin with a '.'.  Note that
+ * a <code>Display</code> must already exist to guarantee that
+ * this method returns an appropriate result.
  *
  * @param extension the program extension
  * @return the program or <code>null</code>
@@ -75,7 +77,9 @@
 }
 
 /**
- * Answer all program extensions in the operating system.
+ * Answer all program extensions in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of extensions
  */
@@ -108,7 +112,9 @@
 }
 
 /**
- * Answers all available programs in the operating system.
+ * Answers all available programs in the operating system.  Note
+ * that a <code>Display</code> must already exist to guarantee
+ * that this method returns an appropriate result.
  *
  * @return an array of programs
  */
@@ -152,7 +158,9 @@
 /**
  * Launches the executable associated with the file in
  * the operating system.  If the file is an executable,
- * then the executable is launched.
+ * then the executable is launched.  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
  * @return <code>true</code> if the file is launched, otherwise <code>false</code>
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 961436e..ecdc91c 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
@@ -82,7 +82,7 @@
  * </p>
  *
  * @param device the device on which to allocate the color
- * @param RGB the RGB values of the desired color
+ * @param rgb the RGB values of the desired color
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -189,6 +189,8 @@
 /**
  * Returns an <code>RGB</code> representing the receiver.
  *
+ * @return the RGB for the color
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
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 9517cc9..119b58c 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
@@ -184,7 +184,7 @@
 /**	 
  * Constructs a new cursor given a device, image and mask
  * data describing the desired cursor appearance, and the x
- * and y co-ordinates of the <em>hotspot</em> (that is, the point
+ * and y coordinates of the <em>hotspot</em> (that is, the point
  * within the area covered by the cursor which is considered
  * to be where the on-screen pointer is "pointing").
  * <p>
@@ -312,6 +312,33 @@
 	OS.memcpy(handle, cursor, org.eclipse.swt.internal.carbon.Cursor.sizeof);
 }
 
+/**	 
+ * Constructs a new cursor given a device, image data describing
+ * the desired cursor appearance, and the x and y coordinates of
+ * the <em>hotspot</em> (that is, the point within the area
+ * covered by the cursor which is considered to be where the
+ * on-screen pointer is "pointing").
+ * <p>
+ * You must dispose the cursor when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the cursor
+ * @param source the image data for the cursor
+ * @param hotspotX the x coordinate of the cursor's hotspot
+ * @param hotspotY the y coordinate of the cursor's hotspot
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the hotspot is outside the bounds of the
+ * 		 image</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java
index 28b6b76..cd9d886 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java
@@ -319,7 +319,7 @@
  * <code>faceName</code> is null, all fonts will be returned.
  *
  * @param faceName the name of the font to look for, or null
- * @param scalable true if scalable fonts should be returned.
+ * @param scalable if true only scalable fonts are returned, otherwise only non-scalable fonts are returned.
  * @return the matching font data
  *
  * @exception SWTException <ul>
@@ -507,7 +507,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public abstract void internal_dispose_GC (int handle, GCData data);
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 154aafa..9316042 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
@@ -30,7 +30,7 @@
 public final class Font {
 
 	/**
-	 * the handle to the OS font resource (a FMFont)
+	 * the handle to the OS font resource
 	 * (Warning: This field is platform dependent)
 	 */
 	public int handle;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java
index 6bcee77..ab689b9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java
@@ -15,7 +15,6 @@
 
 /**
  * Instances of this class describe operating system fonts.
- * Only the public API of this type is platform independent.
  * <p>
  * For platform-independent behaviour, use the get and set methods
  * corresponding to the following properties:
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 0af1da2..ea85766 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
@@ -18,6 +18,17 @@
  * Class <code>GC</code> is where all of the drawing capabilities that are 
  * supported by SWT are located. Instances are used to draw on either an 
  * <code>Image</code>, a <code>Control</code>, or directly on a <code>Display</code>.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
+ * </dl>
+ * 
+ * <p>
+ * The SWT drawing coordinate system is the two-dimensional space with the origin
+ * (0,0) at the top left corner of the drawing area and with (x,y) values increasing
+ * to the right and downward respectively.
+ * </p>
+ * 
  * <p>
  * Application code must explicitly invoke the <code>GC.dispose()</code> 
  * method to release the operating system resources managed by each instance
@@ -25,6 +36,10 @@
  * important on Windows95 and Windows98 where the operating system has a limited
  * number of device contexts available.
  * </p>
+ * 
+ * <p>
+ * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
+ * </p>
  *
  * @see org.eclipse.swt.events.PaintEvent
  */
@@ -68,6 +83,32 @@
 	this(drawable, 0);
 }
 
+/**	 
+ * Constructs a new instance of this class which has been
+ * configured to draw on the specified drawable. Sets the
+ * foreground and background color in the GC to match those
+ * in the drawable.
+ * <p>
+ * You must dispose the graphics context when it is no longer required. 
+ * </p>
+ * 
+ * @param drawable the drawable to draw on
+ * @param style the style of GC to construct
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the drawable is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if there is no current device</li>
+ *    <li>ERROR_INVALID_ARGUMENT
+ *          - if the drawable is an image that is not a bitmap or an icon
+ *          - if the drawable is an image or printer that is already selected
+ *            into another graphics context</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li>
+ * </ul>
+ *  
+ * @since 2.1.2
+ */
 public GC(Drawable drawable, int style) {
 	if (drawable == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	GCData data = new GCData();
@@ -113,6 +154,7 @@
  * Copies a rectangular area of the receiver at the specified
  * position into the image, which must be of type <code>SWT.BITMAP</code>.
  *
+ * @param image the image to copy into
  * @param x the x coordinate in the receiver of the area to be copied
  * @param y the y coordinate in the receiver of the area to be copied
  *
@@ -338,9 +380,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -577,6 +616,23 @@
 	flush();
 }
 
+/** 
+ * Draws a pixel, using the foreground color, at the specified
+ * point (<code>x</code>, <code>y</code>).
+ * <p>
+ * Note that the receiver's line attributes do not affect this
+ * operation.
+ * </p>
+ *
+ * @param x the point's x coordinate
+ * @param y the point's y coordinate
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *  
+ * @since 3.0
+ */
 public void drawPoint(int x, int y) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (data.updateClip) setCGClipping();
@@ -993,9 +1049,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -1193,7 +1246,7 @@
  * Fills the interior of the specified rectangle, using the receiver's
  * background color. 
  *
- * @param rectangle the rectangle to be filled
+ * @param rect the rectangle to be filled
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
@@ -1498,6 +1551,24 @@
 	return data.lineWidth;
 }
 
+/**
+ * Returns the receiver's style information.
+ * <p>
+ * Note that the value which is returned by this method <em>may
+ * not match</em> the value which was provided to the constructor
+ * when the receiver was created. This can occur when the underlying
+ * operating system does not support a particular combination of
+ * requested styles. 
+ * </p>
+ *
+ * @return the style bits
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *   
+ * @since 2.1.2
+ */
 public int getStyle () {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.style;
@@ -1668,7 +1739,7 @@
  * by drawing operations to the region specified
  * by the argument.
  *
- * @param rect the clipping region.
+ * @param region the clipping region.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
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 8e35e3c..238394e 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
@@ -71,7 +71,7 @@
 	public int type;
 	
 	/**
-	 * The handle to the OS image resource.
+	 * the handle to the OS image resource
 	 * (Warning: This field is platform dependent)
 	 */
 	public int handle;
@@ -182,6 +182,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon, or
  *          is otherwise in an invalid state</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the Image is not supported</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -348,6 +349,9 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li>
+ * </ul>
  */
 public Image(Device device, ImageData data) {
 	if (device == null) device = Device.getDevice();
@@ -425,6 +429,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -456,6 +461,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -860,7 +866,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int context, GCData data) {
@@ -892,7 +898,7 @@
  * these cases. For example:
  * <pre>
  *    Button b = new Button();
- *    image.setBackground(b.getBackground());>
+ *    image.setBackground(b.getBackground());
  *    b.setImage(image);
  * </pre>
  * </p><p>
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 a45db2a9..a637502 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
@@ -47,6 +47,25 @@
 	this(null);
 }
 
+/**
+ * Constructs a new empty region.
+ * <p>
+ * You must dispose the region when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the region
+ *
+* @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ *
+ * @see #dispose
+ * 
+ * @since 3.0
+ */
 public Region(Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -249,6 +268,22 @@
 }
 
 
+/**
+ * Intersects the given rectangle to the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to intersect with the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect(Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -261,6 +296,23 @@
 	OS.DisposeRgn(rectRgn);
 }
 
+/**
+ * Intersects all of the rectangles which make up the area covered
+ * by the argument to the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to intersect
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect(Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -348,7 +400,7 @@
  * Subtracts the given polygon from the collection of rectangles
  * the receiver maintains to describe its area.
  *
- * param pointArray points that describe the polygon to merge with the receiver
+ * @param pointArray points that describe the polygon to merge with the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
@@ -375,6 +427,22 @@
 	OS.DisposeRgn(polyRgn);
 }
 
+/**
+ * Subtracts the given rectangle from the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to subtract from the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract(Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -387,6 +455,23 @@
 	OS.DisposeRgn(rectRgn);
 }
 
+/**
+ * Subtracts all of the rectangles which make up the area covered
+ * by the argument from the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to subtract
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract(Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
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 0a1d471..a9af2b6 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
@@ -14,6 +14,23 @@
 import org.eclipse.swt.internal.carbon.*;
 import org.eclipse.swt.*;
 
+/**
+ * <code>TextLayout</code> is a graphic object that represents
+ * styled text.
+ *<p>
+ * Instances of this class provide support for drawing, cursor
+ * navigation, hit testing, text wrapping, alignment, tab expansion
+ * line breaking, etc.  These are aspects required for rendering internationalized text.
+ * </p>
+ * 
+ * <p>
+ * Application code must explicitly invoke the <code>TextLayout#dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ *  @since 3.0
+ */
 public final class TextLayout {
 	
 	static class StyleItem {
@@ -102,6 +119,20 @@
 
 	static final int TAB_COUNT = 32;
 	
+/**	 
+ * Constructs a new instance of this class on the given device.
+ * <p>
+ * You must dispose the text layout when it is no longer required. 
+ * </p>
+ * 
+ * @param device the device on which to allocate the text layout
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public TextLayout (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -196,6 +227,10 @@
 	}
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the text layout. Applications must dispose of all allocated text layouts.
+ */
 public void dispose() {
 	if (layout == 0) return;
 	freeRuns();
@@ -211,10 +246,38 @@
 	device = null;
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw(GC gc, int x, int y) {
 	draw(gc, x, y, -1, -1, null, null);
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param selectionStart the offset where the selections starts, or -1 indicating no selection
+ * @param selectionEnd the offset where the selections ends, or -1 indicating no selection
+ * @param selectionForeground selection foreground, or NULL to use the system default color
+ * @param selectionBackground selection background, or NULL to use the system default color
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) {
 	checkLayout ();
 	computeRuns();
@@ -315,6 +378,17 @@
 	breaks = lineX = lineWidth = lineHeight = lineAscent = null;
 }
 
+/** 
+ * Returns the receiver's horizontal text alignment, which will be one
+ * of <code>SWT.LEFT</code>, <code>SWT.CENTER</code> or
+ * <code>SWT.RIGHT</code>.
+ *
+ * @return the alignment used to positioned text horizontally
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getAlignment() {
 	checkLayout();
 	int[] buffer = new int[1];
@@ -326,11 +400,32 @@
 	return SWT.LEFT;
 }
 
+/**
+ * Returns the ascent of the receiver.
+ *
+ * @return the ascent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ *  @see #getDescent()
+ * 
+ */
 public int getAscent () {
 	checkLayout();	
 	return ascent;
 }
 
+/**
+ * Returns the bounds of the receiver.
+ * 
+ * @return the bounds of the receiver
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds() {
 	checkLayout();
 	computeRuns();
@@ -346,6 +441,20 @@
 	return new Rectangle(0, 0, width, height);
 }
 
+/**
+ * Returns the bounds for the specified range of characters. The
+ * bounds is the smallest rectangle that encompasses all characters
+ * in the range. The start and end offsets are inclusive and will be
+ * clamped if out of range.
+ * 
+ * @param start the start offset
+ * @param end the end offset
+ * @return the bounds of the character range
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds(int start, int end) {
 	checkLayout();
 	computeRuns();
@@ -379,16 +488,51 @@
 	return new Rectangle(rect.left, rect.top, rect.right - rect.left, rect.bottom - rect.top);
 }
 
+/**
+ * Returns the descent of the receiver.
+ *
+ * @return the descent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAscent()
+ */
 public int getDescent () {
 	checkLayout();	
 	return descent;
 }
 
+/** 
+ * Returns the default font currently being used by the receiver
+ * to draw and measure text.
+ *
+ * @return the receiver's font
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Font getFont () {
 	checkLayout();
 	return font;
 }
 
+/**
+ * Returns the embedding level for the specified character offset. The
+ * embedding level is usually used to determine the directionality of a
+ * character in bidirectional text.
+ * 
+ * @param offset the charecter offset
+ * @return the embedding level
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ */
 public int getLevel(int offset) {
 	checkLayout();
 	computeRuns();
@@ -399,6 +543,17 @@
 	return level;
 }
 
+/**
+ * Returns the line offsets.  Each value in the array is the
+ * offset for the first character in a line except for the last
+ * value, which contains the length of the text.
+ * 
+ * @return the line offsets
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getLineOffsets() {
 	checkLayout ();
 	computeRuns();
@@ -407,6 +562,20 @@
 	return offsets;
 }
 
+/**
+ * Returns the index of the line that contains the specified
+ * character offset.
+ * 
+ * @param offset the character offset
+ * @return the line index
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineIndex(int offset) {
 	checkLayout ();
 	computeRuns();
@@ -419,6 +588,19 @@
 	return breaks.length - 1;
 }
 
+/**
+ * Returns the bounds of the line for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the line bounds 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getLineBounds(int lineIndex) {
 	checkLayout();
 	computeRuns();
@@ -433,12 +615,35 @@
 	return new Rectangle(lineX[lineIndex], lineY, lineWidth[lineIndex], lineHeight[lineIndex]);
 }
 
+/**
+ * Returns the receiver's line count. This includes lines caused
+ * by wrapping.
+ *
+ * @return the line count
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineCount() {
 	checkLayout ();
 	computeRuns();
 	return breaks.length;
 }
 
+/**
+ * Returns the font metrics for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the font metrics 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public FontMetrics getLineMetrics (int lineIndex) {
 	checkLayout ();
 	computeRuns();
@@ -462,6 +667,22 @@
 	return FontMetrics.carbon_new(OS.Fix2Long(ascent[0]), OS.Fix2Long(descent[0]), 0, 0, height);
 }
 
+/**
+ * Returns the location for the specified character offset. The
+ * <code>trailing</code> argument indicates whether the offset
+ * corresponds to the leading or trailing edge of the cluster.
+ * 
+ * @param offset the character offset
+ * @param trailing the trailing flag
+ * @return the location of the character offset
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getOffset(Point, int[])
+ * @see #getOffset(int, int, int[])
+ */
 public Point getLocation(int offset, boolean trailing) {
 	checkLayout();
 	computeRuns();
@@ -480,6 +701,24 @@
 	return new Point(Math.min(OS.Fix2Long(caret.fX), OS.Fix2Long(caret.fDeltaX)), lineY);
 }
 
+/**
+ * Returns the next offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the next offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getPreviousOffset(int, int)
+ */
 public int getNextOffset (int offset, int movement) {
 	return _getOffset(offset, movement, true);
 }
@@ -514,6 +753,25 @@
 	return newOffset[0];
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param point the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset(Point point, int[] trailing) {
 	checkLayout();
 	computeRuns();
@@ -521,6 +779,26 @@
 	return getOffset(point.x, point.y, trailing);
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param x the x coordinate of the point
+ * @param y the y coordinate of the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset(int x, int y, int[] trailing) {
 	checkLayout();
 	computeRuns();
@@ -543,6 +821,15 @@
 	return offset[0];
 }
 
+/**
+ * Returns the orientation of the receiver.
+ *
+ * @return the orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getOrientation() {
 	checkLayout();
 	int[] lineDir = new int[1];
@@ -550,20 +837,66 @@
 	return lineDir[0] == OS.kATSURightToLeftBaseDirection ? SWT.RIGHT_TO_LEFT : SWT.LEFT_TO_RIGHT;
 }
 
+/**
+ * Returns the previous offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the previous offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getNextOffset(int, int)
+ */
 public int getPreviousOffset (int index, int movement) {
 	return _getOffset(index, movement, false);
 }
 
+/**
+ * Returns the text segments offsets of the receiver.
+ *
+ * @return the text segments offsets
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getSegments() {
 	checkLayout();
 	return segments;
 }
 
+/**
+ * Returns the line spacing of the receiver.
+ *
+ * @return the line spacing
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getSpacing () {
 	checkLayout();	
 	return spacing;
 }
 
+/**
+ * Gets the style of the receiver at the specified offset.
+ *
+ * @param offset the text offset
+ * @return the style or <code>null</code> if not set
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public TextStyle getStyle (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -577,16 +910,44 @@
 	return null;
 }
 
+/**
+ * Returns the tab list of the receiver.
+ *
+ * @return the tab list
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getTabs() {
 	checkLayout();
 	return tabs;
 }
 
+/**
+ * Gets the receiver's text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's text
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public String getText () {
 	checkLayout ();
 	return text;
 }
 
+/**
+ * Returns the width of the receiver.
+ *
+ * @return the width
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getWidth () {
 	checkLayout ();
 	int[] buffer = new int[1];
@@ -595,10 +956,38 @@
 	return wrapWidth == 0 ? -1 : wrapWidth;
 }
 
+/**
+ * Returns <code>true</code> if the text layout has been disposed,
+ * and <code>false</code> otherwise.
+ * <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.
+ *
+ * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
+ */
 public boolean isDisposed () {
 	return layout == 0;
 }
 
+/**
+ * Sets the text alignment for the receiver. The alignment controls
+ * how a line of text is positioned horizontally. The argument should
+ * be one of <code>SWT.LEFT</code>, <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>.
+ * <p>
+ * The default alignment is <code>SWT.LEFT</code>.  Note that the receiver's
+ * width must be set in order to use <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>
+ * alignment.
+ *</p>
+ *
+ * @param alignment the new alignment 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setWidth(int)
+ */
 public void setAlignment (int alignment) {
 	checkLayout();
 	int mask = SWT.LEFT | SWT.CENTER | SWT.RIGHT;
@@ -616,6 +1005,23 @@
 	setLayoutControl(OS.kATSULineFlushFactorTag, align, 4);
 }
 
+/**
+ * Sets the ascent of the receiver. The ascent is distance in pixels
+ * from the baseline to the top of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * ascent is calculated from the line fonts.
+ *
+ * @param ascent the new ascent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the ascent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setDescent(int)
+ */
 public void setAscent (int ascent) {
 	checkLayout ();
 	if (ascent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -624,6 +1030,23 @@
 	this.ascent = ascent;
 }
 
+/**
+ * Sets the descent of the receiver. The descent is distance in pixels
+ * from the baseline to the bottom of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * descent is calculated from the line fonts.
+ *
+ * @param descent the new descent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the descent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAscent(int)
+ */
 public void setDescent (int descent) {
 	checkLayout ();
 	if (descent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -644,6 +1067,22 @@
 	OS.DisposePtr(ptr1);
 }
 
+/** 
+ * Sets the default font which will be used by the receiver
+ * to draw and measure text. If the
+ * argument is null, then a default font appropriate
+ * for the platform will be used instead. Note that a text
+ * style can override the default font.
+ *
+ * @param font the new font for the receiver, or null to indicate a default font
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setFont (Font font) {
 	checkLayout ();
 	if (font != null && font.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -653,6 +1092,17 @@
 	this.font = font;
 }
 
+/**
+ * Sets the orientation of the receiver, which must be one
+ * of <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
+ * <p>
+ *
+ * @param orientation new orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setOrientation(int orientation) {
 	checkLayout();
 	int mask = SWT.RIGHT_TO_LEFT | SWT.LEFT_TO_RIGHT;
@@ -666,6 +1116,23 @@
 	setLayoutControl(OS.kATSULineDirectionTag, lineDir, 1);
 }
 
+/**
+ * Sets the offsets of the receiver's text segments. Text segments are used to
+ * override the default behaviour of the bidirectional algorithm.
+ * Bidirectional reordering can happen within a text segment but not 
+ * between two adjacent segments.
+ * Each text segment is determined by two consecutive offsets in the 
+ * <code>segments</code> arrays. The first element of the array should 
+ * always be zero and the last one should always be equals to length of
+ * the text.
+ * <p>
+ * 
+ * @param segments the text segments offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSegments(int[] segments) {
 	checkLayout();
 	if (this.segments == null && segments == null) return;
@@ -682,6 +1149,19 @@
 	this.segments = segments;
 }
 
+/**
+ * Sets the line spacing of the receiver.  The line spacing
+ * is the space left between lines.
+ *
+ * @param spacing the new line spacing 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the spacing is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSpacing (int spacing) {
 	checkLayout();
 	if (spacing < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -689,6 +1169,19 @@
 	this.spacing = spacing;
 }
 
+/**
+ * Sets the style of the receiver for the specified range.  Styles previously
+ * set for that range will be overwritten.  The start and end offsets are
+ * inclusive and will be clamped if out of range.
+ * 
+ * @param style the style
+ * @param start the start offset
+ * @param end the end offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setStyle (TextStyle style, int start, int end) {
 	checkLayout();
 	int length = text.length();
@@ -752,6 +1245,17 @@
 	}
 }
 
+/**
+ * Sets the receiver's tab list. Each value in the tab list specifies
+ * the space in pixels from the origin of the text layout to the respective
+ * tab stop.  The last tab stop width is repeated continuously.
+ * 
+ * @param tabs the new tab list
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setTabs(int[] tabs) {
 	checkLayout();
 	if (this.tabs == null && tabs == null) return;
@@ -792,6 +1296,18 @@
 	}
 }
 
+/**
+ * Sets the receiver's text.
+ *
+ * @param text the new text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the text is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setText (String text) {
 	checkLayout ();
 	if (text == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -813,6 +1329,22 @@
 	styles[styles.length - 1].start = text.length();
 }
 
+/**
+ * Sets the line width of the receiver, which determines how
+ * text should be wrapped and aligned. The default value is
+ * <code>-1</code> which means wrapping is disabled.
+ *
+ * @param width the new width 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the width is <code>0</code> or less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlignment(int)
+ */
 public void setWidth (int width) {
 	checkLayout ();
 	if (width < -1 || width == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
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 f9682de..3144842 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
@@ -397,7 +397,8 @@
 
 /**
  * Returns the receiver's text, which will be an empty
- * string if it has never been set.
+ * string if it has never been set or if the receiver is
+ * an <code>ARROW</code> button.
  *
  * @return the receiver's text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java
index 5911ac0..5d04ce9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java
@@ -381,7 +381,7 @@
  * to the image specified by the argument, or to the default
  * which is a filled rectangle if the argument is null
  *
- * @param font the new font (or null)
+ * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
@@ -458,7 +458,6 @@
  * Sets the receiver's size to the point specified by the argument.
  *
  * @param size the new extent for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java
index b0e9499..270fab3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java
@@ -35,7 +35,7 @@
 /**
  * Constructs a new instance of this class given only its parent.
  *
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a composite control which will be the parent of the new instance
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -152,7 +152,7 @@
  * Sets the receiver's selected color to be the argument.
  *
  * @param rgb the new RGB value for the selected color, may be
- *        null to let the platform to select a default when
+ *        null to let the platform select a default when
  *        open() is called
  * @see PaletteData#getRGBs
  */
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 91105a7..4d5e7b0 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
@@ -699,7 +699,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -873,6 +873,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to begin the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1247,6 +1248,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1282,6 +1284,9 @@
  *
  * @param items the array of items
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the items array 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>
@@ -1316,10 +1321,10 @@
 
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1338,7 +1343,7 @@
  * start of the selection and whose y coordinate is the end
  * of the selection. 
  *
- * @param a point representing the new selection start and end
+ * @param selection a point representing the new selection start and end
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -1370,7 +1375,7 @@
  * display incorrectly.
  * </p>
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
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 48ecfa7..2a574ac 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
@@ -21,7 +21,7 @@
  * of containing other controls.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
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 ca5d3f6..5f95509 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
@@ -31,7 +31,7 @@
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>FocusIn, FocusOut, Help, KeyDown, KeyUp, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
  * </dl>
  * <p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -39,8 +39,6 @@
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
- * 
- * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
  */
 public abstract class Control extends Widget implements Drawable {
 	/**
@@ -652,7 +650,9 @@
 
 /**
  * Returns a rectangle describing the receiver's size and location
- * relative to its parent (or its display if its parent is null).
+ * relative to its parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the location is
+ * relative to the display.
  *
  * @return the receiver's bounding rectangle
  *
@@ -741,7 +741,9 @@
 
 /**
  * Returns a point describing the receiver's location relative
- * to its parent (or its display if its parent is null).
+ * to its parent (or its display if its parent is null), unless
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @return the receiver's location
  *
@@ -776,6 +778,13 @@
 	return menu;
 }
 
+/**
+ * Returns the receiver's monitor.
+ * 
+ * @return the receiver's monitor
+ * 
+ * @since 3.0
+ */
 public Monitor getMonitor () {
 	checkWidget();
 	Monitor [] monitors = display.getMonitors ();
@@ -1109,7 +1118,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int context, GCData data) {
@@ -1486,7 +1495,7 @@
  * the top of the drawing order will not be covered by other
  * controls even if they occupy intersecting areas.
  *
- * @param the sibling control (or null)
+ * @param control the sibling control (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the control has been disposed</li> 
@@ -1495,6 +1504,8 @@
  *    <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 #moveBelow
  */
 public void moveAbove (Control control) {
 	checkWidget();
@@ -1512,7 +1523,7 @@
  * the bottom of the drawing order will be covered by all other
  * controls which occupy intersecting areas.
  *
- * @param the sibling control (or null)
+ * @param control the sibling control (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the control has been disposed</li> 
@@ -1521,6 +1532,8 @@
  *    <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 #moveAbove
  */
 public void moveBelow (Control control) {
 	checkWidget();
@@ -1560,6 +1573,8 @@
  * manager caches can be retained. 
  * </p>
  *
+ * @param changed whether or not the receiver's contents have changed
+ * 
  * @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>
@@ -1575,7 +1590,8 @@
 /**
  * Causes the entire bounds of the receiver to be marked
  * as needing to be redrawn. The next time a paint request
- * is processed, the control will be completely painted.
+ * is processed, the control will be completely painted,
+ * including the background.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1583,6 +1599,11 @@
  * </ul>
  *
  * @see #update
+ * @see PaintListener
+ * @see SWT#Paint
+ * @see SWT#NO_BACKGROUND
+ * @see SWT#NO_REDRAW_RESIZE
+ * @see SWT#NO_MERGE_PAINTS
  */
 public void redraw () {
 	checkWidget();
@@ -1593,11 +1614,12 @@
  * Causes the rectangular area of the receiver specified by
  * the arguments to be marked as needing to be redrawn. 
  * The next time a paint request is processed, that area of
- * the receiver will be painted. If the <code>all</code> flag
- * is <code>true</code>, any children of the receiver which
- * intersect with the specified area will also paint their
- * intersecting areas. If the <code>all</code> flag is 
- * <code>false</code>, the children will not be painted.
+ * the receiver will be painted, including the background.
+ * If the <code>all</code> flag is <code>true</code>, any
+ * children of the receiver which intersect with the specified
+ * area will also paint their intersecting areas. If the
+ * <code>all</code> flag is <code>false</code>, the children
+ * will not be painted.
  *
  * @param x the x coordinate of the area to draw
  * @param y the y coordinate of the area to draw
@@ -1611,6 +1633,11 @@
  * </ul>
  *
  * @see #update
+ * @see PaintListener
+ * @see SWT#Paint
+ * @see SWT#NO_BACKGROUND
+ * @see SWT#NO_REDRAW_RESIZE
+ * @see SWT#NO_MERGE_PAINTS
  */
 public void redraw (int x, int y, int width, int height, boolean all) {
 	checkWidget ();
@@ -2031,7 +2058,9 @@
  * Sets the receiver's size and location to the rectangular
  * area specified by the arguments. The <code>x</code> and 
  * <code>y</code> arguments are relative to the receiver's
- * parent (or its display if its parent is null).
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the <code>x</code>
+ * and <code>y</code> arguments are relative to the display.
  * <p>
  * Note: Attempting to set the width or height of the
  * receiver to a negative number will cause that
@@ -2198,7 +2227,8 @@
 
 /**
  * Causes the receiver to have the <em>keyboard focus</em>, 
- * such that all keyboard events will be delivered to it.
+ * such that all keyboard events will be delivered to it.  Focus
+ * reassignment will respect applicable platform constraints.
  *
  * @return <code>true</code> if the control got focus, and <code>false</code> if it was unable to.
  *
@@ -2312,7 +2342,9 @@
 /**
  * Sets the receiver's location to the point specified by
  * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null).
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @param x the new x coordinate for the receiver
  * @param y the new y coordinate for the receiver
@@ -2329,8 +2361,10 @@
 
 /**
  * Sets the receiver's location to the point specified by
- * the argument which is relative to the receiver's
- * parent (or its display if its parent is null).
+ * the arguments which are relative to the receiver's
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @param location the new location for the receiver
  *
@@ -2471,7 +2505,6 @@
  * </p>
  *
  * @param size the new size for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -2900,6 +2933,8 @@
  * </ul>
  *
  * @see #redraw
+ * @see PaintListener
+ * @see SWT#Paint
  */
 public void update () {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java
index 2cbf013..368acba 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java
@@ -23,6 +23,11 @@
  * shares a significant amount of code with this class,
  * and is a subclass.
  * <p>
+ * IMPORTANT: This class was intended to be abstract and
+ * should <em>never</em> be referenced or instantiated.
+ * Instead, the class <code>Shell</code> should be used.
+ * </p>
+ * <p>
  * Instances are always displayed in one of the maximized, 
  * minimized or normal states:
  * <ul>
@@ -210,6 +215,33 @@
 	return image;
 }
 
+/**
+ * Returns the receiver's images if they had previously been 
+ * set using <code>setImages()</code>. Images are typically
+ * displayed by the window manager when the instance is
+ * marked as iconified, and may also be displayed somewhere
+ * in the trim when the instance is in normal or maximized
+ * states. Depending where the icon is displayed, the platform
+ * chooses the icon with the "best" size. It is expected that
+ * the array will contain the same icon rendered at different
+ * resolutions.
+ * 
+ * <p>
+ * Note: This method will return an empty array if called before
+ * <code>setImages()</code> is called. It does not provide
+ * access to a window manager provided, "default" image
+ * even if one exists.
+ * </p>
+ * 
+ * @return the images
+ *
+ * @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 Image [] getImages () {
 	checkWidget();
 	return images;
@@ -353,7 +385,7 @@
  * disposed, the receiver's default button will be set to
  * null. 
  *
- * @param the new default button
+ * @param button the new default button
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the button has been disposed</li> 
@@ -413,6 +445,29 @@
 	this.image = image;
 }
 
+/**
+ * Sets the receiver's images to the argument, which may
+ * be an empty array. Images are typically displayed by the
+ * window manager when the instance is marked as iconified,
+ * and may also be displayed somewhere in the trim when the
+ * instance is in normal or maximized states. Depending where
+ * the icon is displayed, the platform chooses the icon with
+ * the "best" size. It is expected that the array will contain
+ * the same icon rendered at different resolutions.
+ * 
+ * @param images the new image array
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of images is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the images 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.0
+ */
 public void setImages (Image [] images) {
 	checkWidget();
 	if (images == null) error(SWT.ERROR_INVALID_ARGUMENT);
@@ -436,7 +491,7 @@
  * always. This should be avoided if possible.
  * </p>
  *
- * @param the new maximized state
+ * @param maximized the new maximized state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -490,7 +545,7 @@
  * always. This should be avoided if possible.
  * </p>
  *
- * @param the new maximized state
+ * @param minimized the new maximized state
  *
  * @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/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java
index 8f78623..98073ea 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -18,6 +18,12 @@
 /**
  * Instances of this class allow the user to navigate
  * the file system and select a directory.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>(none)</dd>
+ * </dl>
  * <p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
@@ -27,16 +33,7 @@
 	String message = "", filterPath = "";
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -64,15 +61,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
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 740f700..059caac 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
@@ -96,7 +96,7 @@
  * @see #wake
  * @see #readAndDispatch
  * @see #sleep
- * @see #dispose
+ * @see Device#dispose
  */
 public class Display extends Device {
 	
@@ -364,6 +364,29 @@
 	return OS.eventNotHandledErr;
 }
 
+/**
+ * Adds the listener to the collection of listeners who will
+ * be notifed when an event of the given type occurs anywhere
+ * in this display. When the event does occur, the listener is
+ * notified by sending it the <code>handleEvent()</code> message.
+ *
+ * @param eventType the type of event to listen for
+ * @param listener the listener which should be notified when the event occurs
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Listener
+ * @see #removeFilter
+ * @see #removeListener
+ * 
+ * @since 3.0 
+ */
 public void addFilter (int eventType, Listener listener) {
 	checkDevice ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -765,7 +788,7 @@
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  * 
  * @since 2.0
  */
@@ -962,6 +985,16 @@
 	return null;
 }
 
+/**
+ * Returns a rectangle describing the receiver's size and location.
+ *
+ * @return the bounding rectangle
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds () {
 	checkDevice ();
 	int gdevice = OS.GetDeviceList();
@@ -991,6 +1024,19 @@
 	return OS.GetCaretTime () * 1000 / 60;
 }
 
+/**
+ * Returns a rectangle which describes the area of the
+ * receiver which is capable of displaying data.
+ * 
+ * @return the client area
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getBounds
+ */
 public Rectangle getClientArea () {
 	checkDevice ();
 	int gdevice = OS.GetDeviceList();
@@ -1072,6 +1118,18 @@
 	return new Point (pt.h, pt.v);
 }
 
+/**
+ * Returns an array containing the recommended cursor sizes.
+ *
+ * @return the array of cursor sizes
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Point [] getCursorSizes () {
 	checkDevice ();
 	return new Point [] {new Point (16, 16)};
@@ -1226,6 +1284,23 @@
 	return null;
 }
 
+/**
+ * Returns true when the high contrast mode is enabled.
+ * Otherwise, false is returned.
+ * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
+ *
+ * @return the high contrast mode
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public boolean getHighContrast () {
 	checkDevice ();
 	return false;
@@ -1247,6 +1322,20 @@
 	return getDepth ();
 }
 
+/**
+ * Returns an array containing the recommended icon sizes.
+ *
+ * @return the array of icon sizes
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Decorations#setImages(Image[])
+ * 
+ * @since 3.0
+ */
 public Point [] getIconSizes () {
 	checkDevice ();
 	return new Point [] { 
@@ -1473,6 +1562,48 @@
 	return Color.carbon_new (this, new float[]{red, green, blue, 1});
 }
 
+/**
+ * Returns the matching standard platform cursor for the given
+ * constant, which should be one of the cursor constants
+ * specified in class <code>SWT</code>. This cursor should
+ * not be free'd because it was allocated by the system,
+ * not the application.  A value of <code>null</code> will
+ * be returned if the supplied constant is not an swt cursor
+ * constant. 
+ *
+ * @param id the swt cursor constant
+ * @return the corresponding cursor or <code>null</code>
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see SWT#CURSOR_ARROW
+ * @see SWT#CURSOR_WAIT
+ * @see SWT#CURSOR_CROSS
+ * @see SWT#CURSOR_APPSTARTING
+ * @see SWT#CURSOR_HELP
+ * @see SWT#CURSOR_SIZEALL
+ * @see SWT#CURSOR_SIZENESW
+ * @see SWT#CURSOR_SIZENS
+ * @see SWT#CURSOR_SIZENWSE
+ * @see SWT#CURSOR_SIZEWE
+ * @see SWT#CURSOR_SIZEN
+ * @see SWT#CURSOR_SIZES
+ * @see SWT#CURSOR_SIZEE
+ * @see SWT#CURSOR_SIZEW
+ * @see SWT#CURSOR_SIZENE
+ * @see SWT#CURSOR_SIZESE
+ * @see SWT#CURSOR_SIZESW
+ * @see SWT#CURSOR_SIZENW
+ * @see SWT#CURSOR_UPARROW
+ * @see SWT#CURSOR_IBEAM
+ * @see SWT#CURSOR_NO
+ * @see SWT#CURSOR_HAND
+ * 
+ * @since 3.0
+ */
 public Cursor getSystemCursor (int id) {
 	checkDevice ();
 	if (!(0 <= id && id < cursors.length)) return null;
@@ -1482,6 +1613,32 @@
 	return cursors [id];
 }
 
+/**
+ * Returns the matching standard platform image for the given
+ * constant, which should be one of the icon constants
+ * specified in class <code>SWT</code>. This image should
+ * not be free'd because it was allocated by the system,
+ * not the application.  A value of <code>null</code> will
+ * be returned either if the supplied constant is not an
+ * swt icon constant or if the platform does not define an
+ * image that corresponds to the constant. 
+ *
+ * @param id the swt icon constant
+ * @return the corresponding image or <code>null</code>
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see SWT#ICON_ERROR
+ * @see SWT#ICON_INFORMATION
+ * @see SWT#ICON_QUESTION
+ * @see SWT#ICON_WARNING
+ * @see SWT#ICON_WORKING
+ * 
+ * @since 3.0
+ */
 public Image getSystemImage (int id) {
 	int cgImage = 0;
 	int imageData = 0;
@@ -1526,6 +1683,17 @@
 	return Image.carbon_new (this, SWT.ICON, cgImage, imageData);
 }
 
+/**
+ * Returns the single instance of the system tray.
+ *
+ * @return the receiver's user-interface thread
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.0
+ */
 public Tray getSystemTray () {
 	checkDevice ();
 	if (tray != null) return tray;
@@ -1773,7 +1941,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int context, GCData data) {
@@ -1837,6 +2005,54 @@
 	return OS.eventNotHandledErr;
 }
 
+/**
+ * Generate a low level system event.
+ * 
+ * <code>post</code> is used to generate low level keyboard
+ * and mouse events. The intent is to enable automated UI
+ * testing by simulating the input from the user.  Most
+ * SWT applications should never need to call this method.
+ * 
+ * <p>
+ * <b>Event Types:</b>
+ * <p>KeyDown, KeyUp
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type KeyDown or KeyUp</li>
+ * <p> Either one of:
+ * <li>(in) character a character that corresponds to a keyboard key</li>
+ * <li>(in) keyCode the key code of the key that was typed,
+ *          as defined by the key code constants in class <code>SWT</code></li>
+ * </ul>
+ * <p>MouseDown, MouseUp</p>
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type MouseDown or MouseUp
+ * <li>(in) button the button that is pressed or released
+ * </ul>
+ * <p>MouseMove</p>
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type MouseMove
+ * <li>(in) x the x coordinate to move the mouse pointer to in screen coordinates
+ * <li>(in) y the y coordinate to move the mouse pointer to in screen coordinates
+ * </ul>
+ * </dl>
+ * 
+ * @param event the event to be generated
+ * 
+ * @return true if the event was generated or false otherwise
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the event is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.0
+ * 
+ */
 public boolean post(Event event) {
 	if (isDisposed ()) error (SWT.ERROR_DEVICE_DISPOSED);
 	if (event == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1948,12 +2164,84 @@
 	eventQueue [index] = event;
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param point to be mapped 
+ * @return point with mapped coordinates 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Point map (Control from, Control to, Point point) {
 	checkDevice ();
 	if (point == null) error (SWT.ERROR_NULL_ARGUMENT);	
 	return map (from, to, point.x, point.y);
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param x coordinates to be mapped
+ * @param y coordinates to be mapped
+ * @return point with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Point map (Control from, Control to, int x, int y) {
 	checkDevice ();
 	if (from != null && from.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -1982,12 +2270,86 @@
 	return point;
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param rectangle to be mapped
+ * @return rectangle with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Rectangle map (Control from, Control to, Rectangle rectangle) {
 	checkDevice ();
 	if (rectangle == null) error (SWT.ERROR_NULL_ARGUMENT);	
 	return map (from, to, rectangle.x, rectangle.y, rectangle.width, rectangle.height);
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param x coordinates to be mapped
+ * @param y coordinates to be mapped
+ * @param width coordinates to be mapped
+ * @param height coordinates to be mapped
+ * @return rectangle with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Rectangle map (Control from, Control to, int x, int y, int width, int height) {
 	checkDevice ();
 	if (from != null && from.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -2285,6 +2647,27 @@
 
 }
 
+/**
+ * Removes the listener from the collection of listeners who will
+ * be notifed when an event of the given type occurs anywhere in
+ * this display.
+ *
+ * @param eventType the type of event to listen for
+ * @param listener the listener which should no longer be notified when the event occurs
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @see Listener
+ * @see #addFilter
+ * @see #addListener
+ * 
+ * @since 3.0
+ */
 public void removeFilter (int eventType, Listener listener) {
 	checkDevice ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java
index 53c1e02..bf90c0b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java
@@ -35,16 +35,7 @@
 	String filterPath = "", fileName = "";
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -72,15 +63,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java
index 452ebfc..1605f53 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java
@@ -21,6 +21,12 @@
 /**
  * Instances of this class allow the user to select a font
  * from all available fonts in the system.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>(none)</dd>
+ * </dl>
  * <p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
@@ -32,16 +38,7 @@
 	boolean open;
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -69,15 +66,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java
index 2e01292..9e2aaf1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java
@@ -421,8 +421,8 @@
 }
 
 /**
- * Returns the zero-relative index of the item which is currently
- * has the focus in the receiver, or -1 if no item is has focus.
+ * Returns the zero-relative index of the item which currently
+ * has the focus in the receiver, or -1 if no item has focus.
  *
  * @return the index of the selected item
  *
@@ -833,6 +833,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to start the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1062,11 +1063,16 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the index was already selected, it remains
- * selected. The range of the indices is inclusive. Indices that are
- * out of range are ignored and no items will be selected if start is
- * greater than end.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If an item in the given range is not selected, it is selected.
+ * If an item in the given range was already selected, it remains selected.
+ * Indices that are out of range are ignored and no items will be selected
+ * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start of the range
  * @param end the end of the range
@@ -1075,6 +1081,8 @@
  *    <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 List#setSelection(int,int)
  */
 public void select (int start, int end) {
 	checkWidget ();
@@ -1090,20 +1098,25 @@
 
 /**
  * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the given zero-relative index in the receiver 
- * is not selected, it is selected.  If the item at the index
- * was selected, it remains selected. Indices that are out
- * of range and duplicate indices are ignored.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If the item at a given index is not selected, it is selected.
+ * If the item at a given index was already selected, it remains selected.
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the array of indices for the items to select
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of indices 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>
+ * 
+ * @see List#setSelection(int[])
  */
 public void select (int [] indices) {
 	checkWidget ();
@@ -1158,7 +1171,9 @@
 }
 
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1278,10 +1293,14 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is cleared before the new items are selected.
+ * <p>
  * Indices that are out of range are ignored and no items will be selected
  * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start index of the items to select
  * @param end the end index of the items to select
@@ -1291,8 +1310,8 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see Table#deselectAll()
- * @see Table#select(int,int)
+ * @see List#deselectAll()
+ * @see List#select(int,int)
  */
 public void setSelection (int start, int end) {
 	checkWidget ();
@@ -1309,13 +1328,17 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items at the given zero-relative indices in the receiver.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the indices of the items to select
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of indices is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1347,13 +1370,16 @@
 
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of items is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1361,7 +1387,8 @@
  * </ul>
  *
  * @see List#deselectAll()
- * @see List#select(int)
+ * @see List#select(int[])
+ * @see List#setSelection(int[])
  */
 public void setSelection (String [] items) {
 	checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
index ddc3056..4a236fb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
@@ -117,7 +117,7 @@
  * for the instance so that the instance will be a drop-down
  * menu on the given parent's parent.
  *
- * @param parent a menu which will be the parent of the new instance (cannot be null)
+ * @param parentMenu a menu which will be the parent of the new instance (cannot be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -141,7 +141,7 @@
  * for the instance so that the instance will be a drop-down
  * menu on the given parent's parent menu.
  *
- * @param parent a menu item which will be the parent of the new instance (cannot be null)
+ * @param parentItem a menu item which will be the parent of the new instance (cannot be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
index 7cca4f8..6f8b7e1 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
@@ -593,7 +593,7 @@
  * Note: This feature is not available on all window systems (for example, Window NT),
  * in which case, calling this method will silently do nothing.
  *
- * @param menu the image to display
+ * @param image the image to display
  *
  * @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/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java
index 39a4523..05d7b72 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java
@@ -39,16 +39,7 @@
 	
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -75,16 +66,9 @@
  * of those <code>SWT</code> style constants. The class description
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
- * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java
index 8082911..e643aef 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java
@@ -149,11 +149,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * 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
+ * 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 (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -170,11 +171,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value that the receiver will allow.  This new
+ * value will be ignored if it is negative or is not less 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 (must be zero or greater)
+ * @param value the new minimum, which must be nonnegative and less than 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/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java
index c0ab66e..010a7b6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java
@@ -248,7 +248,7 @@
  * are pressed to the argument, which must be at least 
  * one.
  *
- * @param value the new increment (must be greater than zero)
+ * @param increment the new increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -262,11 +262,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * 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
+ * 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 (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -283,11 +284,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value that the receiver will allow.  This new
+ * value will be ignored if it is negative or is not less 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 (must be zero or greater)
+ * @param value the new minimum, which must be nonnegative and less than the current maximum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -309,7 +311,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param pageIncrement the page increment (must be greater than zero)
  *
  * @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/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
index ea885ea..e421348 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
@@ -596,11 +596,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the maximum. If this value is negative or less than or
+ * equal to the minimum, the value is ignored. If necessary, first
+ * the thumb and then the selection are adjusted to fit within the
+ * new range.
  *
- * @param value the new maximum (must be zero or greater)
+ * @param value the new maximum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -621,11 +622,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value. If this value is negative or greater
+ * than or equal to the maximum, the value is ignored. If necessary,
+ * first the thumb and then the selection are adjusted to fit within
+ * the new range.
  *
- * @param value the new minimum (must be zero or greater)
+ * @param value the new minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -652,7 +654,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -670,7 +672,7 @@
  * value to the argument which must be greater than or equal
  * to zero.
  *
- * @param value the new selection (must be zero or greater)
+ * @param selection the new selection (must be zero or greater)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -684,17 +686,17 @@
 
 /**
  * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values to the
- * argument which must be at least one.
+ * difference between its maximum and minimum values.  This new
+ * value will be ignored if it is less than one, and will be
+ * clamped if it exceeds the receiver's current range.
  *
- * @param value the new thumb value (must be at least one)
+ * @param value the new thumb value, which must be at least one and not
+ * larger than the size of the current range
  *
  * @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 ScrollBar
  */
 public void setThumb (int value) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java
index 1f8fccb..2072d1f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java
@@ -87,6 +87,10 @@
  * receiver's parent).
  * </p>
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
index e3feb8b..287d80c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
@@ -378,6 +378,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
+ * @see SWT#Close
  * @see #dispose
  */
 public void close () {
@@ -625,9 +626,10 @@
 }
 
 /** 
- * Returns the region that defines the shape of the shell.
+ * Returns the region that defines the shape of the shell,
+ * or null if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell
+ * @return the region that defines the shape of the shell (or null)
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -983,8 +985,8 @@
  * the display on which it was created (so that all other
  * shells on that display, which are not the receiver's
  * children will be drawn behind it), marks it visible,
- * and sets focus to its default button (if it has one)
- * and asks the window manager to make the shell active.
+ * sets the focus and asks the window manager to make the
+ * shell active.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1196,11 +1198,16 @@
 
 /**
  * Sets the shape of the shell to the region specified
- * by the argument.  A null region will restore the default shape.
- * Shell must be created with the style SWT.NO_TRIM.
+ * by the argument.  When the argument is null, the
+ * default shape of the shell is restored.  The shell
+ * must be created with the style SWT.NO_TRIM in order
+ * to specify a region.
  *
- * @param rgn the region that defines the shape of the shell
- * 
+ * @param region the region that defines the shape of the shell (or null)
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the region 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>
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 788487b..6cec962 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
@@ -366,11 +366,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the maximum. If this value is negative or less than or
+ * equal to the minimum, the value is ignored. If necessary, first
+ * the thumb and then the selection are adjusted to fit within the
+ * new range.
  *
- * @param value the new maximum (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -391,11 +392,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value. If this value is negative or greater
+ * than or equal to the maximum, the value is ignored. If necessary,
+ * first the thumb and then the selection are adjusted to fit within
+ * the new range.
  *
- * @param value the new minimum (must be zero or greater)
+ * @param value the new minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -422,7 +424,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -454,17 +456,17 @@
 
 /**
  * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values to the
- * argument which must be at least one.
+ * difference between its maximum and minimum values.  This new
+ * value will be ignored if it is less than one, and will be
+ * clamped if it exceeds the receiver's current range.
  *
- * @param value the new thumb value (must be at least one)
+ * @param value the new thumb value, which must be at least one and not
+ * larger than the size of the current range
  *
  * @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 ScrollBar
  */
 public void setThumb (int value) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java
index 527ca6b..e33c12c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java
@@ -529,7 +529,7 @@
 /**
  * Selects the item at the given zero-relative index in the receiver. 
  * If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are
+ * The current selection is first cleared, then the new items are
  * selected. Indices that are out of range are ignored.
  *
  * @param index the index of the item to select
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java
index 8dbf4f6..dbdfcb7 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java
@@ -95,6 +95,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java
index 06278ab..8d069a4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java
@@ -204,6 +204,27 @@
 	if (!isValidSubclass ()) error (SWT.ERROR_INVALID_SUBCLASS);
 }
 
+/**
+ * Clears the item at the given zero-relative index in the receiver.
+ * The text, icon and other attribues of the item are set to the default
+ * value.  If the table was created with the SWT.VIRTUAL style, these
+ * attributes are requested again as needed.
+ *
+ * @param index the index of the item to clear
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT#SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int index) {
 	checkWidget();
 	if (!(0 <= index && index < itemCount)) error (SWT.ERROR_INVALID_RANGE);
@@ -219,6 +240,29 @@
 	}
 }
 
+/**
+ * Removes the items from the receiver which are between the given
+ * zero-relative start and end indices (inclusive).  The text, icon
+ * and other attribues of the items are set to their default values.
+ * If the table was created with the SWT.VIRTUAL style, these attributes
+ * are requested again as needed.
+ *
+ * @param start the start index of the item to clear
+ * @param end the end index of the item to clear
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if either the start or end are not between 0 and the number of elements in the list minus 1 (inclusive)</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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int start, int end) {
 	checkWidget();
 	if (start > end) return;
@@ -234,6 +278,28 @@
 	}
 }
 
+/**
+ * Clears the items at the given zero-relative indices in the receiver.
+ * The text, icon and other attribues of the items are set to their default
+ * values.  If the table was created with the SWT.VIRTUAL style, these
+ * attributes are requested again as needed.
+ *
+ * @param indices the array of indices of the items
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the indices array 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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int [] indices) {
 	checkWidget();
 	if (indices == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -248,6 +314,22 @@
 	}
 }
 
+/**
+ * Clears all the items in the receiver. The text, icon and other
+ * attribues of the items are set to their default values. If the
+ * table was created with the SWT.VIRTUAL style, these attributes
+ * are requested again as needed.
+ *
+ * @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 SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clearAll () {
 	checkWidget();
 	for (int i=0; i<itemCount; i++) {
@@ -892,6 +974,8 @@
 /**
  * Returns the width in pixels of a grid line.
  *
+ * @return the width of a grid line in pixels
+ * 
  * @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>
@@ -1641,7 +1725,7 @@
  * </ul>
  *
  * @see SelectionListener
- * @see #addSelectionListener
+ * @see #addSelectionListener(SelectionListener)
  */
 public void removeSelectionListener(SelectionListener listener) {
 	checkWidget ();
@@ -1680,11 +1764,16 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the index was already selected, it remains
- * selected. The range of the indices is inclusive. Indices that are
- * out of range are ignored and no items will be selected if start is
- * greater than end.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If an item in the given range is not selected, it is selected.
+ * If an item in the given range was already selected, it remains selected.
+ * Indices that are out of range are ignored and no items will be selected
+ * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start of the range
  * @param end the end of the range
@@ -1693,6 +1782,8 @@
  *    <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 Table#setSelection(int,int)
  */
 public void select (int start, int end) {
 	checkWidget ();
@@ -1713,10 +1804,13 @@
 
 /**
  * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the given zero-relative index in the receiver 
- * is not selected, it is selected.  If the item at the index
- * was selected, it remains selected. Indices that are out
- * of range and duplicate indices are ignored.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If the item at a given index is not selected, it is selected.
+ * If the item at a given index was already selected, it remains selected.
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the array of indices for the items to select
  *
@@ -1727,6 +1821,8 @@
  *    <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 Table#setSelection(int[])
  */
 public void select (int [] indices) {
 	checkWidget ();
@@ -1772,7 +1868,9 @@
 }
 
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1816,7 +1914,7 @@
  * it visible may not actually cause it to be displayed.
  * </p>
  *
- * @param visible the new visibility state
+ * @param show the new visibility state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1829,6 +1927,18 @@
 	OS.SetDataBrowserListViewHeaderBtnHeight (handle, (short)height);
 }
 
+/**
+ * Sets the number of items contained in the receiver.
+ *
+ * @param count the number of items
+ *
+ * @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 void setItemCount (int count) {
 	checkWidget ();
 	checkItems (true);
@@ -1878,7 +1988,7 @@
  * it visible may not actually cause it to be displayed.
  * </p>
  *
- * @param visible the new visibility state
+ * @param show the new visibility state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1976,10 +2086,14 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is cleared before the new items are selected.
+ * <p>
  * Indices that are out of range are ignored and no items will be selected
  * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  * 
  * @param start the start index of the items to select
  * @param end the end index of the items to select
@@ -2008,8 +2122,12 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selected is first cleared, then the new items are selected.
+ * Selects the items at the given zero-relative indices in the receiver.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the indices of the items to select
  *
@@ -2047,14 +2165,17 @@
 
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the item has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2062,7 +2183,8 @@
  * </ul>
  *
  * @see Table#deselectAll()
- * @see Table#select(int)
+ * @see Table#select(int[])
+ * @see Table#setSelection(int[])
  */
 public void setSelection (TableItem [] items) {
 	checkWidget ();
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 07a8287..2c9e9db 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
@@ -227,7 +227,7 @@
 /**
  * Returns <code>true</code> if the receiver is checked,
  * and false otherwise.  When the parent does not have
- * the <code>CHECK style, return false.
+ * the <code>CHECK</code> style, return false.
  *
  * @return the checked state of the checkbox
  *
@@ -771,7 +771,7 @@
 }
 
 /**
- * Sets the image indent.
+ * Sets the indent of the first column's image, expressed in terms of the image's width.
  *
  * @param indent the new indent
  *
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 73e5095..fbe7e6e 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
@@ -29,7 +29,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>CENTER, LEFT, MULTI, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
+ * <dd>CENTER, LEFT, MULTI, PASSWORD, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>DefaultSelection, Modify, Verify</dd>
  * </dl>
@@ -43,7 +43,16 @@
 	int txnObject, txnFrameID;
 	int textLimit = LIMIT;
 	char echoCharacter;
+	/**
+	* The maximum number of characters that can be entered
+	* into a text widget.
+	*/
 	public static final int LIMIT;
+	/**
+	* The delimiter used by multi-line text widgets.  When text
+	* is queried and from the widget, it will be delimited using
+	* this delimiter.
+	*/
 	public static final String DELIMITER;
 	static final char PASSWORD = '\245';
 
@@ -530,6 +539,8 @@
  * default action of the text widget when the user
  * double clicks.
  * </p>
+ * 
+ * @return whether or not double click is enabled
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -549,6 +560,8 @@
  * displayed when the user enters text or the
  * text is changed by the programmer.
  * </p>
+ * 
+ * @return the echo character
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -563,6 +576,8 @@
 /**
  * Gets the editable state.
  *
+ * @return whether or not the reciever is editable
+ * 
  * @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>
@@ -625,7 +640,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -733,7 +748,8 @@
 }
 
 /**
- * Gets a range of text.
+ * Gets a range of text.  Returns an empty string if the
+ * start of the range is greater than the end.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N-1 where N is
@@ -1310,10 +1326,10 @@
 
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1445,7 +1461,7 @@
  * SINGLE and the argument contains multiple lines of text, the result of this
  * operation is undefined and may vary from platform to platform.
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java
index b04567d..adca099 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java
@@ -74,8 +74,8 @@
  * @see SWT#HORIZONTAL
  * @see SWT#SHADOW_OUT
  * @see SWT#VERTICAL
- * @see Widget#checkSubclass
- * @see Widget#getStyle
+ * @see Widget#checkSubclass()
+ * @see Widget#getStyle()
  */
 public ToolBar (Composite parent, int style) {
 	super (parent, checkStyle (style));
@@ -233,7 +233,7 @@
 }
 
 /**
- * Returns an array of <code>TabItem</code>s which are the items
+ * Returns an array of <code>ToolItem</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/carbon/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java
index d7f73e7..0b14abf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java
@@ -904,8 +904,8 @@
  *
  * @param rectangles the bounds of the rectangles to be drawn
  *
-  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of rectangles is null</li>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the set of rectangles is null or contains a null rectangle</li>
  * </ul>
  * @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/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java
index 9d8f8c8..68253e0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java
@@ -554,7 +554,7 @@
 }
 
 /**
- * Returns the number of items contained in the receiver
+ * Returns the items contained in the receiver
  * that are direct item children of the receiver.  These
  * are the roots of the tree.
  * <p>
@@ -563,7 +563,7 @@
  * not affect the receiver. 
  * </p>
  *
- * @return the number of items
+ * @return the items
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1047,7 +1047,7 @@
  * will be inserted when dropped on the tree.
  * 
  * @param item the insert item.  Null will clear the insertion mark.
- * @param after true places the insert mark above 'item'. false places 
+ * @param before true places the insert mark above 'item'. false places 
  *	the insert mark below 'item'.
  *
  * @exception IllegalArgumentException <ul>
@@ -1066,7 +1066,9 @@
 }
 
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1143,14 +1145,17 @@
 
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the item has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</li>
  * </ul>
  * @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/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
index f3d64db..ad25823 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
@@ -570,7 +570,7 @@
  * Sets the grayed state of the receiver.
  * <p>
  *
- * @param checked the new grayed state
+ * @param grayed the new grayed state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java
index 2f88c39..3c2c1f6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java
@@ -27,7 +27,7 @@
  * </p><p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>(none)</dd>
+ * <dd>FLAT</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java
index 18ddd0f..b8db593 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java
@@ -515,7 +515,6 @@
  * Sets the receiver's ideal size to the point specified by the argument.
  *
  * @param size the new ideal size for the receiver
- * @param height the new ideal height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -571,7 +570,6 @@
  * </p>
  *
  * @param size the new size for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java
index 691057c..220f1e6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java
@@ -1005,7 +1005,7 @@
 /**
  * Selects the item at the given zero-relative index in the receiver. 
  * If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are
+ * The current selection is first cleared, then the new items are
  * selected. Indices that are out of range are ignored.
  *
  * @param index the index of the item to select
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java
index 0afc555..21cbd3a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabItem.java
@@ -96,6 +96,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
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 133bd0f..27fd355 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
@@ -13,6 +13,23 @@
 import org.eclipse.swt.internal.*;
 import org.eclipse.swt.*;
 
+/**
+ * <code>TextLayout</code> is a graphic object that represents
+ * styled text.
+ *<p>
+ * Instances of this class provide support for drawing, cursor
+ * navigation, hit testing, text wrapping, alignment, tab expansion
+ * line breaking, etc.  These are aspects required for rendering internationalized text.
+ * </p>
+ * 
+ * <p>
+ * Application code must explicitly invoke the <code>TextLayout#dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ *  @since 3.0
+ */
 public final class TextLayout {
 	Device device;
 	Font font;
@@ -35,6 +52,20 @@
 		boolean lineBreak, softBreak, tab;
 	}
 	
+/**	 
+ * Constructs a new instance of this class on the given device.
+ * <p>
+ * You must dispose the text layout when it is no longer required. 
+ * </p>
+ * 
+ * @param device the device on which to allocate the text layout
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public TextLayout (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -207,6 +238,10 @@
 	if (newGC) gc.dispose();
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the text layout. Applications must dispose of all allocated text layouts.
+ */
 public void dispose () {
 	if (device == null) return;
 	freeRuns();
@@ -221,10 +256,38 @@
 	device = null;
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw (GC gc, int x, int y) {
 	draw(gc, x, y, -1, -1, null, null);
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param selectionStart the offset where the selections starts, or -1 indicating no selection
+ * @param selectionEnd the offset where the selections ends, or -1 indicating no selection
+ * @param selectionForeground selection foreground, or NULL to use the system default color
+ * @param selectionBackground selection background, or NULL to use the system default color
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw (GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) {
 	checkLayout();
 	if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -328,16 +391,48 @@
 	runs = null;
 }
 
+/** 
+ * Returns the receiver's horizontal text alignment, which will be one
+ * of <code>SWT.LEFT</code>, <code>SWT.CENTER</code> or
+ * <code>SWT.RIGHT</code>.
+ *
+ * @return the alignment used to positioned text horizontally
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getAlignment () {
 	checkLayout();
 	return alignment;
 }
 
+/**
+ * Returns the ascent of the receiver.
+ *
+ * @return the ascent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ *  @see #getDescent()
+ * 
+ */
 public int getAscent () {
 	checkLayout();
 	return ascent;
 }
 
+/**
+ * Returns the bounds of the receiver.
+ * 
+ * @return the bounds of the receiver
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds () {
 	checkLayout();
 	computeRuns(null);
@@ -353,6 +448,20 @@
 }
 
 
+/**
+ * Returns the bounds for the specified range of characters. The
+ * bounds is the smallest rectangle that encompasses all characters
+ * in the range. The start and end offsets are inclusive and will be
+ * clamped if out of range.
+ * 
+ * @param start the start offset
+ * @param end the end offset
+ * @return the bounds of the character range
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds (int start, int end) {
 	checkLayout();
 	int length = text.length();
@@ -378,16 +487,51 @@
 	return rect;
 }
 
+/**
+ * Returns the descent of the receiver.
+ *
+ * @return the descent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAscent()
+ */
 public int getDescent () {
 	checkLayout();
 	return descent;
 }
 
+/** 
+ * Returns the default font currently being used by the receiver
+ * to draw and measure text.
+ *
+ * @return the receiver's font
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Font getFont () {
 	checkLayout();
 	return font;
 }
 
+/**
+ * Returns the embedding level for the specified character offset. The
+ * embedding level is usually used to determine the directionality of a
+ * character in bidirectional text.
+ * 
+ * @param offset the charecter offset
+ * @return the embedding level
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ */
 public int getLevel (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -395,6 +539,17 @@
 	return 0;
 }
 
+/**
+ * Returns the line offsets.  Each value in the array is the
+ * offset for the first character in a line except for the last
+ * value, which contains the length of the text.
+ * 
+ * @return the line offsets
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getLineOffsets () {
 	checkLayout();
 	computeRuns(null);
@@ -403,6 +558,19 @@
 	return offsets;
 }
 
+/**
+ * Returns the bounds of the line for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the line bounds 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getLineBounds(int lineIndex) {
 	checkLayout();
 	computeRuns(null);
@@ -418,12 +586,36 @@
 	return new Rectangle (x, y, width, height);
 }
 
+/**
+ * Returns the receiver's line count. This includes lines caused
+ * by wrapping.
+ *
+ * @return the line count
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineCount () {
 	checkLayout();
 	computeRuns(null);
 	return runs.length;
 }
 
+/**
+ * Returns the index of the line that contains the specified
+ * character offset.
+ * 
+ * @param offset the character offset
+ * @return the line index
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineIndex (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -437,6 +629,19 @@
 	return runs.length - 1;
 }
 
+/**
+ * Returns the font metrics for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the font metrics 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public FontMetrics getLineMetrics (int lineIndex) {
 	checkLayout();
 	computeRuns(null);
@@ -468,6 +673,22 @@
 	return metrics;
 }
 
+/**
+ * Returns the location for the specified character offset. The
+ * <code>trailing</code> argument indicates whether the offset
+ * corresponds to the leading or trailing edge of the cluster.
+ * 
+ * @param offset the character offset
+ * @param trailing the trailing flag
+ * @return the location of the character offset
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getOffset(Point, int[])
+ * @see #getOffset(int, int, int[])
+ */
 public Point getLocation (int offset, boolean trailing) {
 	checkLayout();
 	int length = text.length();
@@ -524,6 +745,24 @@
 	return device.getSystemFont();
 }
 
+/**
+ * Returns the next offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the next offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getPreviousOffset(int, int)
+ */
 public int getNextOffset (int offset, int movement) {
 	checkLayout();
 	computeRuns(null);
@@ -550,12 +789,51 @@
 	return offset;
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param point the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset (Point point, int[] trailing) {
 	checkLayout();
 	if (point == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	return getOffset (point.x, point.y, trailing);
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param x the x coordinate of the point
+ * @param y the y coordinate of the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset (int x, int y, int[] trailing) {
 	checkLayout();
 	if (trailing != null && trailing.length < 1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -610,11 +888,38 @@
 	return lineOffset[line + 1];
 }
 
+/**
+ * Returns the orientation of the receiver.
+ *
+ * @return the orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getOrientation () {
 	checkLayout();
 	return orientation;
 }
 
+/**
+ * Returns the previous offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the previous offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getNextOffset(int, int)
+ */
 public int getPreviousOffset (int offset, int movement) {
 	checkLayout();
 	computeRuns(null);
@@ -642,16 +947,44 @@
 	return offset;
 }
 
+/**
+ * Returns the line spacing of the receiver.
+ *
+ * @return the line spacing
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getSpacing () {
 	checkLayout();	
 	return lineSpacing;
 }
 
+/**
+ * Returns the text segments offsets of the receiver.
+ *
+ * @return the text segments offsets
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getSegments() {
 	checkLayout();
 	return segments;
 }
 
+/**
+ * Gets the style of the receiver at the specified offset.
+ *
+ * @param offset the text offset
+ * @return the style or <code>null</code> if not set
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public TextStyle getStyle (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -665,21 +998,59 @@
 	return null;
 }
 
+/**
+ * Returns the tab list of the receiver.
+ *
+ * @return the tab list
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getTabs () {
 	checkLayout();
 	return tabs;
 }
 
+/**
+ * Gets the receiver's text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's text
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public String getText () {
 	checkLayout();
 	return text;
 }
 
+/**
+ * Returns the width of the receiver.
+ *
+ * @return the width
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getWidth () {
 	checkLayout();
 	return wrapWidth;
 }
 
+/**
+ * Returns <code>true</code> if the text layout has been disposed,
+ * and <code>false</code> otherwise.
+ * <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.
+ *
+ * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
+ */
 public boolean isDisposed () {
 	return device == null;
 }
@@ -768,6 +1139,24 @@
 	run.descent = metrics.getDescent();
 }
 
+/**
+ * Sets the text alignment for the receiver. The alignment controls
+ * how a line of text is positioned horizontally. The argument should
+ * be one of <code>SWT.LEFT</code>, <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>.
+ * <p>
+ * The default alignment is <code>SWT.LEFT</code>.  Note that the receiver's
+ * width must be set in order to use <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>
+ * alignment.
+ *</p>
+ *
+ * @param alignment the new alignment 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setWidth(int)
+ */
 public void setAlignment (int alignment) {
 	checkLayout();
 	int mask = SWT.LEFT | SWT.CENTER | SWT.RIGHT;
@@ -778,6 +1167,23 @@
 	this.alignment = alignment;
 }
 
+/**
+ * Sets the ascent of the receiver. The ascent is distance in pixels
+ * from the baseline to the top of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * ascent is calculated from the line fonts.
+ *
+ * @param ascent the new ascent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the ascent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setDescent(int)
+ */
 public void setAscent (int ascent) {
 	checkLayout();
 	if (ascent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -786,6 +1192,23 @@
 	this.ascent = ascent;
 }
 
+/**
+ * Sets the descent of the receiver. The descent is distance in pixels
+ * from the baseline to the bottom of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * descent is calculated from the line fonts.
+ *
+ * @param descent the new descent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the descent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAscent(int)
+ */
 public void setDescent (int descent) {
 	checkLayout();
 	if (descent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -794,6 +1217,22 @@
 	this.descent = descent;
 }
 
+/** 
+ * Sets the default font which will be used by the receiver
+ * to draw and measure text. If the
+ * argument is null, then a default font appropriate
+ * for the platform will be used instead. Note that a text
+ * style can override the default font.
+ *
+ * @param font the new font for the receiver, or null to indicate a default font
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setFont (Font font) {
 	checkLayout ();
 	if (font != null && font.isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -803,6 +1242,17 @@
 	this.font = font;
 }
 
+/**
+ * Sets the orientation of the receiver, which must be one
+ * of <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
+ * <p>
+ *
+ * @param orientation new orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setOrientation (int orientation) {
 	checkLayout();
 	int mask = SWT.RIGHT_TO_LEFT | SWT.LEFT_TO_RIGHT;
@@ -812,6 +1262,19 @@
 	this.orientation = orientation;
 }
 
+/**
+ * Sets the line spacing of the receiver.  The line spacing
+ * is the space left between lines.
+ *
+ * @param spacing the new line spacing 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the spacing is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSpacing (int spacing) {
 	checkLayout();
 	if (spacing < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -820,6 +1283,23 @@
 	this.lineSpacing = spacing;
 }
 
+/**
+ * Sets the offsets of the receiver's text segments. Text segments are used to
+ * override the default behaviour of the bidirectional algorithm.
+ * Bidirectional reordering can happen within a text segment but not 
+ * between two adjacent segments.
+ * Each text segment is determined by two consecutive offsets in the 
+ * <code>segments</code> arrays. The first element of the array should 
+ * always be zero and the last one should always be equals to length of
+ * the text.
+ * <p>
+ * 
+ * @param segments the text segments offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSegments(int[] segments) {
 	checkLayout();
 	if (this.segments == null && segments == null) return;
@@ -836,6 +1316,19 @@
 	this.segments = segments;
 }
 
+/**
+ * Sets the style of the receiver for the specified range.  Styles previously
+ * set for that range will be overwritten.  The start and end offsets are
+ * inclusive and will be clamped if out of range.
+ * 
+ * @param style the style
+ * @param start the start offset
+ * @param end the end offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setStyle (TextStyle style, int start, int end) {
 	checkLayout();
 	int length = text.length();
@@ -899,6 +1392,17 @@
 	}
 }
 
+/**
+ * Sets the receiver's tab list. Each value in the tab list specifies
+ * the space in pixels from the origin of the text layout to the respective
+ * tab stop.  The last tab stop width is repeated continuously.
+ * 
+ * @param tabs the new tab list
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setTabs (int[] tabs) {
 	checkLayout();
 	if (this.tabs == null && tabs == null) return;
@@ -915,6 +1419,18 @@
 	this.tabs = tabs;
 } 
 
+/**
+ * Sets the receiver's text.
+ *
+ * @param text the new text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the text is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setText (String text) {
 	checkLayout();
 	if (text == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -927,6 +1443,22 @@
 	styles[1].start = text.length();
 }
 
+/**
+ * Sets the line width of the receiver, which determines how
+ * text should be wrapped and aligned. The default value is
+ * <code>-1</code> which means wrapping is disabled.
+ *
+ * @param width the new width 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the width is <code>0</code> or less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlignment(int)
+ */
 public void setWidth (int width) {
 	checkLayout();
 	if (width < -1 || width == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java
index 70a2a7c..3421a5f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tray/org/eclipse/swt/widgets/TrayItem.java
@@ -15,27 +15,119 @@
 import org.eclipse.swt.events.*;
 import org.eclipse.swt.graphics.*;
 
+/**
+ * Instances of this class represent icons that can be placed on the
+ * system tray or task bar status area.
+ *
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>DefaultSelection, MenuDetect, Selection</dd>
+ * </dl>
+ * <p>
+ * IMPORTANT: This class is <em>not</em> intended to be subclassed.
+ * </p>
+ * 
+ * @since 3.0
+ */
 public class TrayItem extends Item {
 	Tray parent;
 	String toolTipText;
 	boolean visible = true;
 	
+/**
+ * Constructs a new instance of this class given its parent
+ * (which must be a <code>Tray</code>) and a style value
+ * describing its behavior and appearance. The item is added
+ * to the end of the items maintained by its parent.
+ * <p>
+ * The style value is either one of the style constants defined in
+ * class <code>SWT</code> which is applicable to instances of this
+ * class, or must be built by <em>bitwise OR</em>'ing together 
+ * (that is, using the <code>int</code> "|" operator) two or more
+ * of those <code>SWT</code> style constants. The class description
+ * lists the style constants that are applicable to the class.
+ * Style bits are also inherited from superclasses.
+ * </p>
+ *
+ * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param style the style of control to construct
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
+ * </ul>
+ *
+ * @see SWT
+ * @see Widget#checkSubclass
+ * @see Widget#getStyle
+ */
 public TrayItem (Tray parent, int style) {
 	super (parent, style);
 	this.parent = parent;
 	parent.createItem (this, parent.getItemCount ());
 }
 
+/**
+ * Adds the listener to the collection of listeners who will
+ * be notified when the receiver is selected, by sending
+ * it one of the messages defined in the <code>SelectionListener</code>
+ * interface.
+ * <p>
+ * <code>widgetSelected</code> is called when the receiver is selected
+ * <code>widgetDefaultSelected</code> is called when the receiver is double-clicked
+ * </p>
+ *
+ * @param listener the listener which should be notified
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener 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>
+ *
+ * @see SelectionListener
+ * @see #removeSelectionListener
+ * @see SelectionEvent
+ */
 public void addSelectionListener(SelectionListener listener) {
 	checkWidget ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
 }
 
+/**
+ * Returns the receiver's tool tip text, or null if it has
+ * not been set.
+ *
+ * @return the receiver's tool tip 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 getToolTipText () {
 	checkWidget ();
 	return toolTipText;
 }
 
+/**
+ * Returns <code>true</code> if the receiver is visible and 
+ * <code>false</code> otherwise.
+ *
+ * @return the receiver's visibility
+ *
+ * @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 boolean getVisible () {
 	checkWidget ();
 	return visible;
@@ -46,22 +138,74 @@
 	parent.destroyItem (this);
 }
 
+/**
+ * Removes the listener from the collection of listeners who will
+ * be notified when the receiver is selected.
+ *
+ * @param listener the listener which should no longer be notified
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener 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>
+ *
+ * @see SelectionListener
+ * @see #addSelectionListener
+ */
 public void removeSelectionListener (SelectionListener listener) {
 	checkWidget ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
 }
 
+/**
+ * Sets the receiver's image.
+ *
+ * @param image the new image
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the image 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 setImage (Image image) {
 	checkWidget ();
 	if (image != null && image.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT);
 	super.setImage (image);
 }
 
+/**
+ * Sets the receiver's tool tip text to the argument, which
+ * may be null indicating that no tool tip text should be shown.
+ *
+ * @param value the new tool tip text (or null)
+ *
+ * @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 setToolTipText (String string) {
 	checkWidget ();
 	toolTipText = string;
 }
 
+/**
+ * Makes the receiver visible if the argument is <code>true</code>,
+ * and makes it invisible otherwise. 
+ *
+ * @param visible the new visibility 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 void setVisible (boolean visible) {
 	checkWidget ();
 	if (this.visible == visible) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java
index 1d3d6c9..c76f749 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java
@@ -221,6 +221,27 @@
 protected void checkSubclass () {
 	if (!isValidSubclass ()) error (SWT.ERROR_INVALID_SUBCLASS);
 }
+/**
+ * Clears the item at the given zero-relative index in the receiver.
+ * The text, icon and other attribues of the item are set to the default
+ * value.  If the table was created with the SWT.VIRTUAL style, these
+ * attributes are requested again as needed.
+ *
+ * @param index the index of the item to clear
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT#SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int index) {
 	checkWidget ();
 	if (!(0 <= index && index < getItemCount())) {
@@ -231,6 +252,29 @@
 	int y = getRedrawY(item);
 	redraw(0, y, getClientArea().width, getItemHeight(), false);
 }
+/**
+ * Removes the items from the receiver which are between the given
+ * zero-relative start and end indices (inclusive).  The text, icon
+ * and other attribues of the items are set to their default values.
+ * If the table was created with the SWT.VIRTUAL style, these attributes
+ * are requested again as needed.
+ *
+ * @param start the start index of the item to clear
+ * @param end the end index of the item to clear
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if either the start or end are not between 0 and the number of elements in the list minus 1 (inclusive)</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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int start, int end) {
 	checkWidget ();
 	if (start > end) return;
@@ -245,6 +289,28 @@
 		}
 	}
 }
+/**
+ * Clears the items at the given zero-relative indices in the receiver.
+ * The text, icon and other attribues of the items are set to their default
+ * values.  If the table was created with the SWT.VIRTUAL style, these
+ * attributes are requested again as needed.
+ *
+ * @param indices the array of indices of the items
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the indices array 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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int [] indices) {
 	checkWidget ();
 	if (indices == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -258,6 +324,22 @@
 		clear(indices [i]);
 	}
 }
+/**
+ * Clears all the items in the receiver. The text, icon and other
+ * attribues of the items are set to their default values. If the
+ * table was created with the SWT.VIRTUAL style, these attributes
+ * are requested again as needed.
+ *
+ * @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 SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clearAll () {
 	checkWidget ();
 	for (int i=0; i<getItemCount(); i++) {
@@ -798,6 +880,8 @@
 /**
  * Returns the width in pixels of a grid line.
  *
+ * @return the width of a grid line in pixels
+ * 
  * @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>
@@ -2149,7 +2233,7 @@
  * </ul>
  *
  * @see SelectionListener
- * @see #addSelectionListener
+ * @see #addSelectionListener(SelectionListener)
  */
 public void removeSelectionListener(SelectionListener listener) {
 	checkWidget();
@@ -2313,10 +2397,13 @@
 }
 /**
  * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the given zero-relative index in the receiver 
- * is not selected, it is selected.  If the item at the index
- * was selected, it remains selected. Indices that are out
- * of range and duplicate indices are ignored.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If the item at a given index is not selected, it is selected.
+ * If the item at a given index was already selected, it remains selected.
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the array of indices for the items to select
  *
@@ -2327,6 +2414,8 @@
  *    <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 Table#setSelection(int[])
  */
 public void select(int indices[]) {
 	checkWidget ();
@@ -2372,11 +2461,16 @@
 	}
 }
 /**
- * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the index was already selected, it remains
- * selected. The range of the indices is inclusive. Indices that are
- * out of range are ignored and no items will be selected if start is
- * greater than end.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If an item in the given range is not selected, it is selected.
+ * If an item in the given range was already selected, it remains selected.
+ * Indices that are out of range are ignored and no items will be selected
+ * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start of the range
  * @param end the end of the range
@@ -2385,6 +2479,8 @@
  *    <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 Table#setSelection(int,int)
  */
 public void select(int start, int end) {
 	checkWidget ();
@@ -2411,7 +2507,9 @@
 	}
 }
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2535,7 +2633,7 @@
  * it visible may not actually cause it to be displayed.
  * </p>
  *
- * @param visible the new visibility state
+ * @param show the new visibility state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2554,6 +2652,18 @@
 		redraw();
 	}
 }
+/**
+ * Sets the number of items contained in the receiver.
+ *
+ * @param count the number of items
+ *
+ * @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 void setItemCount (int count) {
 	checkWidget ();
 	count = Math.max (0, count);
@@ -2584,7 +2694,7 @@
  * it visible may not actually cause it to be displayed.
  * </p>
  *
- * @param visible the new visibility state
+ * @param show the new visibility state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2613,8 +2723,12 @@
 	resizeColumn = column;
 }
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selected is first cleared, then the new items are selected.
+ * Selects the items at the given zero-relative indices in the receiver.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the indices of the items to select
  *
@@ -2652,14 +2766,17 @@
 }
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the item has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2667,7 +2784,8 @@
  * </ul>
  *
  * @see Table#deselectAll()
- * @see Table#select(int)
+ * @see Table#select(int[])
+ * @see Table#setSelection(int[])
  */
 public void setSelection(TableItem items[]) {
 	checkWidget ();
@@ -2700,10 +2818,14 @@
 	showSelection ();
 }
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is cleared before the new items are selected.
+ * <p>
  * Indices that are out of range are ignored and no items will be selected
  * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  * 
  * @param start the start index of the items to select
  * @param end the end index of the items to select
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 f40a660..0ce55db 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
@@ -387,7 +387,7 @@
 /**
  * Returns <code>true</code> if the receiver is checked,
  * and false otherwise.  When the parent does not have
- * the <code>CHECK style, return false.
+ * the <code>CHECK</code> style, return false.
  *
  * @return the checked state of the checkbox
  *
@@ -1415,7 +1415,7 @@
 	setImage(0, image);
 }
 /**
- * Sets the image indent.
+ * Sets the indent of the first column's image, expressed in terms of the image's width.
  *
  * @param indent the new indent
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java
index e269f85..2bd2faa 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java
@@ -668,7 +668,7 @@
 	return super.getItemHeight();
 }
 /**
- * Returns the number of items contained in the receiver
+ * Returns the items contained in the receiver
  * that are direct item children of the receiver.  These
  * are the roots of the tree.
  * <p>
@@ -677,7 +677,7 @@
  * not affect the receiver. 
  * </p>
  *
- * @return the number of items
+ * @return the items
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1419,7 +1419,9 @@
 		clientArea.width, clientArea.height, true);
 }
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1476,7 +1478,7 @@
  * will be inserted when dropped on the tree.
  * 
  * @param item the insert item.  Null will clear the insertion mark.
- * @param after true places the insert mark above 'item'. false places 
+ * @param before true places the insert mark above 'item'. false places 
  *	the insert mark below 'item'.
  *
  * @exception IllegalArgumentException <ul>
@@ -1494,14 +1496,17 @@
 }
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the item has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</li>
  * </ul>
  * @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 c202ee5..c814092 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
@@ -1205,11 +1205,7 @@
 void setParentItem(TreeItem parentItem) {
 	this.parentItem = parentItem;
 }
-/**
- * This label will be displayed to the right of the bitmap, 
- * or, if the receiver doesn't have a bitmap to the right of 
- * the horizontal hierarchy connector line.
- */
+
 public void setText(String newText) {
 	checkWidget();
 	Tree parent = getParent();	
@@ -1409,7 +1405,7 @@
  * Sets the grayed state of the receiver.
  * <p>
  *
- * @param checked the new grayed state
+ * @param grayed the new grayed state
  *
  * @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/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
index 70d32ee..44322d2 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
@@ -86,7 +86,7 @@
  * </p>
  *
  * @param device the device on which to allocate the color
- * @param RGB the RGB values of the desired color
+ * @param rgb the RGB values of the desired color
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -206,6 +206,8 @@
 /**
  * Returns an <code>RGB</code> representing the receiver.
  *
+ * @return the RGB for the color
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
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 b4f75ea..5a52e50 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
@@ -133,7 +133,7 @@
 /**	 
  * Constructs a new cursor given a device, image and mask
  * data describing the desired cursor appearance, and the x
- * and y co-ordinates of the <em>hotspot</em> (that is, the point
+ * and y coordinates of the <em>hotspot</em> (that is, the point
  * within the area covered by the cursor which is considered
  * to be where the on-screen pointer is "pointing").
  * <p>
@@ -240,6 +240,33 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**	 
+ * Constructs a new cursor given a device, image data describing
+ * the desired cursor appearance, and the x and y coordinates of
+ * the <em>hotspot</em> (that is, the point within the area
+ * covered by the cursor which is considered to be where the
+ * on-screen pointer is "pointing").
+ * <p>
+ * You must dispose the cursor when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the cursor
+ * @param source the image data for the cursor
+ * @param hotspotX the x coordinate of the cursor's hotspot
+ * @param hotspotY the y coordinate of the cursor's hotspot
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the hotspot is outside the bounds of the
+ * 		 image</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java
index 1d3b4e7..5a915ab 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java
@@ -313,7 +313,7 @@
  * <code>faceName</code> is null, all fonts will be returned.
  *
  * @param faceName the name of the font to look for, or null
- * @param scalable true if scalable fonts should be returned.
+ * @param scalable if true only scalable fonts are returned, otherwise only non-scalable fonts are returned.
  * @return the matching font data
  *
  * @exception SWTException <ul>
@@ -525,7 +525,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public abstract void internal_dispose_GC (int /*long*/ handle, GCData data);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java
index 712134c..bf96a2d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java
@@ -15,7 +15,6 @@
 
 /**
  * Instances of this class describe operating system fonts.
- * Only the public API of this type is platform independent.
  * <p>
  * For platform-independent behaviour, use the get and set methods
  * corresponding to the following properties:
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 d62049d..145a06e 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
@@ -19,6 +19,17 @@
  * Class <code>GC</code> is where all of the drawing capabilities that are 
  * supported by SWT are located. Instances are used to draw on either an 
  * <code>Image</code>, a <code>Control</code>, or directly on a <code>Display</code>.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
+ * </dl>
+ * 
+ * <p>
+ * The SWT drawing coordinate system is the two-dimensional space with the origin
+ * (0,0) at the top left corner of the drawing area and with (x,y) values increasing
+ * to the right and downward respectively.
+ * </p>
+ * 
  * <p>
  * Application code must explicitly invoke the <code>GC.dispose()</code> 
  * method to release the operating system resources managed by each instance
@@ -26,6 +37,10 @@
  * important on Windows95 and Windows98 where the operating system has a limited
  * number of device contexts available.
  * </p>
+ * 
+ * <p>
+ * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
+ * </p>
  *
  * @see org.eclipse.swt.events.PaintEvent
  */
@@ -67,6 +82,32 @@
 	this(drawable, 0);
 }
 
+/**	 
+ * Constructs a new instance of this class which has been
+ * configured to draw on the specified drawable. Sets the
+ * foreground and background color in the GC to match those
+ * in the drawable.
+ * <p>
+ * You must dispose the graphics context when it is no longer required. 
+ * </p>
+ * 
+ * @param drawable the drawable to draw on
+ * @param style the style of GC to construct
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the drawable is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if there is no current device</li>
+ *    <li>ERROR_INVALID_ARGUMENT
+ *          - if the drawable is an image that is not a bitmap or an icon
+ *          - if the drawable is an image or printer that is already selected
+ *            into another graphics context</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li>
+ * </ul>
+ *  
+ * @since 2.1.2
+ */
 public GC(Drawable drawable, int style) {
 	if (drawable == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	GCData data = new GCData();
@@ -96,6 +137,7 @@
  * Copies a rectangular area of the receiver at the specified
  * position into the image, which must be of type <code>SWT.BITMAP</code>.
  *
+ * @param image the image to copy into
  * @param x the x coordinate in the receiver of the area to be copied
  * @param y the y coordinate in the receiver of the area to be copied
  *
@@ -239,9 +281,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -581,6 +620,23 @@
 	OS.gdk_draw_arc(data.drawable, handle, 0, x, y, width, height, 0, 23040);
 }
 
+/** 
+ * Draws a pixel, using the foreground color, at the specified
+ * point (<code>x</code>, <code>y</code>).
+ * <p>
+ * Note that the receiver's line attributes do not affect this
+ * operation.
+ * </p>
+ *
+ * @param x the point's x coordinate
+ * @param y the point's y coordinate
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *  
+ * @since 3.0
+ */
 public void drawPoint (int x, int y) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.gdk_draw_point(data.drawable, handle, x, y);
@@ -964,9 +1020,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -1159,7 +1212,7 @@
  * Fills the interior of the specified rectangle, using the receiver's
  * background color. 
  *
- * @param rectangle the rectangle to be filled
+ * @param rect the rectangle to be filled
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
@@ -1482,6 +1535,24 @@
 	return values.line_width;
 }
 
+/**
+ * Returns the receiver's style information.
+ * <p>
+ * Note that the value which is returned by this method <em>may
+ * not match</em> the value which was provided to the constructor
+ * when the receiver was created. This can occur when the underlying
+ * operating system does not support a particular combination of
+ * requested styles. 
+ * </p>
+ *
+ * @return the style bits
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *   
+ * @since 2.1.2
+ */
 public int getStyle () {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.style;
@@ -1670,7 +1741,7 @@
  * by drawing operations to the region specified
  * by the argument.
  *
- * @param rect the clipping region.
+ * @param region the clipping region.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
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 0a91f67..9abecc3 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
@@ -183,6 +183,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon, or
  *          is otherwise in an invalid state</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the Image is not supported</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -378,6 +379,9 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li>
+ * </ul>
  */
 public Image(Device device, ImageData data) {
 	if (device == null) device = Device.getDevice();
@@ -458,6 +462,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -490,6 +495,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -877,7 +883,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) {
@@ -909,7 +915,7 @@
  * these cases. For example:
  * <pre>
  *    Button b = new Button();
- *    image.setBackground(b.getBackground());>
+ *    image.setBackground(b.getBackground());
  *    b.setImage(image);
  * </pre>
  * </p><p>
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 e73a975..a9e77a6 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
@@ -47,6 +47,25 @@
 	this(null);
 }
 
+/**
+ * Constructs a new empty region.
+ * <p>
+ * You must dispose the region when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the region
+ *
+* @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ *
+ * @see #dispose
+ * 
+ * @since 3.0
+ */
 public Region(Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -240,6 +259,22 @@
 	return (int)/*64*/handle;
 }
 
+/**
+ * Intersects the given rectangle to the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to intersect with the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect(Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -254,6 +289,23 @@
 	OS.gdk_region_destroy(rectRgn);
 }
 
+/**
+ * Intersects all of the rectangles which make up the area covered
+ * by the argument to the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to intersect
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect(Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -343,7 +395,7 @@
  * Subtracts the given polygon from the collection of rectangles
  * the receiver maintains to describe its area.
  *
- * param pointArray points that describe the polygon to merge with the receiver
+ * @param pointArray points that describe the polygon to merge with the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
@@ -362,6 +414,22 @@
 	OS.gdk_region_destroy(polyRgn);
 }
 
+/**
+ * Subtracts the given rectangle from the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to subtract from the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract(Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -376,6 +444,23 @@
 	OS.gdk_region_destroy(rectRgn);
 }
 
+/**
+ * Subtracts all of the rectangles which make up the area covered
+ * by the argument from the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to subtract
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract(Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
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 877ec67..aa44ff3 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
@@ -14,6 +14,23 @@
 import org.eclipse.swt.internal.gtk.*;
 import org.eclipse.swt.*;
 
+/**
+ * <code>TextLayout</code> is a graphic object that represents
+ * styled text.
+ *<p>
+ * Instances of this class provide support for drawing, cursor
+ * navigation, hit testing, text wrapping, alignment, tab expansion
+ * line breaking, etc.  These are aspects required for rendering internationalized text.
+ * </p>
+ * 
+ * <p>
+ * Application code must explicitly invoke the <code>TextLayout#dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ *  @since 3.0
+ */
 public final class TextLayout {
 	
 	static class StyleItem {
@@ -31,6 +48,20 @@
 	
 	static final char LTR_MARK = '\u200E', RTL_MARK = '\u200F', OBJECT_REPLACEMENT_CHARACTER = '\uFFFC';
 
+/**	 
+ * Constructs a new instance of this class on the given device.
+ * <p>
+ * You must dispose the text layout when it is no longer required. 
+ * </p>
+ * 
+ * @param device the device on which to allocate the text layout
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public TextLayout (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -133,6 +164,10 @@
 	OS.pango_layout_set_attributes(layout, attrList);
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the text layout. Applications must dispose of all allocated text layouts.
+ */
 public void dispose() {
 	if (layout == 0) return;
 	font = null;
@@ -146,6 +181,18 @@
 	device = null;
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw(GC gc, int x, int y) {
 	checkLayout ();
 	computeRuns();
@@ -154,6 +201,22 @@
 	OS.gdk_draw_layout(gc.data.drawable, gc.handle, x, y, layout);
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param selectionStart the offset where the selections starts, or -1 indicating no selection
+ * @param selectionEnd the offset where the selections ends, or -1 indicating no selection
+ * @param selectionForeground selection foreground, or NULL to use the system default color
+ * @param selectionBackground selection background, or NULL to use the system default color
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) {
 	checkLayout ();
 	computeRuns();
@@ -203,6 +266,17 @@
 	attrList = 0;
 }
 
+/** 
+ * Returns the receiver's horizontal text alignment, which will be one
+ * of <code>SWT.LEFT</code>, <code>SWT.CENTER</code> or
+ * <code>SWT.RIGHT</code>.
+ *
+ * @return the alignment used to positioned text horizontally
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getAlignment() {
 	checkLayout();
 	int align = OS.pango_layout_get_alignment(layout);
@@ -213,11 +287,32 @@
 	return SWT.LEFT;
 }
 
+/**
+ * Returns the ascent of the receiver.
+ *
+ * @return the ascent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ *  @see #getDescent()
+ * 
+ */
 public int getAscent () {
 	checkLayout();
 	return ascent;
 }
 
+/**
+ * Returns the bounds of the receiver.
+ * 
+ * @return the bounds of the receiver
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds() {
 	checkLayout();
 	computeRuns();
@@ -229,6 +324,20 @@
 	return new Rectangle(0, 0, width, height);
 }
 
+/**
+ * Returns the bounds for the specified range of characters. The
+ * bounds is the smallest rectangle that encompasses all characters
+ * in the range. The start and end offsets are inclusive and will be
+ * clamped if out of range.
+ * 
+ * @param start the start offset
+ * @param end the end offset
+ * @return the bounds of the character range
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds(int start, int end) {
 	checkLayout();
 	computeRuns();
@@ -251,16 +360,51 @@
 	return new Rectangle(rect.x, rect.y, rect.width, rect.height);
 }
 
+/**
+ * Returns the descent of the receiver.
+ *
+ * @return the descent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAscent()
+ */
 public int getDescent () {
 	checkLayout();
 	return descent;
 }
 
+/** 
+ * Returns the default font currently being used by the receiver
+ * to draw and measure text.
+ *
+ * @return the receiver's font
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Font getFont () {
 	checkLayout();
 	return font;
 }
 
+/**
+ * Returns the embedding level for the specified character offset. The
+ * embedding level is usually used to determine the directionality of a
+ * character in bidirectional text.
+ * 
+ * @param offset the charecter offset
+ * @return the embedding level
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ */
 public int getLevel(int offset) {
 	checkLayout();
 	computeRuns();
@@ -289,6 +433,19 @@
 	return level;
 }
 
+/**
+ * Returns the bounds of the line for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the line bounds 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getLineBounds(int lineIndex) {
 	checkLayout();
 	computeRuns();
@@ -307,12 +464,36 @@
 	return new Rectangle(x, y, width, height);
 }
 
+/**
+ * Returns the receiver's line count. This includes lines caused
+ * by wrapping.
+ *
+ * @return the line count
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineCount() {
 	checkLayout ();
 	computeRuns();
 	return OS.pango_layout_get_line_count(layout);
 }
 
+/**
+ * Returns the index of the line that contains the specified
+ * character offset.
+ * 
+ * @param offset the character offset
+ * @return the line index
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineIndex(int offset) {
 	checkLayout ();
 	computeRuns();
@@ -332,6 +513,19 @@
 	return line;
 }
 
+/**
+ * Returns the font metrics for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the font metrics 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public FontMetrics getLineMetrics (int lineIndex) {
 	checkLayout ();
 	computeRuns();
@@ -382,6 +576,17 @@
 	return FontMetrics.gtk_new(ascent, descent, averageCharWidth, 0, height);
 }
 
+/**
+ * Returns the line offsets.  Each value in the array is the
+ * offset for the first character in a line except for the last
+ * value, which contains the length of the text.
+ * 
+ * @return the line offsets
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getLineOffsets() {
 	checkLayout();
 	computeRuns();
@@ -400,6 +605,22 @@
 	return offsets;
 }
 
+/**
+ * Returns the location for the specified character offset. The
+ * <code>trailing</code> argument indicates whether the offset
+ * corresponds to the leading or trailing edge of the cluster.
+ * 
+ * @param offset the character offset
+ * @param trailing the trailing flag
+ * @return the location of the character offset
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getOffset(Point, int[])
+ * @see #getOffset(int, int, int[])
+ */
 public Point getLocation(int offset, boolean trailing) {
 	checkLayout();
 	computeRuns();
@@ -415,6 +636,24 @@
 	return new Point(OS.PANGO_PIXELS(x), OS.PANGO_PIXELS(y));
 }
 
+/**
+ * Returns the next offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the next offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getPreviousOffset(int, int)
+ */
 public int getNextOffset (int offset, int movement) {
 	return _getOffset(offset, movement, true);
 }
@@ -448,12 +687,51 @@
 	return Math.min(Math.max(0, untranslateOffset(offset)), text.length());
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param point the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset(Point point, int[] trailing) {
 	checkLayout();
 	if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	return getOffset(point.x, point.y, trailing);
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param x the x coordinate of the point
+ * @param y the y coordinate of the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset(int x, int y, int[] trailing) {
 	checkLayout();
 	computeRuns();
@@ -467,16 +745,52 @@
 	return untranslateOffset(offset);
 }
 
+/**
+ * Returns the orientation of the receiver.
+ *
+ * @return the orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getOrientation() {
 	checkLayout();
 	int baseDir = OS.pango_context_get_base_dir(context);
 	return baseDir == OS.PANGO_DIRECTION_RTL ? SWT.RIGHT_TO_LEFT : SWT.LEFT_TO_RIGHT;
 }
 
+/**
+ * Returns the previous offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the previous offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getNextOffset(int, int)
+ */
 public int getPreviousOffset (int index, int movement) {
 	return _getOffset(index, movement, false);
 }
 
+/**
+ * Returns the text segments offsets of the receiver.
+ *
+ * @return the text segments offsets
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getSegments() {
 	checkLayout();
 	return segments;
@@ -510,11 +824,30 @@
 	return new String(newChars, 0, Math.min(charCount + segmentCount, newChars.length));
 }
 
+/**
+ * Returns the line spacing of the receiver.
+ *
+ * @return the line spacing
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getSpacing () {
 	checkLayout();	
 	return OS.PANGO_PIXELS(OS.pango_layout_get_spacing(layout));
 }
 
+/**
+ * Gets the style of the receiver at the specified offset.
+ *
+ * @param offset the text offset
+ * @return the style or <code>null</code> if not set
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public TextStyle getStyle (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -528,6 +861,15 @@
 	return null;
 }
 
+/**
+ * Returns the tab list of the receiver.
+ *
+ * @return the tab list
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getTabs() {
 	checkLayout();
 	int /*long*/ tabArray = OS.pango_layout_get_tabs(layout);
@@ -546,20 +888,67 @@
 	return tabs;
 }
 
+/**
+ * Gets the receiver's text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's text
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public String getText () {
 	checkLayout ();
 	return text;
 }
 
+/**
+ * Returns the width of the receiver.
+ *
+ * @return the width
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getWidth () {
 	checkLayout ();
 	return OS.PANGO_PIXELS(OS.pango_layout_get_width(layout));
 }
 
+/**
+ * Returns <code>true</code> if the text layout has been disposed,
+ * and <code>false</code> otherwise.
+ * <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.
+ *
+ * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
+ */
 public boolean isDisposed () {
 	return layout == 0;
 }
 
+/**
+ * Sets the text alignment for the receiver. The alignment controls
+ * how a line of text is positioned horizontally. The argument should
+ * be one of <code>SWT.LEFT</code>, <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>.
+ * <p>
+ * The default alignment is <code>SWT.LEFT</code>.  Note that the receiver's
+ * width must be set in order to use <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>
+ * alignment.
+ *</p>
+ *
+ * @param alignment the new alignment 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setWidth(int)
+ */
 public void setAlignment (int alignment) {
 	checkLayout();
 	int mask = SWT.LEFT | SWT.CENTER | SWT.RIGHT;
@@ -575,6 +964,23 @@
 	OS.pango_layout_set_alignment(layout, align);
 }
 
+/**
+ * Sets the ascent of the receiver. The ascent is distance in pixels
+ * from the baseline to the top of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * ascent is calculated from the line fonts.
+ *
+ * @param ascent the new ascent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the ascent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setDescent(int)
+ */
 public void setAscent (int ascent) {
 	checkLayout();
 	if (ascent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -583,6 +989,23 @@
 	this.ascent = ascent;
 }
 
+/**
+ * Sets the descent of the receiver. The descent is distance in pixels
+ * from the baseline to the bottom of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * descent is calculated from the line fonts.
+ *
+ * @param descent the new descent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the descent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAscent(int)
+ */
 public void setDescent (int descent) {
 	checkLayout();
 	if (descent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -591,6 +1014,22 @@
 	this.descent = descent;
 }
 
+/** 
+ * Sets the default font which will be used by the receiver
+ * to draw and measure text. If the
+ * argument is null, then a default font appropriate
+ * for the platform will be used instead. Note that a text
+ * style can override the default font.
+ *
+ * @param font the new font for the receiver, or null to indicate a default font
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setFont (Font font) {
 	checkLayout ();
 	if (font != null && font.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -600,6 +1039,17 @@
 	OS.pango_layout_set_font_description(layout, font != null ? font.handle : 0);
 }
 
+/**
+ * Sets the orientation of the receiver, which must be one
+ * of <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
+ * <p>
+ *
+ * @param orientation new orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setOrientation(int orientation) {
 	checkLayout();
 	int mask = SWT.RIGHT_TO_LEFT | SWT.LEFT_TO_RIGHT;
@@ -612,12 +1062,42 @@
 	OS.pango_layout_context_changed(layout);
 }
 
+/**
+ * Sets the line spacing of the receiver.  The line spacing
+ * is the space left between lines.
+ *
+ * @param spacing the new line spacing 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the spacing is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSpacing (int spacing) {
 	checkLayout();
 	if (spacing < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 	OS.pango_layout_set_spacing(layout, spacing * OS.PANGO_SCALE);
 }
 
+/**
+ * Sets the offsets of the receiver's text segments. Text segments are used to
+ * override the default behaviour of the bidirectional algorithm.
+ * Bidirectional reordering can happen within a text segment but not 
+ * between two adjacent segments.
+ * Each text segment is determined by two consecutive offsets in the 
+ * <code>segments</code> arrays. The first element of the array should 
+ * always be zero and the last one should always be equals to length of
+ * the text.
+ * <p>
+ * 
+ * @param segments the text segments offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSegments(int[] segments) {
 	checkLayout();
 	if (this.segments == null && segments == null) return;
@@ -634,6 +1114,19 @@
 	this.segments = segments;
 }
 
+/**
+ * Sets the style of the receiver for the specified range.  Styles previously
+ * set for that range will be overwritten.  The start and end offsets are
+ * inclusive and will be clamped if out of range.
+ * 
+ * @param style the style
+ * @param start the start offset
+ * @param end the end offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setStyle (TextStyle style, int start, int end) {
 	checkLayout();
 	int length = text.length();
@@ -712,6 +1205,17 @@
 	}
 }
 
+/**
+ * Sets the receiver's tab list. Each value in the tab list specifies
+ * the space in pixels from the origin of the text layout to the respective
+ * tab stop.  The last tab stop width is repeated continuously.
+ * 
+ * @param tabs the new tab list
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setTabs(int[] tabs) {
 	checkLayout();
 	if (tabs == null) {
@@ -728,6 +1232,18 @@
 	}
 }
 
+/**
+ * Sets the receiver's text.
+ *
+ * @param text the new text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the text is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setText (String text) {
 	checkLayout ();
 	if (text == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -740,6 +1256,22 @@
 	styles[styles.length - 1].start = text.length();
 }
 
+/**
+ * Sets the line width of the receiver, which determines how
+ * text should be wrapped and aligned. The default value is
+ * <code>-1</code> which means wrapping is disabled.
+ *
+ * @param width the new width 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the width is <code>0</code> or less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlignment(int)
+ */
 public void setWidth (int width) {
 	checkLayout ();
 	if (width < -1 || width == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
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 9c1814b..24267f2 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
@@ -325,7 +325,8 @@
 
 /**
  * Returns the receiver's text, which will be an empty
- * string if it has never been set.
+ * string if it has never been set or if the receiver is
+ * an <code>ARROW</code> button.
  *
  * @return the receiver's text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Caret.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Caret.java
index 5d1fa2e..3e9454c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Caret.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Caret.java
@@ -366,7 +366,7 @@
  * to the image specified by the argument, or to the default
  * which is a filled rectangle if the argument is null
  *
- * @param font the new font (or null)
+ * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
@@ -443,7 +443,6 @@
  * Sets the receiver's size to the point specified by the argument.
  *
  * @param size the new extent for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java
index 3e34b84..3c30843 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java
@@ -35,7 +35,7 @@
 /**
  * Constructs a new instance of this class given only its parent.
  *
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a composite control which will be the parent of the new instance
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -140,7 +140,7 @@
  * Sets the receiver's selected color to be the argument.
  *
  * @param rgb the new RGB value for the selected color, may be
- *        null to let the platform to select a default when
+ *        null to let the platform select a default when
  *        open() is called
  * @see PaletteData#getRGBs
  */
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 bfa4177..9c528ed 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
@@ -619,7 +619,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -839,6 +839,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to begin the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1119,6 +1120,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1144,6 +1146,9 @@
  *
  * @param items the array of items
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the items array 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>
@@ -1211,10 +1216,10 @@
 
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1233,7 +1238,7 @@
  * start of the selection and whose y coordinate is the end
  * of the selection. 
  *
- * @param a point representing the new selection start and end
+ * @param selection a point representing the new selection start and end
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -1261,7 +1266,7 @@
  * display incorrectly.
  * </p>
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
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 ff229ad..b1dc1b5 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
@@ -20,7 +20,7 @@
  * of containing other controls.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
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 d0844a6..2040ac8 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
@@ -27,7 +27,7 @@
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>FocusIn, FocusOut, Help, KeyDown, KeyUp, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
  * </dl>
  * <p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -35,8 +35,6 @@
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
- * 
- * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
  */
 public abstract class Control extends Widget implements Drawable {
 	int /*long*/ fixedHandle;
@@ -375,7 +373,9 @@
 
 /**
  * Returns a rectangle describing the receiver's size and location
- * relative to its parent (or its display if its parent is null).
+ * relative to its parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the location is
+ * relative to the display.
  *
  * @return the receiver's bounding rectangle
  *
@@ -422,7 +422,9 @@
  * Sets the receiver's size and location to the rectangular
  * area specified by the arguments. The <code>x</code> and 
  * <code>y</code> arguments are relative to the receiver's
- * parent (or its display if its parent is null).
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the <code>x</code>
+ * and <code>y</code> arguments are relative to the display.
  * <p>
  * Note: Attempting to set the width or height of the
  * receiver to a negative number will cause that
@@ -511,7 +513,9 @@
 
 /**
  * Returns a point describing the receiver's location relative
- * to its parent (or its display if its parent is null).
+ * to its parent (or its display if its parent is null), unless
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @return the receiver's location
  *
@@ -530,8 +534,10 @@
 
 /**
  * Sets the receiver's location to the point specified by
- * the argument which is relative to the receiver's
- * parent (or its display if its parent is null).
+ * the arguments which are relative to the receiver's
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @param location the new location for the receiver
  *
@@ -549,7 +555,9 @@
 /**
  * Sets the receiver's location to the point specified by
  * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null).
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @param x the new x coordinate for the receiver
  * @param y the new y coordinate for the receiver
@@ -594,7 +602,6 @@
  * </p>
  *
  * @param size the new size for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -638,7 +645,7 @@
  * the top of the drawing order will not be covered by other
  * controls even if they occupy intersecting areas.
  *
- * @param the sibling control (or null)
+ * @param control the sibling control (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the control has been disposed</li> 
@@ -647,6 +654,8 @@
  *    <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 #moveBelow
  */
 public void moveAbove (Control control) {
 	checkWidget();
@@ -664,7 +673,7 @@
  * the bottom of the drawing order will be covered by all other
  * controls which occupy intersecting areas.
  *
- * @param the sibling control (or null)
+ * @param control the sibling control (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the control has been disposed</li> 
@@ -673,6 +682,8 @@
  *    <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 #moveAbove
  */
 public void moveBelow (Control control) {
 	checkWidget();
@@ -711,6 +722,8 @@
  * manager caches can be retained. 
  * </p>
  *
+ * @param changed whether or not the receiver's contents have changed
+ * 
  * @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>
@@ -1491,6 +1504,13 @@
 	return menu;
 }
 
+/**
+ * Returns the receiver's monitor.
+ * 
+ * @return the receiver's monitor
+ * 
+ * @since 3.0
+ */
 public Monitor getMonitor () {
 	checkWidget();
 	Monitor monitor = null;
@@ -1912,7 +1932,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) {
@@ -2058,7 +2078,8 @@
 /**
  * Causes the entire bounds of the receiver to be marked
  * as needing to be redrawn. The next time a paint request
- * is processed, the control will be completely painted.
+ * is processed, the control will be completely painted,
+ * including the background.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2066,6 +2087,11 @@
  * </ul>
  *
  * @see #update
+ * @see PaintListener
+ * @see SWT#Paint
+ * @see SWT#NO_BACKGROUND
+ * @see SWT#NO_REDRAW_RESIZE
+ * @see SWT#NO_MERGE_PAINTS
  */
 public void redraw () {
 	checkWidget();
@@ -2078,11 +2104,12 @@
  * Causes the rectangular area of the receiver specified by
  * the arguments to be marked as needing to be redrawn. 
  * The next time a paint request is processed, that area of
- * the receiver will be painted. If the <code>all</code> flag
- * is <code>true</code>, any children of the receiver which
- * intersect with the specified area will also paint their
- * intersecting areas. If the <code>all</code> flag is 
- * <code>false</code>, the children will not be painted.
+ * the receiver will be painted, including the background.
+ * If the <code>all</code> flag is <code>true</code>, any
+ * children of the receiver which intersect with the specified
+ * area will also paint their intersecting areas. If the
+ * <code>all</code> flag is <code>false</code>, the children
+ * will not be painted.
  *
  * @param x the x coordinate of the area to draw
  * @param y the y coordinate of the area to draw
@@ -2096,6 +2123,11 @@
  * </ul>
  *
  * @see #update
+ * @see PaintListener
+ * @see SWT#Paint
+ * @see SWT#NO_BACKGROUND
+ * @see SWT#NO_REDRAW_RESIZE
+ * @see SWT#NO_MERGE_PAINTS
  */
 public void redraw (int x, int y, int width, int height, boolean all) {
 	checkWidget();
@@ -2411,7 +2443,8 @@
 
 /**
  * Causes the receiver to have the <em>keyboard focus</em>, 
- * such that all keyboard events will be delivered to it.
+ * such that all keyboard events will be delivered to it.  Focus
+ * reassignment will respect applicable platform constraints.
  *
  * @return <code>true</code> if the control got focus, and <code>false</code> if it was unable to.
  *
@@ -2995,6 +3028,8 @@
  * </ul>
  *
  * @see #redraw
+ * @see PaintListener
+ * @see SWT#Paint
  */
 public void update () {
 	checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java
index 69aa449..21c2190 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java
@@ -21,6 +21,11 @@
  * shares a significant amount of code with this class,
  * and is a subclass.
  * <p>
+ * IMPORTANT: This class was intended to be abstract and
+ * should <em>never</em> be referenced or instantiated.
+ * Instead, the class <code>Shell</code> should be used.
+ * </p>
+ * <p>
  * Instances are always displayed in one of the maximized, 
  * minimized or normal states:
  * <ul>
@@ -312,6 +317,33 @@
 	return image;
 }
 
+/**
+ * Returns the receiver's images if they had previously been 
+ * set using <code>setImages()</code>. Images are typically
+ * displayed by the window manager when the instance is
+ * marked as iconified, and may also be displayed somewhere
+ * in the trim when the instance is in normal or maximized
+ * states. Depending where the icon is displayed, the platform
+ * chooses the icon with the "best" size. It is expected that
+ * the array will contain the same icon rendered at different
+ * resolutions.
+ * 
+ * <p>
+ * Note: This method will return an empty array if called before
+ * <code>setImages()</code> is called. It does not provide
+ * access to a window manager provided, "default" image
+ * even if one exists.
+ * </p>
+ * 
+ * @return the images
+ *
+ * @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 Image [] getImages () {
 	checkWidget ();
 	return images;
@@ -464,7 +496,7 @@
  * disposed, the receiver's default button will be set to
  * null. 
  *
- * @param the new default button
+ * @param button the new default button
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the button has been disposed</li> 
@@ -508,6 +540,29 @@
 	_setImages (image != null ? new Image [] {image} : null);
 }
 
+/**
+ * Sets the receiver's images to the argument, which may
+ * be an empty array. Images are typically displayed by the
+ * window manager when the instance is marked as iconified,
+ * and may also be displayed somewhere in the trim when the
+ * instance is in normal or maximized states. Depending where
+ * the icon is displayed, the platform chooses the icon with
+ * the "best" size. It is expected that the array will contain
+ * the same icon rendered at different resolutions.
+ * 
+ * @param images the new image array
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of images is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the images 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.0
+ */
 public void setImages (Image [] images) {
 	checkWidget ();
 	if (images == null) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -532,7 +587,7 @@
  * always. This should be avoided if possible.
  * </p>
  *
- * @param the new maximized state
+ * @param maximized the new maximized state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -585,7 +640,7 @@
  * always. This should be avoided if possible.
  * </p>
  *
- * @param the new maximized state
+ * @param minimized the new maximized state
  *
  * @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/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java
index 3c34941..59ca444 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -18,6 +18,12 @@
 /**
  * Instances of this class allow the user to navigate
  * the file system and select a directory.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>(none)</dd>
+ * </dl>
  * <p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
@@ -28,16 +34,7 @@
 	static final String SEPARATOR = System.getProperty ("file.separator");
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -64,15 +61,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent 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 10a3811..8f0ddfd 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
@@ -89,7 +89,7 @@
  * @see #wake
  * @see #readAndDispatch
  * @see #sleep
- * @see #dispose
+ * @see Device#dispose
  */
 public class Display extends Device {
 
@@ -394,6 +394,29 @@
 	super (data);
 }
 
+/**
+ * Adds the listener to the collection of listeners who will
+ * be notifed when an event of the given type occurs anywhere
+ * in this display. When the event does occur, the listener is
+ * notified by sending it the <code>handleEvent()</code> message.
+ *
+ * @param eventType the type of event to listen for
+ * @param listener the listener which should be notified when the event occurs
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Listener
+ * @see #removeFilter
+ * @see #removeListener
+ * 
+ * @since 3.0 
+ */
 public void addFilter (int eventType, Listener listener) {
 	checkDevice ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -577,7 +600,7 @@
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  * 
  * @since 2.0
  */
@@ -989,6 +1012,18 @@
 	return new Point (x [0], y [0]);
 }
 
+/**
+ * Returns an array containing the recommended cursor sizes.
+ *
+ * @return the array of cursor sizes
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Point [] getCursorSizes () {
 	checkDevice ();
 	return new Point [] {new Point (16, 16), new Point (32, 32)}; 
@@ -1163,6 +1198,23 @@
 	return null;
 }
 
+/**
+ * Returns true when the high contrast mode is enabled.
+ * Otherwise, false is returned.
+ * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
+ *
+ * @return the high contrast mode
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public boolean getHighContrast () {
 	checkDevice ();
 	return false;
@@ -1192,6 +1244,20 @@
 	return getDepth ();
 }
 
+/**
+ * Returns an array containing the recommended icon sizes.
+ *
+ * @return the array of icon sizes
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Decorations#setImages(Image[])
+ * 
+ * @since 3.0
+ */
 public Point [] getIconSizes () {
 	checkDevice ();
 	return new Point [] {new Point (16, 16), new Point (32, 32)}; 
@@ -1373,6 +1439,48 @@
 	return Color.gtk_new (this, gdkColor);
 }
 
+/**
+ * Returns the matching standard platform cursor for the given
+ * constant, which should be one of the cursor constants
+ * specified in class <code>SWT</code>. This cursor should
+ * not be free'd because it was allocated by the system,
+ * not the application.  A value of <code>null</code> will
+ * be returned if the supplied constant is not an swt cursor
+ * constant. 
+ *
+ * @param id the swt cursor constant
+ * @return the corresponding cursor or <code>null</code>
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see SWT#CURSOR_ARROW
+ * @see SWT#CURSOR_WAIT
+ * @see SWT#CURSOR_CROSS
+ * @see SWT#CURSOR_APPSTARTING
+ * @see SWT#CURSOR_HELP
+ * @see SWT#CURSOR_SIZEALL
+ * @see SWT#CURSOR_SIZENESW
+ * @see SWT#CURSOR_SIZENS
+ * @see SWT#CURSOR_SIZENWSE
+ * @see SWT#CURSOR_SIZEWE
+ * @see SWT#CURSOR_SIZEN
+ * @see SWT#CURSOR_SIZES
+ * @see SWT#CURSOR_SIZEE
+ * @see SWT#CURSOR_SIZEW
+ * @see SWT#CURSOR_SIZENE
+ * @see SWT#CURSOR_SIZESE
+ * @see SWT#CURSOR_SIZESW
+ * @see SWT#CURSOR_SIZENW
+ * @see SWT#CURSOR_UPARROW
+ * @see SWT#CURSOR_IBEAM
+ * @see SWT#CURSOR_NO
+ * @see SWT#CURSOR_HAND
+ * 
+ * @since 3.0
+ */
 public Cursor getSystemCursor (int id) {
 	checkDevice ();
 	if (!(0 <= id && id < cursors.length)) return null;
@@ -1382,6 +1490,32 @@
 	return cursors [id];
 }
 
+/**
+ * Returns the matching standard platform image for the given
+ * constant, which should be one of the icon constants
+ * specified in class <code>SWT</code>. This image should
+ * not be free'd because it was allocated by the system,
+ * not the application.  A value of <code>null</code> will
+ * be returned either if the supplied constant is not an
+ * swt icon constant or if the platform does not define an
+ * image that corresponds to the constant. 
+ *
+ * @param id the swt icon constant
+ * @return the corresponding image or <code>null</code>
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see SWT#ICON_ERROR
+ * @see SWT#ICON_INFORMATION
+ * @see SWT#ICON_QUESTION
+ * @see SWT#ICON_WARNING
+ * @see SWT#ICON_WORKING
+ * 
+ * @since 3.0
+ */
 public Image getSystemImage (int id) {
 	int /*long*/ imagePixmap = 0, imageMask = 0;
 	switch (id) {
@@ -1562,6 +1696,17 @@
 	return Font.gtk_new (this, defaultFont);
 }
 
+/**
+ * Returns the single instance of the system tray.
+ *
+ * @return the receiver's user-interface thread
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.0
+ */
 public Tray getSystemTray () {
 	if (tray != null) return tray;
 	return tray = new Tray (this, SWT.NULL);
@@ -1675,7 +1820,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) {
@@ -1723,12 +1868,84 @@
 	return thread == Thread.currentThread ();
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param point to be mapped 
+ * @return point with mapped coordinates 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Point map (Control from, Control to, Point point) {
 	checkDevice ();
 	if (point == null) error (SWT.ERROR_NULL_ARGUMENT);	
 	return map (from, to, point.x, point.y);
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param x coordinates to be mapped
+ * @param y coordinates to be mapped
+ * @return point with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Point map (Control from, Control to, int x, int y) {
 	checkDevice ();
 	if (from != null && from.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -1755,6 +1972,42 @@
 	return point;
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param rectangle to be mapped
+ * @return rectangle with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Rectangle map (Control from, Control to, Rectangle rectangle) {
 	checkDevice();
 	if (rectangle == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1784,6 +2037,44 @@
 	return widget.menuPositionProc (menu, x, y, push_in, user_data);	
 }
 
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param x coordinates to be mapped
+ * @param y coordinates to be mapped
+ * @param width coordinates to be mapped
+ * @param height coordinates to be mapped
+ * @return rectangle with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Rectangle map (Control from, Control to, int x, int y, int width, int height) {
 	checkDevice();
 	if (from != null && from.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -1816,6 +2107,54 @@
 	return widget.hoverProc (handle);
 }
 
+/**
+ * Generate a low level system event.
+ * 
+ * <code>post</code> is used to generate low level keyboard
+ * and mouse events. The intent is to enable automated UI
+ * testing by simulating the input from the user.  Most
+ * SWT applications should never need to call this method.
+ * 
+ * <p>
+ * <b>Event Types:</b>
+ * <p>KeyDown, KeyUp
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type KeyDown or KeyUp</li>
+ * <p> Either one of:
+ * <li>(in) character a character that corresponds to a keyboard key</li>
+ * <li>(in) keyCode the key code of the key that was typed,
+ *          as defined by the key code constants in class <code>SWT</code></li>
+ * </ul>
+ * <p>MouseDown, MouseUp</p>
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type MouseDown or MouseUp
+ * <li>(in) button the button that is pressed or released
+ * </ul>
+ * <p>MouseMove</p>
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type MouseMove
+ * <li>(in) x the x coordinate to move the mouse pointer to in screen coordinates
+ * <li>(in) y the y coordinate to move the mouse pointer to in screen coordinates
+ * </ul>
+ * </dl>
+ * 
+ * @param event the event to be generated
+ * 
+ * @return true if the event was generated or false otherwise
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the event is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.0
+ * 
+ */
 public boolean post (Event event) {
 	if (isDisposed ()) error (SWT.ERROR_DEVICE_DISPOSED);
 	if (event == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -2070,6 +2409,27 @@
 	eventCallback.dispose ();  eventCallback = null;
 }
 
+/**
+ * Removes the listener from the collection of listeners who will
+ * be notifed when an event of the given type occurs anywhere in
+ * this display.
+ *
+ * @param eventType the type of event to listen for
+ * @param listener the listener which should no longer be notified when the event occurs
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @see Listener
+ * @see #addFilter
+ * @see #addListener
+ * 
+ * @since 3.0
+ */
 public void removeFilter (int eventType, Listener listener) {
 	checkDevice ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java
index d8c74d1..05075b3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java
@@ -40,16 +40,7 @@
 	static final char SEPARATOR = System.getProperty ("file.separator").charAt (0);
 	
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -76,15 +67,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java
index d8bc13c..51792e1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java
@@ -19,6 +19,12 @@
 /**
  * Instances of this class allow the user to select a font
  * from all available fonts in the system.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>(none)</dd>
+ * </dl>
  * <p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
@@ -28,16 +34,7 @@
 	FontData fontData;
 	RGB rgb;
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -64,15 +61,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
index c6f7cfa..7b78627 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
@@ -92,29 +92,7 @@
 	return clientHandle;
 }
 
-/**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
- * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p>
- * 
- * @return the required bounds to produce the given client area
- *
- * @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 #getClientArea
- */
+
 public Rectangle computeTrim (int x, int y, int width, int height) {
 	checkWidget();
 	int clientX = OS.GTK_WIDGET_X (clientHandle);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java
index 26cb2d3..437bcf8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java
@@ -351,8 +351,8 @@
 }
 
 /**
- * Returns the zero-relative index of the item which is currently
- * has the focus in the receiver, or -1 if no item is has focus.
+ * Returns the zero-relative index of the item which currently
+ * has the focus in the receiver, or -1 if no item has focus.
  *
  * @return the index of the selected item
  *
@@ -757,6 +757,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to start the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1031,11 +1032,16 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the index was already selected, it remains
- * selected. The range of the indices is inclusive. Indices that are
- * out of range are ignored and no items will be selected if start is
- * greater than end.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If an item in the given range is not selected, it is selected.
+ * If an item in the given range was already selected, it remains selected.
+ * Indices that are out of range are ignored and no items will be selected
+ * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start of the range
  * @param end the end of the range
@@ -1044,6 +1050,8 @@
  *    <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 List#setSelection(int,int)
  */
 public void select (int start, int end) {
 	checkWidget ();
@@ -1070,20 +1078,25 @@
 
 /**
  * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the given zero-relative index in the receiver 
- * is not selected, it is selected.  If the item at the index
- * was selected, it remains selected. Indices that are out
- * of range and duplicate indices are ignored.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If the item at a given index is not selected, it is selected.
+ * If the item at a given index was already selected, it remains selected.
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the array of indices for the items to select
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of indices 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>
+ * 
+ * @see List#setSelection(int[])
  */
 public void select (int [] indices) {
 	checkWidget ();
@@ -1111,7 +1124,9 @@
 }
 
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1267,10 +1282,14 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is cleared before the new items are selected.
+ * <p>
  * Indices that are out of range are ignored and no items will be selected
  * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start index of the items to select
  * @param end the end index of the items to select
@@ -1280,8 +1299,8 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see Table#deselectAll()
- * @see Table#select(int,int)
+ * @see List#deselectAll()
+ * @see List#select(int,int)
  */
 public void setSelection (int start, int end) {
 	checkWidget ();
@@ -1306,13 +1325,17 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items at the given zero-relative indices in the receiver.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the indices of the items to select
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of indices is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1343,13 +1366,16 @@
 
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of items is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1357,7 +1383,8 @@
  * </ul>
  *
  * @see List#deselectAll()
- * @see List#select(int)
+ * @see List#select(int[])
+ * @see List#setSelection(int[])
  */
 public void setSelection (String [] items) {
 	checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
index a4acba0..ea399bf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
@@ -107,7 +107,7 @@
  * for the instance so that the instance will be a drop-down
  * menu on the given parent's parent.
  *
- * @param parent a menu which will be the parent of the new instance (cannot be null)
+ * @param parentMenu a menu which will be the parent of the new instance (cannot be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -131,7 +131,7 @@
  * for the instance so that the instance will be a drop-down
  * menu on the given parent's parent menu.
  *
- * @param parent a menu item which will be the parent of the new instance (cannot be null)
+ * @param parentItem a menu item which will be the parent of the new instance (cannot be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
index 32a4dc2..6b1418e 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
@@ -610,7 +610,7 @@
  * Note: This feature is not available on all window systems (for example, Window NT),
  * in which case, calling this method will silently do nothing.
  *
- * @param menu the image to display
+ * @param image the image to display
  *
  * @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/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java
index b9da6ec..ec65b11 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java
@@ -39,16 +39,7 @@
 	String message = "";
 	int /*long*/ handle;
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -75,16 +66,9 @@
  * of those <code>SWT</code> style constants. The class description
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
- * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java
index 5e897d2..0fd25cd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java
@@ -159,11 +159,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * 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
+ * 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 (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -179,11 +180,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value that the receiver will allow.  This new
+ * value will be ignored if it is negative or is not less 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 (must be zero or greater)
+ * @param value the new minimum, which must be nonnegative and less than 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/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
index baebbc8..064eb5e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
@@ -270,7 +270,7 @@
  * are pressed to the argument, which must be at least 
  * one.
  *
- * @param value the new increment (must be greater than zero)
+ * @param increment the new increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -286,11 +286,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * 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
+ * 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 (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -307,11 +308,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value that the receiver will allow.  This new
+ * value will be ignored if it is negative or is not less 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 (must be zero or greater)
+ * @param value the new minimum, which must be nonnegative and less than the current maximum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -334,7 +336,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param pageIncrement the page increment (must be greater than zero)
  *
  * @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/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
index 965aa19..2b033ee 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
@@ -481,11 +481,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the maximum. If this value is negative or less than or
+ * equal to the minimum, the value is ignored. If necessary, first
+ * the thumb and then the selection are adjusted to fit within the
+ * new range.
  *
- * @param value the new maximum (must be zero or greater)
+ * @param value the new maximum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -508,11 +509,12 @@
 }
 	
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value. If this value is negative or greater
+ * than or equal to the maximum, the value is ignored. If necessary,
+ * first the thumb and then the selection are adjusted to fit within
+ * the new range.
  *
- * @param value the new minimum (must be zero or greater)
+ * @param value the new minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -541,7 +543,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -565,7 +567,7 @@
  * value to the argument which must be greater than or equal
  * to zero.
  *
- * @param value the new selection (must be zero or greater)
+ * @param selection the new selection (must be zero or greater)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -582,17 +584,17 @@
 
 /**
  * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values to the
- * argument which must be at least one.
+ * difference between its maximum and minimum values.  This new
+ * value will be ignored if it is less than one, and will be
+ * clamped if it exceeds the receiver's current range.
  *
- * @param value the new thumb value (must be at least one)
+ * @param value the new thumb value, which must be at least one and not
+ * larger than the size of the current range
  *
  * @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 ScrollBar
  */
 public void setThumb (int value) {
 	checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scrollable.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scrollable.java
index d16db65..92c94f1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scrollable.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scrollable.java
@@ -89,6 +89,10 @@
  * receiver's parent).
  * </p>
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
index d6e8b66..1c55c2c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
@@ -439,6 +439,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
+ * @see SWT#Close
  * @see #dispose
  */
 public void close () {
@@ -598,9 +599,10 @@
 }
 
 /** 
- * Returns the region that defines the shape of the shell.
+ * Returns the region that defines the shape of the shell,
+ * or null if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell
+ * @return the region that defines the shape of the shell (or null)
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -749,8 +751,8 @@
  * the display on which it was created (so that all other
  * shells on that display, which are not the receiver's
  * children will be drawn behind it), marks it visible,
- * and sets focus to its default button (if it has one)
- * and asks the window manager to make the shell active.
+ * sets the focus and asks the window manager to make the
+ * shell active.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -996,11 +998,16 @@
 
 /**
  * Sets the shape of the shell to the region specified
- * by the argument.  A null region will restore the default shape.
- * Shell must be created with the style SWT.NO_TRIM.
+ * by the argument.  When the argument is null, the
+ * default shape of the shell is restored.  The shell
+ * must be created with the style SWT.NO_TRIM in order
+ * to specify a region.
  *
- * @param rgn the region that defines the shape of the shell
- * 
+ * @param region the region that defines the shape of the shell (or null)
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the region 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>
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 8a50ce4..540a943 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
@@ -359,11 +359,12 @@
 }
 
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the maximum. If this value is negative or less than or
+ * equal to the minimum, the value is ignored. If necessary, first
+ * the thumb and then the selection are adjusted to fit within the
+ * new range.
  *
- * @param value the new maximum (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -387,11 +388,12 @@
 }
 
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value. If this value is negative or greater
+ * than or equal to the maximum, the value is ignored. If necessary,
+ * first the thumb and then the selection are adjusted to fit within
+ * the new range.
  *
- * @param value the new minimum (must be zero or greater)
+ * @param value the new minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -421,7 +423,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -457,17 +459,17 @@
 
 /**
  * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values to the
- * argument which must be at least one.
+ * difference between its maximum and minimum values.  This new
+ * value will be ignored if it is less than one, and will be
+ * clamped if it exceeds the receiver's current range.
  *
- * @param value the new thumb value (must be at least one)
+ * @param value the new thumb value, which must be at least one and not
+ * larger than the size of the current range
  *
  * @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 ScrollBar
  */
 public void setThumb (int value) {
 	checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java
index 538b69b..3a155c5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java
@@ -608,7 +608,7 @@
 /**
  * Selects the item at the given zero-relative index in the receiver. 
  * If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are
+ * The current selection is first cleared, then the new items are
  * selected. Indices that are out of range are ignored.
  *
  * @param index the index of the item to select
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java
index c8ad03e..6745f42 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabItem.java
@@ -92,6 +92,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_RANGE - if the index is either negative or greater than the parent's current tab count</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java
index 1ee3508..58790b3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java
@@ -249,6 +249,27 @@
 	return size;
 }
 
+/**
+ * Clears the item at the given zero-relative index in the receiver.
+ * The text, icon and other attribues of the item are set to the default
+ * value.  If the table was created with the SWT.VIRTUAL style, these
+ * attributes are requested again as needed.
+ *
+ * @param index the index of the item to clear
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT#SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int index) {
 	checkWidget ();
 	if (!(0 <= index && index < itemCount)) {
@@ -258,6 +279,29 @@
 	if (item != null) item.clear();
 }
 
+/**
+ * Removes the items from the receiver which are between the given
+ * zero-relative start and end indices (inclusive).  The text, icon
+ * and other attribues of the items are set to their default values.
+ * If the table was created with the SWT.VIRTUAL style, these attributes
+ * are requested again as needed.
+ *
+ * @param start the start index of the item to clear
+ * @param end the end index of the item to clear
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if either the start or end are not between 0 and the number of elements in the list minus 1 (inclusive)</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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int start, int end) {
 	checkWidget ();
 	if (start > end) return;
@@ -274,6 +318,28 @@
 	}
 }
 
+/**
+ * Clears the items at the given zero-relative indices in the receiver.
+ * The text, icon and other attribues of the items are set to their default
+ * values.  If the table was created with the SWT.VIRTUAL style, these
+ * attributes are requested again as needed.
+ *
+ * @param indices the array of indices of the items
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the indices array 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>
+ * 
+ * @see SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clear (int [] indices) {
 	checkWidget ();
 	if (indices == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -289,6 +355,22 @@
 	}
 }
 
+/**
+ * Clears all the items in the receiver. The text, icon and other
+ * attribues of the items are set to their default values. If the
+ * table was created with the SWT.VIRTUAL style, these attributes
+ * are requested again as needed.
+ *
+ * @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 SWT#VIRTUAL
+ * @see SWT.SetData
+ * 
+ * @since 3.0
+ */
 public void clearAll () {
 	checkWidget ();
 	for (int i=0; i<itemCount; i++) {
@@ -877,6 +959,8 @@
 /**
  * Returns the width in pixels of a grid line.
  *
+ * @return the width of a grid line in pixels
+ * 
  * @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>
@@ -1684,7 +1768,7 @@
  * </ul>
  *
  * @see SelectionListener
- * @see #addSelectionListener
+ * @see #addSelectionListener(SelectionListener)
  */
 public void removeSelectionListener(SelectionListener listener) {
 	checkWidget();
@@ -1740,11 +1824,16 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the index was already selected, it remains
- * selected. The range of the indices is inclusive. Indices that are
- * out of range are ignored and no items will be selected if start is
- * greater than end.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If an item in the given range is not selected, it is selected.
+ * If an item in the given range was already selected, it remains selected.
+ * Indices that are out of range are ignored and no items will be selected
+ * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start of the range
  * @param end the end of the range
@@ -1753,6 +1842,8 @@
  *    <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 Table#setSelection(int,int)
  */
 public void select (int start, int end) {
 	checkWidget ();
@@ -1776,10 +1867,13 @@
 
 /**
  * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the given zero-relative index in the receiver 
- * is not selected, it is selected.  If the item at the index
- * was selected, it remains selected. Indices that are out
- * of range and duplicate indices are ignored.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If the item at a given index is not selected, it is selected.
+ * If the item at a given index was already selected, it remains selected.
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the array of indices for the items to select
  *
@@ -1790,6 +1884,8 @@
  *    <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 Table#setSelection(int[])
  */
 public void select (int [] indices) {
 	checkWidget ();
@@ -1814,7 +1910,9 @@
 }
 
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1900,7 +1998,7 @@
  * it visible may not actually cause it to be displayed.
  * </p>
  *
- * @param visible the new visibility state
+ * @param show the new visibility state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1912,6 +2010,18 @@
 	OS.gtk_tree_view_set_headers_visible (handle, show);
 }
 
+/**
+ * Sets the number of items contained in the receiver.
+ *
+ * @param count the number of items
+ *
+ * @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 void setItemCount (int count) {
 	checkWidget ();
 	count = Math.max (0, count);
@@ -1947,7 +2057,7 @@
  * it visible may not actually cause it to be displayed.
  * </p>
  *
- * @param visible the new visibility state
+ * @param show the new visibility state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2003,10 +2113,14 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is cleared before the new items are selected.
+ * <p>
  * Indices that are out of range are ignored and no items will be selected
  * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  * 
  * @param start the start index of the items to select
  * @param end the end index of the items to select
@@ -2031,8 +2145,12 @@
 }
 
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selected is first cleared, then the new items are selected.
+ * Selects the items at the given zero-relative indices in the receiver.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the indices of the items to select
  *
@@ -2059,14 +2177,17 @@
 
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the item has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2074,7 +2195,8 @@
  * </ul>
  *
  * @see Table#deselectAll()
- * @see Table#select(int)
+ * @see Table#select(int[])
+ * @see Table#setSelection(int[])
  */
 public void setSelection (TableItem [] items) {
 	checkWidget ();
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 43d5b5f..c006501 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
@@ -230,7 +230,7 @@
 /**
  * Returns <code>true</code> if the receiver is checked,
  * and false otherwise.  When the parent does not have
- * the <code>CHECK style, return false.
+ * the <code>CHECK</code> style, return false.
  *
  * @return the checked state of the checkbox
  *
@@ -902,7 +902,7 @@
 }
 
 /**
- * Sets the image indent.
+ * Sets the indent of the first column's image, expressed in terms of the image's width.
  *
  * @param indent the new indent
  *
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 cda061a..a55b4fc 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
@@ -23,7 +23,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>CENTER, LEFT, MULTI, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
+ * <dd>CENTER, LEFT, MULTI, PASSWORD, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>DefaultSelection, Modify, Verify</dd>
  * </dl>
@@ -41,7 +41,16 @@
 	static final int INNER_BORDER = 2;
 	static final int ITER_SIZEOF = OS.GtkTextIter_sizeof();
 	
+	/**
+	* The maximum number of characters that can be entered
+	* into a text widget.
+	*/
 	public final static int LIMIT;
+	/**
+	* The delimiter used by multi-line text widgets.  When text
+	* is queried and from the widget, it will be delimited using
+	* this delimiter.
+	*/
 	public final static String DELIMITER;
 	/*
 	* These values can be different on different platforms.
@@ -503,6 +512,8 @@
  * default action of the text widget when the user
  * double clicks.
  * </p>
+ * 
+ * @return whether or not double click is enabled
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -521,6 +532,8 @@
  * displayed when the user enters text or the
  * text is changed by the programmer.
  * </p>
+ * 
+ * @return the echo character
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -540,6 +553,8 @@
 /**
  * Gets the editable state.
  *
+ * @return whether or not the reciever is editable
+ * 
  * @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>
@@ -606,7 +621,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -744,7 +759,8 @@
 }
 
 /**
- * Gets a range of text.
+ * Gets a range of text.  Returns an empty string if the
+ * start of the range is greater than the end.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N-1 where N is
@@ -1311,10 +1327,10 @@
 
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1472,7 +1488,7 @@
  * SINGLE and the argument contains multiple lines of text, the result of this
  * operation is undefined and may vary from platform to platform.
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolBar.java
index c487a3e..bc90357 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolBar.java
@@ -72,8 +72,8 @@
  * @see SWT#HORIZONTAL
  * @see SWT#SHADOW_OUT
  * @see SWT#VERTICAL
- * @see Widget#checkSubclass
- * @see Widget#getStyle
+ * @see Widget#checkSubclass()
+ * @see Widget#getStyle()
  */
 public ToolBar (Composite parent, int style) {
 	super (parent, checkStyle (style));
@@ -240,7 +240,7 @@
 }
 
 /**
- * Returns an array of <code>TabItem</code>s which are the items
+ * Returns an array of <code>ToolItem</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/gtk/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java
index 3b5e1c5..5f20c2e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java
@@ -786,7 +786,7 @@
  * @param rectangles the bounds of the rectangles to be drawn
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of rectangles is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the set of rectangles is null or contains a null rectangle</li>
  * </ul>
  * @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/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java
index df7df68..a52f5c9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java
@@ -16,6 +16,22 @@
 import org.eclipse.swt.internal.*;
 import org.eclipse.swt.internal.gtk.*;
 
+/**
+ * Instances of this class represent icons that can be placed on the
+ * system tray or task bar status area.
+ *
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>DefaultSelection, MenuDetect, Selection</dd>
+ * </dl>
+ * <p>
+ * IMPORTANT: This class is <em>not</em> intended to be subclassed.
+ * </p>
+ * 
+ * @since 3.0
+ */
 public class TrayItem extends Item {
 	Tray parent;
 	String toolTipText;
@@ -23,12 +39,66 @@
 	int /*long*/ imageHandle;
 	int /*long*/ tooltipsHandle;
 
+/**
+ * Constructs a new instance of this class given its parent
+ * (which must be a <code>Tray</code>) and a style value
+ * describing its behavior and appearance. The item is added
+ * to the end of the items maintained by its parent.
+ * <p>
+ * The style value is either one of the style constants defined in
+ * class <code>SWT</code> which is applicable to instances of this
+ * class, or must be built by <em>bitwise OR</em>'ing together 
+ * (that is, using the <code>int</code> "|" operator) two or more
+ * of those <code>SWT</code> style constants. The class description
+ * lists the style constants that are applicable to the class.
+ * Style bits are also inherited from superclasses.
+ * </p>
+ *
+ * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param style the style of control to construct
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
+ * </ul>
+ *
+ * @see SWT
+ * @see Widget#checkSubclass
+ * @see Widget#getStyle
+ */
 public TrayItem (Tray parent, int style) {
 	super (parent, style);
 	this.parent = parent;
 	createWidget (parent.getItemCount ());
 }
 
+/**
+ * Adds the listener to the collection of listeners who will
+ * be notified when the receiver is selected, by sending
+ * it one of the messages defined in the <code>SelectionListener</code>
+ * interface.
+ * <p>
+ * <code>widgetSelected</code> is called when the receiver is selected
+ * <code>widgetDefaultSelected</code> is called when the receiver is double-clicked
+ * </p>
+ *
+ * @param listener the listener which should be notified
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener 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>
+ *
+ * @see SelectionListener
+ * @see #removeSelectionListener
+ * @see SelectionEvent
+ */
 public void addSelectionListener(SelectionListener listener) {
 	checkWidget ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -81,6 +151,17 @@
 	OS.g_free (clientEvent);
 }
 
+/**
+ * Returns the receiver's tool tip text, or null if it has
+ * not been set.
+ *
+ * @return the receiver's tool tip 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 getToolTipText () {
 	checkWidget ();
 	return toolTipText;
@@ -108,6 +189,17 @@
 	OS.g_signal_connect (handle, OS.button_press_event, display.windowProc3, BUTTON_PRESS_EVENT);
  }
 
+/**
+ * Returns <code>true</code> if the receiver is visible and 
+ * <code>false</code> otherwise.
+ *
+ * @return the receiver's visibility
+ *
+ * @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 boolean getVisible () {
 	checkWidget ();
 	return OS.GTK_WIDGET_VISIBLE (handle);
@@ -127,6 +219,23 @@
 	handle = 0;
 }
 
+/**
+ * Removes the listener from the collection of listeners who will
+ * be notified when the receiver is selected.
+ *
+ * @param listener the listener which should no longer be notified
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener 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>
+ *
+ * @see SelectionListener
+ * @see #addSelectionListener
+ */
 public void removeSelectionListener (SelectionListener listener) {
 	checkWidget ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -135,6 +244,19 @@
 	eventTable.unhook (SWT.DefaultSelection, listener);
 }
 
+/**
+ * Sets the receiver's image.
+ *
+ * @param image the new image
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the image 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 setImage (Image image) {
 	checkWidget ();
 	if (image != null && image.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -151,6 +273,17 @@
 	}
 }
 
+/**
+ * Sets the receiver's tool tip text to the argument, which
+ * may be null indicating that no tool tip text should be shown.
+ *
+ * @param value the new tool tip text (or null)
+ *
+ * @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 setToolTipText (String string) {
 	checkWidget ();
 	toolTipText = string;
@@ -167,6 +300,17 @@
 	OS.gtk_tooltips_set_tip (tooltipsHandle, handle, buffer, null);
 }
 
+/**
+ * Makes the receiver visible if the argument is <code>true</code>,
+ * and makes it invisible otherwise. 
+ *
+ * @param visible the new visibility 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 void setVisible (boolean visible) {
 	checkWidget ();
 	if (OS.GTK_WIDGET_VISIBLE (handle) == visible) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
index e5d0af6..78983db 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
@@ -471,7 +471,7 @@
 }
 
 /**
- * Returns the number of items contained in the receiver
+ * Returns the items contained in the receiver
  * that are direct item children of the receiver.  These
  * are the roots of the tree.
  * <p>
@@ -480,7 +480,7 @@
  * not affect the receiver. 
  * </p>
  *
- * @return the number of items
+ * @return the items
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -934,7 +934,9 @@
 }
 
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -976,14 +978,17 @@
 
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the item has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</li>
  * </ul>
  * @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/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
index 7fe4fae..965c814 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
@@ -492,7 +492,7 @@
  * Sets the grayed state of the receiver.
  * <p>
  *
- * @param checked the new grayed state
+ * @param grayed the new grayed state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -605,11 +605,7 @@
 	OS.gtk_tree_store_set (parent.modelHandle, handle, Tree.PIXBUF_COLUMN, pixbuf, -1);
 }
 
-/**
- * This label will be displayed to the right of the bitmap, 
- * or, if the receiver doesn't have a bitmap to the right of 
- * the horizontal hierarchy connector line.
- */
+
 public void setText (String string) {
 	checkWidget();
 	if (string == null) error (SWT.ERROR_NULL_ARGUMENT);
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 2a8fbb8..fba6c9f 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
@@ -84,7 +84,7 @@
  * </p>
  *
  * @param device the device on which to allocate the color
- * @param RGB the RGB values of the desired color
+ * @param rgb the RGB values of the desired color
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -184,6 +184,8 @@
 /**
  * Returns an <code>RGB</code> representing the receiver.
  *
+ * @return the RGB for the color
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
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 f5690e1..ef3dc2c 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
@@ -130,7 +130,7 @@
 /**	 
  * Constructs a new cursor given a device, image and mask
  * data describing the desired cursor appearance, and the x
- * and y co-ordinates of the <em>hotspot</em> (that is, the point
+ * and y coordinates of the <em>hotspot</em> (that is, the point
  * within the area covered by the cursor which is considered
  * to be where the on-screen pointer is "pointing").
  * <p>
@@ -234,6 +234,33 @@
 	if (handle == 0) SWT.error(SWT.ERROR_NO_HANDLES);
 	if (device.tracking) device.new_Object(this);
 }
+/**	 
+ * Constructs a new cursor given a device, image data describing
+ * the desired cursor appearance, and the x and y coordinates of
+ * the <em>hotspot</em> (that is, the point within the area
+ * covered by the cursor which is considered to be where the
+ * on-screen pointer is "pointing").
+ * <p>
+ * You must dispose the cursor when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the cursor
+ * @param source the image data for the cursor
+ * @param hotspotX the x coordinate of the cursor's hotspot
+ * @param hotspotY the y coordinate of the cursor's hotspot
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the hotspot is outside the bounds of the
+ * 		 image</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java
index e35e9b8..3e97b42 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java
@@ -380,7 +380,7 @@
  * <code>faceName</code> is null, all fonts will be returned.
  *
  * @param faceName the name of the font to look for, or null
- * @param scalable true if scalable fonts should be returned.
+ * @param scalable if true only scalable fonts are returned, otherwise only non-scalable fonts are returned.
  * @return the matching font data
  *
  * @exception SWTException <ul>
@@ -641,7 +641,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public abstract void internal_dispose_GC (int handle, GCData data);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java
index a2faf9d..de3ce9f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java
@@ -15,7 +15,6 @@
  
 /**
  * Instances of this class describe operating system fonts.
- * Only the public API of this type is platform independent.
  * <p>
  * For platform-independent behaviour, use the get and set methods
  * corresponding to the following properties:
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 858e728..f34bc87 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
@@ -19,6 +19,17 @@
  * Class <code>GC</code> is where all of the drawing capabilities that are 
  * supported by SWT are located. Instances are used to draw on either an 
  * <code>Image</code>, a <code>Control</code>, or directly on a <code>Display</code>.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
+ * </dl>
+ * 
+ * <p>
+ * The SWT drawing coordinate system is the two-dimensional space with the origin
+ * (0,0) at the top left corner of the drawing area and with (x,y) values increasing
+ * to the right and downward respectively.
+ * </p>
+ * 
  * <p>
  * Application code must explicitly invoke the <code>GC.dispose()</code> 
  * method to release the operating system resources managed by each instance
@@ -26,6 +37,10 @@
  * important on Windows95 and Windows98 where the operating system has a limited
  * number of device contexts available.
  * </p>
+ * 
+ * <p>
+ * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
+ * </p>
  *
  * @see org.eclipse.swt.events.PaintEvent
  */
@@ -65,6 +80,32 @@
 public GC(Drawable drawable) {
 	this(drawable, 0);
 }
+/**	 
+ * Constructs a new instance of this class which has been
+ * configured to draw on the specified drawable. Sets the
+ * foreground and background color in the GC to match those
+ * in the drawable.
+ * <p>
+ * You must dispose the graphics context when it is no longer required. 
+ * </p>
+ * 
+ * @param drawable the drawable to draw on
+ * @param style the style of GC to construct
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the drawable is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if there is no current device</li>
+ *    <li>ERROR_INVALID_ARGUMENT
+ *          - if the drawable is an image that is not a bitmap or an icon
+ *          - if the drawable is an image or printer that is already selected
+ *            into another graphics context</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li>
+ * </ul>
+ *  
+ * @since 2.1.2
+ */
 public GC(Drawable drawable, int style) {
 	if (drawable == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	GCData data = new GCData();
@@ -127,6 +168,7 @@
  * Copies a rectangular area of the receiver at the specified
  * position into the image, which must be of type <code>SWT.BITMAP</code>.
  *
+ * @param image the image to copy into
  * @param x the x coordinate in the receiver of the area to be copied
  * @param y the y coordinate in the receiver of the area to be copied
  *
@@ -217,9 +259,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -688,6 +727,23 @@
 	}
 	OS.XDrawArc(data.display, data.drawable, handle, x, y, width, height, 0, 23040);
 }
+/** 
+ * Draws a pixel, using the foreground color, at the specified
+ * point (<code>x</code>, <code>y</code>).
+ * <p>
+ * Note that the receiver's line attributes do not affect this
+ * operation.
+ * </p>
+ *
+ * @param x the point's x coordinate
+ * @param y the point's y coordinate
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *  
+ * @since 3.0
+ */
 public void drawPoint (int x, int y) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.XDrawPoint(data.display, data.drawable, handle, x, y);
@@ -1143,9 +1199,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -1371,7 +1424,7 @@
  * Fills the interior of the specified rectangle, using the receiver's
  * background color. 
  *
- * @param rectangle the rectangle to be filled
+ * @param rect the rectangle to be filled
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
@@ -2176,6 +2229,24 @@
 	OS.XGetGCValues(data.display, handle, OS.GCLineWidth, values);
 	return values.line_width;
 }
+/**
+ * Returns the receiver's style information.
+ * <p>
+ * Note that the value which is returned by this method <em>may
+ * not match</em> the value which was provided to the constructor
+ * when the receiver was created. This can occur when the underlying
+ * operating system does not support a particular combination of
+ * requested styles. 
+ * </p>
+ *
+ * @return the style bits
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *   
+ * @since 2.1.2
+ */
 public int getStyle () {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.style;
@@ -2387,7 +2458,7 @@
  * by drawing operations to the region specified
  * by the argument.
  *
- * @param rect the clipping region.
+ * @param region the clipping region.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
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 f38b67c..65338d8 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
@@ -180,6 +180,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon, or
  *          is otherwise in an invalid state</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the Image is not supported</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -510,6 +511,9 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li>
+ * </ul>
  */
 public Image(Device device, ImageData image) {
 	if (device == null) device = Device.getDevice();
@@ -588,6 +592,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -619,6 +624,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -1078,7 +1084,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int gc, GCData data) {
@@ -1285,7 +1291,7 @@
  * these cases. For example:
  * <pre>
  *    Button b = new Button();
- *    image.setBackground(b.getBackground());>
+ *    image.setBackground(b.getBackground());
  *    b.setImage(image);
  * </pre>
  * </p><p>
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 59fc795..5e181ef 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
@@ -46,6 +46,25 @@
 public Region () {
 	this(null);
 }
+/**
+ * Constructs a new empty region.
+ * <p>
+ * You must dispose the region when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the region
+ *
+* @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ *
+ * @see #dispose
+ * 
+ * @since 3.0
+ */
 public Region (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -229,6 +248,22 @@
 public int hashCode () {
 	return handle;
 }
+/**
+ * Intersects the given rectangle to the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to intersect with the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect (Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -244,6 +279,23 @@
 	OS.XIntersectRegion(handle, rectRgn, handle);
 	OS.XDestroyRegion(rectRgn);
 }
+/**
+ * Intersects all of the rectangles which make up the area covered
+ * by the argument to the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to intersect
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect (Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -327,7 +379,7 @@
  * Subtracts the given polygon from the collection of rectangles
  * the receiver maintains to describe its area.
  *
- * param pointArray points that describe the polygon to merge with the receiver
+ * @param pointArray points that describe the polygon to merge with the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
@@ -349,6 +401,22 @@
 	OS.XSubtractRegion(handle, polyRgn, handle);
 	OS.XDestroyRegion(polyRgn);
 }
+/**
+ * Subtracts the given rectangle from the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to subtract from the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract (Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -364,6 +432,23 @@
 	OS.XSubtractRegion(handle, rectRgn, handle);
 	OS.XDestroyRegion(rectRgn);
 }
+/**
+ * Subtracts all of the rectangles which make up the area covered
+ * by the argument from the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to subtract
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract (Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
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 5158dd3..d706332 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
@@ -14,6 +14,23 @@
 import org.eclipse.swt.internal.motif.*;
 import org.eclipse.swt.*;
 
+/**
+ * <code>TextLayout</code> is a graphic object that represents
+ * styled text.
+ *<p>
+ * Instances of this class provide support for drawing, cursor
+ * navigation, hit testing, text wrapping, alignment, tab expansion
+ * line breaking, etc.  These are aspects required for rendering internationalized text.
+ * </p>
+ * 
+ * <p>
+ * Application code must explicitly invoke the <code>TextLayout#dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ *  @since 3.0
+ */
 public final class TextLayout {
 	Device device;
 	Font font;
@@ -37,6 +54,20 @@
 		boolean lineBreak, softBreak, tab;
 	}
 	
+/**	 
+ * Constructs a new instance of this class on the given device.
+ * <p>
+ * You must dispose the text layout when it is no longer required. 
+ * </p>
+ * 
+ * @param device the device on which to allocate the text layout
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public TextLayout (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -215,6 +246,10 @@
 	}
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the text layout. Applications must dispose of all allocated text layouts.
+ */
 public void dispose () {
 	if (device == null) return;
 	freeRuns();
@@ -229,10 +264,38 @@
 	device = null;
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw (GC gc, int x, int y) {
 	draw(gc, x, y, -1, -1, null, null);
 }
 
+/**
+ * Draws the receiver's text using the specified GC at the specified
+ * point.
+ * 
+ * @param gc the GC to draw
+ * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn
+ * @param selectionStart the offset where the selections starts, or -1 indicating no selection
+ * @param selectionEnd the offset where the selections ends, or -1 indicating no selection
+ * @param selectionForeground selection foreground, or NULL to use the system default color
+ * @param selectionBackground selection background, or NULL to use the system default color
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) {
 	checkLayout();
 	computeRuns();
@@ -329,16 +392,48 @@
 	runs = null;
 }
 
+/** 
+ * Returns the receiver's horizontal text alignment, which will be one
+ * of <code>SWT.LEFT</code>, <code>SWT.CENTER</code> or
+ * <code>SWT.RIGHT</code>.
+ *
+ * @return the alignment used to positioned text horizontally
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getAlignment () {
 	checkLayout();
 	return alignment;
 }
 
+/**
+ * Returns the ascent of the receiver.
+ *
+ * @return the ascent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ *  @see #getDescent()
+ * 
+ */
 public int getAscent () {
 	checkLayout();
 	return ascent;
 }
 
+/**
+ * Returns the bounds of the receiver.
+ * 
+ * @return the bounds of the receiver
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds () {
 	checkLayout();
 	computeRuns();
@@ -353,6 +448,20 @@
 	return new Rectangle (0, 0, width, lineY[lineY.length - 1]);
 }
 
+/**
+ * Returns the bounds for the specified range of characters. The
+ * bounds is the smallest rectangle that encompasses all characters
+ * in the range. The start and end offsets are inclusive and will be
+ * clamped if out of range.
+ * 
+ * @param start the start offset
+ * @param end the end offset
+ * @return the bounds of the character range
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getBounds (int start, int end) {
 	checkLayout();
 	computeRuns();
@@ -378,11 +487,32 @@
 	return rect;
 }
 
+/**
+ * Returns the descent of the receiver.
+ *
+ * @return the descent
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAscent()
+ */
 public int getDescent () {
 	checkLayout();
 	return descent;
 }
 
+/** 
+ * Returns the default font currently being used by the receiver
+ * to draw and measure text.
+ *
+ * @return the receiver's font
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Font getFont () {
 	checkLayout();
 	return font;
@@ -423,6 +553,20 @@
 	return fontStruct;
 }
 
+/**
+ * Returns the embedding level for the specified character offset. The
+ * embedding level is usually used to determine the directionality of a
+ * character in bidirectional text.
+ * 
+ * @param offset the charecter offset
+ * @return the embedding level
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ */
 public int getLevel (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -430,6 +574,17 @@
 	return 0;
 }
 
+/**
+ * Returns the line offsets.  Each value in the array is the
+ * offset for the first character in a line except for the last
+ * value, which contains the length of the text.
+ * 
+ * @return the line offsets
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getLineOffsets () {
 	checkLayout();
 	computeRuns();
@@ -438,6 +593,19 @@
 	return offsets;
 }
 
+/**
+ * Returns the bounds of the line for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the line bounds 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public Rectangle getLineBounds(int lineIndex) {
 	checkLayout();
 	computeRuns();
@@ -453,12 +621,36 @@
 	return new Rectangle (x, y, width, height);
 }
 
+/**
+ * Returns the receiver's line count. This includes lines caused
+ * by wrapping.
+ *
+ * @return the line count
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineCount () {
 	checkLayout();
 	computeRuns();
 	return runs.length;
 }
 
+/**
+ * Returns the index of the line that contains the specified
+ * character offset.
+ * 
+ * @param offset the character offset
+ * @return the line index
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the character offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getLineIndex (int offset) {
 	checkLayout();
 	computeRuns();
@@ -472,6 +664,19 @@
 	return runs.length - 1;
 }
 
+/**
+ * Returns the font metrics for the specified line index.
+ * 
+ * @param lineIndex the line index
+ * @return the font metrics 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the line index is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public FontMetrics getLineMetrics (int lineIndex) {
 	checkLayout();
 	computeRuns();
@@ -505,6 +710,22 @@
 	return metrics;
 }
 
+/**
+ * Returns the location for the specified character offset. The
+ * <code>trailing</code> argument indicates whether the offset
+ * corresponds to the leading or trailing edge of the cluster.
+ * 
+ * @param offset the character offset
+ * @param trailing the trailing flag
+ * @return the location of the character offset
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getOffset(Point, int[])
+ * @see #getOffset(int, int, int[])
+ */
 public Point getLocation (int offset, boolean trailing) {
 	checkLayout();
 	computeRuns();
@@ -559,6 +780,24 @@
 	return device.getSystemFont();
 }
 
+/**
+ * Returns the next offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the next offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getPreviousOffset(int, int)
+ */
 public int getNextOffset (int offset, int movement) {
 	checkLayout();
 	computeRuns();
@@ -585,12 +824,51 @@
 	return offset;
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param point the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset (Point point, int[] trailing) {
 	checkLayout();
 	if (point == null) SWT.error (SWT.ERROR_NULL_ARGUMENT);
 	return getOffset (point.x, point.y, trailing);
 }
 
+/**
+ * Returns the character offset for the specified point.  When
+ * the point is over a cluster composed by multiple characters,
+ * the trailing argument will determine for each character in the
+ * cluster whether it is under the point.
+ * 
+ * @param x the x coordinate of the point
+ * @param y the y coordinate of the point
+ * @param trailing the trailing buffer
+ * @return the character offset
+ *  
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getLocation(int, boolean)
+ */
 public int getOffset (int x, int y, int[] trailing) {
 	checkLayout();
 	computeRuns();
@@ -644,11 +922,38 @@
 	return lineOffset[line + 1];
 }
 
+/**
+ * Returns the orientation of the receiver.
+ *
+ * @return the orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getOrientation () {
 	checkLayout();
 	return orientation;
 }
 
+/**
+ * Returns the previous offset for the specified offset and movement
+ * type.  The movement is one of <code>SWT.MOVEMENT_CHAR</code>, 
+ * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>.
+ * 
+ * @param offset the start offset
+ * @param movement the movement type 
+ * @return the previous offset
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the offset is out of range</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getNextOffset(int, int)
+ */
 public int getPreviousOffset (int offset, int movement) {
 	checkLayout();
 	computeRuns();
@@ -676,16 +981,44 @@
 	return offset;
 }
 
+/**
+ * Returns the text segments offsets of the receiver.
+ *
+ * @return the text segments offsets
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getSegments() {
 	checkLayout();
 	return segments;
 }
 
+/**
+ * Returns the line spacing of the receiver.
+ *
+ * @return the line spacing
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getSpacing () {
 	checkLayout();	
 	return lineSpacing;
 }
 
+/**
+ * Gets the style of the receiver at the specified offset.
+ *
+ * @param offset the text offset
+ * @return the style or <code>null</code> if not set
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public TextStyle getStyle (int offset) {
 	checkLayout();
 	int length = text.length();
@@ -699,21 +1032,59 @@
 	return null;
 }
 
+/**
+ * Returns the tab list of the receiver.
+ *
+ * @return the tab list
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int[] getTabs () {
 	checkLayout();
 	return tabs;
 }
 
+/**
+ * Gets the receiver's text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's text
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public String getText () {
 	checkLayout();
 	return text;
 }
 
+/**
+ * Returns the width of the receiver.
+ *
+ * @return the width
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public int getWidth () {
 	checkLayout();
 	return wrapWidth;
 }
 
+/**
+ * Returns <code>true</code> if the text layout has been disposed,
+ * and <code>false</code> otherwise.
+ * <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.
+ *
+ * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
+ */
 public boolean isDisposed () {
 	return device == null;
 }
@@ -808,6 +1179,24 @@
 	OS.XmStringFree(xmString);
 }
 
+/**
+ * Sets the text alignment for the receiver. The alignment controls
+ * how a line of text is positioned horizontally. The argument should
+ * be one of <code>SWT.LEFT</code>, <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>.
+ * <p>
+ * The default alignment is <code>SWT.LEFT</code>.  Note that the receiver's
+ * width must be set in order to use <code>SWT.RIGHT</code> or <code>SWT.CENTER</code>
+ * alignment.
+ *</p>
+ *
+ * @param alignment the new alignment 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setWidth(int)
+ */
 public void setAlignment (int alignment) {
 	checkLayout();
 	int mask = SWT.LEFT | SWT.CENTER | SWT.RIGHT;
@@ -818,6 +1207,23 @@
 	this.alignment = alignment;
 }
 
+/**
+ * Sets the ascent of the receiver. The ascent is distance in pixels
+ * from the baseline to the top of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * ascent is calculated from the line fonts.
+ *
+ * @param ascent the new ascent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the ascent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setDescent(int)
+ */
 public void setAscent (int ascent) {
 	checkLayout();
 	if (ascent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -826,6 +1232,23 @@
 	this.ascent = ascent;
 }
 
+/**
+ * Sets the descent of the receiver. The descent is distance in pixels
+ * from the baseline to the bottom of the line and it is applied to all
+ * lines. The default value is <code>-1</code> which means that the
+ * descent is calculated from the line fonts.
+ *
+ * @param descent the new descent
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the descent is less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAscent(int)
+ */
 public void setDescent (int descent) {
 	checkLayout();
 	if (descent < -1) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -834,6 +1257,22 @@
 	this.descent = descent;
 }
 
+/** 
+ * Sets the default font which will be used by the receiver
+ * to draw and measure text. If the
+ * argument is null, then a default font appropriate
+ * for the platform will be used instead. Note that a text
+ * style can override the default font.
+ *
+ * @param font the new font for the receiver, or null to indicate a default font
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setFont (Font font) {
 	checkLayout ();
 	if (font != null && font.isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -846,6 +1285,17 @@
 	defaultDescent = fontStruct.descent;
 }
 
+/**
+ * Sets the orientation of the receiver, which must be one
+ * of <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
+ * <p>
+ *
+ * @param orientation new orientation style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setOrientation (int orientation) {
 	checkLayout();
 	int mask = SWT.RIGHT_TO_LEFT | SWT.LEFT_TO_RIGHT;
@@ -855,6 +1305,19 @@
 	this.orientation = orientation;
 }
 
+/**
+ * Sets the line spacing of the receiver.  The line spacing
+ * is the space left between lines.
+ *
+ * @param spacing the new line spacing 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the spacing is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSpacing (int spacing) {
 	checkLayout();
 	if (spacing < 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -863,6 +1326,23 @@
 	this.lineSpacing = spacing;
 }
 
+/**
+ * Sets the offsets of the receiver's text segments. Text segments are used to
+ * override the default behaviour of the bidirectional algorithm.
+ * Bidirectional reordering can happen within a text segment but not 
+ * between two adjacent segments.
+ * Each text segment is determined by two consecutive offsets in the 
+ * <code>segments</code> arrays. The first element of the array should 
+ * always be zero and the last one should always be equals to length of
+ * the text.
+ * <p>
+ * 
+ * @param segments the text segments offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setSegments(int[] segments) {
 	checkLayout();
 	if (this.segments == null && segments == null) return;
@@ -879,6 +1359,19 @@
 	this.segments = segments;
 }
 
+/**
+ * Sets the style of the receiver for the specified range.  Styles previously
+ * set for that range will be overwritten.  The start and end offsets are
+ * inclusive and will be clamped if out of range.
+ * 
+ * @param style the style
+ * @param start the start offset
+ * @param end the end offset
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setStyle (TextStyle style, int start, int end) {
 	checkLayout();
 	int length = text.length();
@@ -942,6 +1435,17 @@
 	}
 }
 
+/**
+ * Sets the receiver's tab list. Each value in the tab list specifies
+ * the space in pixels from the origin of the text layout to the respective
+ * tab stop.  The last tab stop width is repeated continuously.
+ * 
+ * @param tabs the new tab list
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setTabs (int[] tabs) {
 	checkLayout();
 	if (this.tabs == null && tabs == null) return;
@@ -958,6 +1462,18 @@
 	this.tabs = tabs;
 } 
 
+/**
+ * Sets the receiver's text.
+ *
+ * @param text the new text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the text is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setText (String text) {
 	checkLayout();
 	if (text == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -970,6 +1486,22 @@
 	styles[1].start = text.length();
 }
 
+/**
+ * Sets the line width of the receiver, which determines how
+ * text should be wrapped and aligned. The default value is
+ * <code>-1</code> which means wrapping is disabled.
+ *
+ * @param width the new width 
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the width is <code>0</code> or less than <code>-1</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlignment(int)
+ */
 public void setWidth (int width) {
 	checkLayout();
 	if (width < -1 || width == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
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 f6cb63e..5395a3e 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
@@ -406,7 +406,8 @@
 }
 /**
  * Returns the receiver's text, which will be an empty
- * string if it has never been set.
+ * string if it has never been set or if the receiver is
+ * an <code>ARROW</code> button.
  *
  * @return the receiver's text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Caret.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Caret.java
index fc8b37a..de11a10 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Caret.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Caret.java
@@ -352,7 +352,7 @@
  * to the image specified by the argument, or to the default
  * which is a filled rectangle if the argument is null
  *
- * @param font the new font (or null)
+ * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
@@ -425,7 +425,6 @@
  * Sets the receiver's size to the point specified by the argument.
  *
  * @param size the new extent for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ColorDialog.java
index ef01b79..7d9ae22 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ColorDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ColorDialog.java
@@ -51,7 +51,7 @@
 /**
  * Constructs a new instance of this class given only its parent.
  *
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a composite control which will be the parent of the new instance
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -447,7 +447,7 @@
  * Sets the receiver's selected color to be the argument.
  *
  * @param rgb the new RGB value for the selected color, may be
- *        null to let the platform to select a default when
+ *        null to let the platform select a default when
  *        open() is called
  * @see PaletteData#getRGBs
  */
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 4cefab5..011a4de 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
@@ -598,7 +598,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -804,6 +804,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to begin the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1148,6 +1149,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1180,6 +1182,9 @@
  *
  * @param items the array of items
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the items array 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>
@@ -1229,10 +1234,10 @@
 }
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1250,7 +1255,7 @@
  * start of the selection and whose y coordinate is the end
  * of the selection. 
  *
- * @param a point representing the new selection start and end
+ * @param selection a point representing the new selection start and end
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -1304,7 +1309,7 @@
  * display incorrectly.
  * </p>
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
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 abb6b09..49f1573 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
@@ -21,7 +21,7 @@
  * of containing other controls.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
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 cdc2b07..9c8b5c8 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
@@ -27,7 +27,7 @@
  * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
  * <dt><b>Events:</b>
  * <dd>FocusIn, FocusOut, Help, KeyDown, KeyUp, MouseDoubleClick, MouseDown, MouseEnter,
- *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize</dd>
+ *     MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd>
  * </dl>
  * <p>
  * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified.
@@ -35,8 +35,6 @@
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
- * 
- * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
  */
 public abstract class Control extends Widget implements Drawable {
 	Composite parent;
@@ -640,7 +638,9 @@
 }
 /**
  * Returns a rectangle describing the receiver's size and location
- * relative to its parent (or its display if its parent is null).
+ * relative to its parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the location is
+ * relative to the display.
  *
  * @return the receiver's bounding rectangle
  *
@@ -832,7 +832,9 @@
 }
 /**
  * Returns a point describing the receiver's location relative
- * to its parent (or its display if its parent is null).
+ * to its parent (or its display if its parent is null), unless
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @return the receiver's location
  *
@@ -867,6 +869,13 @@
 	checkWidget();
 	return menu;
 }
+/**
+ * Returns the receiver's monitor.
+ * 
+ * @return the receiver's monitor
+ * 
+ * @since 3.0
+ */
 public Monitor getMonitor () {
 	checkWidget();
 	Monitor [] monitors = display.getMonitors ();
@@ -1115,7 +1124,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int xGC, GCData data) {
@@ -1261,7 +1270,7 @@
  * the top of the drawing order will not be covered by other
  * controls even if they occupy intersecting areas.
  *
- * @param the sibling control (or null)
+ * @param control the sibling control (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the control has been disposed</li> 
@@ -1270,6 +1279,8 @@
  *    <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 #moveBelow
  */
 public void moveAbove (Control control) {
 	checkWidget();
@@ -1286,7 +1297,7 @@
  * the bottom of the drawing order will be covered by all other
  * controls which occupy intersecting areas.
  *
- * @param the sibling control (or null)
+ * @param control the sibling control (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the control has been disposed</li> 
@@ -1295,6 +1306,8 @@
  *    <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 #moveAbove
  */
 public void moveBelow (Control control) {
 	checkWidget();
@@ -1341,6 +1354,8 @@
  * manager caches can be retained. 
  * </p>
  *
+ * @param changed whether or not the receiver's contents have changed
+ * 
  * @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>
@@ -1374,7 +1389,8 @@
 /**
  * Causes the entire bounds of the receiver to be marked
  * as needing to be redrawn. The next time a paint request
- * is processed, the control will be completely painted.
+ * is processed, the control will be completely painted,
+ * including the background.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1382,6 +1398,11 @@
  * </ul>
  *
  * @see #update
+ * @see PaintListener
+ * @see SWT#Paint
+ * @see SWT#NO_BACKGROUND
+ * @see SWT#NO_REDRAW_RESIZE
+ * @see SWT#NO_MERGE_PAINTS
  */
 public void redraw () {
 	checkWidget();
@@ -1391,11 +1412,12 @@
  * Causes the rectangular area of the receiver specified by
  * the arguments to be marked as needing to be redrawn. 
  * The next time a paint request is processed, that area of
- * the receiver will be painted. If the <code>all</code> flag
- * is <code>true</code>, any children of the receiver which
- * intersect with the specified area will also paint their
- * intersecting areas. If the <code>all</code> flag is 
- * <code>false</code>, the children will not be painted.
+ * the receiver will be painted, including the background.
+ * If the <code>all</code> flag is <code>true</code>, any
+ * children of the receiver which intersect with the specified
+ * area will also paint their intersecting areas. If the
+ * <code>all</code> flag is <code>false</code>, the children
+ * will not be painted.
  *
  * @param x the x coordinate of the area to draw
  * @param y the y coordinate of the area to draw
@@ -1409,6 +1431,11 @@
  * </ul>
  *
  * @see #update
+ * @see PaintListener
+ * @see SWT#Paint
+ * @see SWT#NO_BACKGROUND
+ * @see SWT#NO_REDRAW_RESIZE
+ * @see SWT#NO_MERGE_PAINTS
  */
 public void redraw (int x, int y, int width, int height, boolean all) {
 	checkWidget ();
@@ -1893,7 +1920,9 @@
  * Sets the receiver's size and location to the rectangular
  * area specified by the arguments. The <code>x</code> and 
  * <code>y</code> arguments are relative to the receiver's
- * parent (or its display if its parent is null).
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the <code>x</code>
+ * and <code>y</code> arguments are relative to the display.
  * <p>
  * Note: Attempting to set the width or height of the
  * receiver to a negative number will cause that
@@ -2030,7 +2059,8 @@
 }
 /**
  * Causes the receiver to have the <em>keyboard focus</em>, 
- * such that all keyboard events will be delivered to it.
+ * such that all keyboard events will be delivered to it.  Focus
+ * reassignment will respect applicable platform constraints.
  *
  * @return <code>true</code> if the control got focus, and <code>false</code> if it was unable to.
  *
@@ -2131,7 +2161,9 @@
 /**
  * Sets the receiver's location to the point specified by
  * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null).
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @param x the new x coordinate for the receiver
  * @param y the new y coordinate for the receiver
@@ -2147,8 +2179,10 @@
 }
 /**
  * Sets the receiver's location to the point specified by
- * the argument which is relative to the receiver's
- * parent (or its display if its parent is null).
+ * the arguments which are relative to the receiver's
+ * parent (or its display if its parent is null), unless 
+ * the receiver is a shell. In this case, the point is 
+ * relative to the display. 
  *
  * @param location the new location for the receiver
  *
@@ -2298,7 +2332,6 @@
  * </p>
  *
  * @param size the new size for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -2731,6 +2764,8 @@
  * </ul>
  *
  * @see #redraw
+ * @see PaintListener
+ * @see SWT#Paint
  */
 public void update () {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java
index 97860a5..60d5a08 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java
@@ -21,6 +21,11 @@
  * shares a significant amount of code with this class,
  * and is a subclass.
  * <p>
+ * IMPORTANT: This class was intended to be abstract and
+ * should <em>never</em> be referenced or instantiated.
+ * Instead, the class <code>Shell</code> should be used.
+ * </p>
+ * <p>
  * Instances are always displayed in one of the maximized, 
  * minimized or normal states:
  * <ul>
@@ -406,7 +411,7 @@
  * disposed, the receiver's default button will be set to
  * null. 
  *
- * @param the new default button
+ * @param button the new default button
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the button has been disposed</li> 
@@ -465,6 +470,29 @@
 	_setImages (image != null ? new Image [] {image} : null);
 }
 
+/**
+ * Sets the receiver's images to the argument, which may
+ * be an empty array. Images are typically displayed by the
+ * window manager when the instance is marked as iconified,
+ * and may also be displayed somewhere in the trim when the
+ * instance is in normal or maximized states. Depending where
+ * the icon is displayed, the platform chooses the icon with
+ * the "best" size. It is expected that the array will contain
+ * the same icon rendered at different resolutions.
+ * 
+ * @param images the new image array
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of images is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the images 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.0
+ */
 public void setImages (Image [] images) {
 	checkWidget ();
 	if (images == null) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -489,7 +517,7 @@
  * always. This should be avoided if possible.
  * </p>
  *
- * @param the new maximized state
+ * @param maximized the new maximized state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -606,7 +634,7 @@
  * always. This should be avoided if possible.
  * </p>
  *
- * @param the new maximized state
+ * @param minimized the new maximized state
  *
  * @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/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java
index 316fc5a..265bcd7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -18,6 +18,12 @@
 /**
  * Instances of this class allow the user to navigate
  * the file system and select a directory.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>(none)</dd>
+ * </dl>
  * <p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
@@ -30,16 +36,7 @@
 	static final String SEPARATOR = System.getProperty ("file.separator");
 	
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -66,15 +63,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
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 ad5b18e..735c2f0 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
@@ -89,7 +89,7 @@
  * @see #wake
  * @see #readAndDispatch
  * @see #sleep
- * @see #dispose
+ * @see Device#dispose
  */
 public class Display extends Device {
 
@@ -449,6 +449,29 @@
 	indexTable [oldSlot] = -2;
 	widgetTable [oldSlot] = widget;
 }
+/**
+ * Adds the listener to the collection of listeners who will
+ * be notifed when an event of the given type occurs anywhere
+ * in this display. When the event does occur, the listener is
+ * notified by sending it the <code>handleEvent()</code> message.
+ *
+ * @param eventType the type of event to listen for
+ * @param listener the listener which should be notified when the event occurs
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Listener
+ * @see #removeFilter
+ * @see #removeListener
+ * 
+ * @since 3.0 
+ */
 public void addFilter (int eventType, Listener listener) {
 	checkDevice ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -590,7 +613,7 @@
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #dispose
+ * @see Device#dispose
  * 
  * @since 2.0
  */
@@ -1156,6 +1179,18 @@
 	OS.XQueryPointer (xDisplay, window, unused, unused, rootX, rootY, unused, unused, unused);
 	return new Point (rootX [0], rootY [0]);
 }
+/**
+ * Returns an array containing the recommended cursor sizes.
+ *
+ * @return the array of cursor sizes
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Point [] getCursorSizes() {
 	checkDevice ();
 	int xDrawable = OS.XDefaultRootWindow (xDisplay);
@@ -1307,6 +1342,23 @@
 	} while ((handle = OS.XtParent (handle)) != 0);
 	return null;
 }
+/**
+ * Returns true when the high contrast mode is enabled.
+ * Otherwise, false is returned.
+ * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
+ *
+ * @return the high contrast mode
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public boolean getHighContrast () {
 	checkDevice ();
 	return false;
@@ -1326,6 +1378,20 @@
 public int getIconDepth () {
 	return getDepth ();
 }
+/**
+ * Returns an array containing the recommended icon sizes.
+ *
+ * @return the array of icon sizes
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Decorations#setImages(Image[])
+ * 
+ * @since 3.0
+ */
 public Point [] getIconSizes () {
 	checkDevice ();
 	int w = OS.XDefaultRootWindow (xDisplay);
@@ -1547,6 +1613,48 @@
 	if (xColor == null) return super.getSystemColor (SWT.COLOR_BLACK);
 	return Color.motif_new (this, xColor);
 }
+/**
+ * Returns the matching standard platform cursor for the given
+ * constant, which should be one of the cursor constants
+ * specified in class <code>SWT</code>. This cursor should
+ * not be free'd because it was allocated by the system,
+ * not the application.  A value of <code>null</code> will
+ * be returned if the supplied constant is not an swt cursor
+ * constant. 
+ *
+ * @param id the swt cursor constant
+ * @return the corresponding cursor or <code>null</code>
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see SWT#CURSOR_ARROW
+ * @see SWT#CURSOR_WAIT
+ * @see SWT#CURSOR_CROSS
+ * @see SWT#CURSOR_APPSTARTING
+ * @see SWT#CURSOR_HELP
+ * @see SWT#CURSOR_SIZEALL
+ * @see SWT#CURSOR_SIZENESW
+ * @see SWT#CURSOR_SIZENS
+ * @see SWT#CURSOR_SIZENWSE
+ * @see SWT#CURSOR_SIZEWE
+ * @see SWT#CURSOR_SIZEN
+ * @see SWT#CURSOR_SIZES
+ * @see SWT#CURSOR_SIZEE
+ * @see SWT#CURSOR_SIZEW
+ * @see SWT#CURSOR_SIZENE
+ * @see SWT#CURSOR_SIZESE
+ * @see SWT#CURSOR_SIZESW
+ * @see SWT#CURSOR_SIZENW
+ * @see SWT#CURSOR_UPARROW
+ * @see SWT#CURSOR_IBEAM
+ * @see SWT#CURSOR_NO
+ * @see SWT#CURSOR_HAND
+ * 
+ * @since 3.0
+ */
 public Cursor getSystemCursor (int id) {
 	checkDevice ();
 	if (!(0 <= id && id < cursors.length)) return null;
@@ -1580,6 +1688,32 @@
 	checkDevice ();
 	return defaultFont;
 }
+/**
+ * Returns the matching standard platform image for the given
+ * constant, which should be one of the icon constants
+ * specified in class <code>SWT</code>. This image should
+ * not be free'd because it was allocated by the system,
+ * not the application.  A value of <code>null</code> will
+ * be returned either if the supplied constant is not an
+ * swt icon constant or if the platform does not define an
+ * image that corresponds to the constant. 
+ *
+ * @param id the swt icon constant
+ * @return the corresponding image or <code>null</code>
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see SWT#ICON_ERROR
+ * @see SWT#ICON_INFORMATION
+ * @see SWT#ICON_QUESTION
+ * @see SWT#ICON_WARNING
+ * @see SWT#ICON_WORKING
+ * 
+ * @since 3.0
+ */
 public Image getSystemImage (int style) {
 	checkDevice ();
 	int imagePixmap = 0, maskPixmap = 0;
@@ -1628,6 +1762,17 @@
 	if (imagePixmap == 0) return null;
 	return Image.motif_new (this, SWT.ICON, imagePixmap, maskPixmap);
 }
+/**
+ * Returns the single instance of the system tray.
+ *
+ * @return the receiver's user-interface thread
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.0
+ */
 public Tray getSystemTray () {
 	if (tray != null) return tray;
 	return tray = new Tray (this, SWT.NULL);
@@ -2122,7 +2267,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int gc, GCData data) {
@@ -2136,11 +2281,83 @@
 	int index = name.lastIndexOf ('.');
 	return name.substring (0, index + 1).equals (PACKAGE_PREFIX);
 }
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param point to be mapped 
+ * @return point with mapped coordinates 
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Point map (Control from, Control to, Point point) {
 	checkDevice ();
 	if (point == null) error (SWT.ERROR_NULL_ARGUMENT);	
 	return map (from, to, point.x, point.y);
 }
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param x coordinates to be mapped
+ * @param y coordinates to be mapped
+ * @return point with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Point map (Control from, Control to, int x, int y) {
 	checkDevice ();
 	if (from != null && from.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -2160,11 +2377,85 @@
 	}
 	return point;
 }
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param rectangle to be mapped
+ * @return rectangle with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Rectangle map (Control from, Control to, Rectangle rectangle) {
 	checkDevice();
 	if (rectangle == null) error (SWT.ERROR_NULL_ARGUMENT);
 	return map (from, to, rectangle.x, rectangle.y, rectangle.width, rectangle.height);
 }
+/**
+ * Maps a point from one coordinate system to another.
+ * When the control is null, coordinates are mapped to
+ * the display.
+ * <p>
+ * NOTE: On right-to-left platforms where the coordinate
+ * systems are mirrored, special care needs to be taken
+ * when mapping coordinates from one control to another
+ * to ensure the result is correctly mirrored.
+ * 
+ * Mapping a point that is the origin of a rectangle and
+ * then adding the width and height is not equivalent to
+ * mapping the rectangle.  When one control is mirrored
+ * and the other is not, adding the width and height to a
+ * point that was mapped causes the rectangle to extend
+ * in the wrong direction.  Mapping the entire rectangle
+ * instead of just one point causes both the origin and
+ * the corner of the rectangle to be mapped.
+ * </p>
+ * 
+ * @param from the source <code>Control</code> or <code>null</code>
+ * @param to the destination <code>Control</code> or <code>null</code>
+ * @param x coordinates to be mapped
+ * @param y coordinates to be mapped
+ * @param width coordinates to be mapped
+ * @param height coordinates to be mapped
+ * @return rectangle with mapped coordinates
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 2.1.2
+ */
 public Rectangle map (Control from, Control to, int x, int y, int width, int height) {
 	checkDevice();
 	if (from != null && from.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT);
@@ -2190,6 +2481,54 @@
 	if (widget == null) return 0;
 	return widget.hoverProc (id);
 }
+/**
+ * Generate a low level system event.
+ * 
+ * <code>post</code> is used to generate low level keyboard
+ * and mouse events. The intent is to enable automated UI
+ * testing by simulating the input from the user.  Most
+ * SWT applications should never need to call this method.
+ * 
+ * <p>
+ * <b>Event Types:</b>
+ * <p>KeyDown, KeyUp
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type KeyDown or KeyUp</li>
+ * <p> Either one of:
+ * <li>(in) character a character that corresponds to a keyboard key</li>
+ * <li>(in) keyCode the key code of the key that was typed,
+ *          as defined by the key code constants in class <code>SWT</code></li>
+ * </ul>
+ * <p>MouseDown, MouseUp</p>
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type MouseDown or MouseUp
+ * <li>(in) button the button that is pressed or released
+ * </ul>
+ * <p>MouseMove</p>
+ * <p>The following fields in the <code>Event</code> apply:
+ * <ul>
+ * <li>(in) type MouseMove
+ * <li>(in) x the x coordinate to move the mouse pointer to in screen coordinates
+ * <li>(in) y the y coordinate to move the mouse pointer to in screen coordinates
+ * </ul>
+ * </dl>
+ * 
+ * @param event the event to be generated
+ * 
+ * @return true if the event was generated or false otherwise
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the event is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.0
+ * 
+ */
 public boolean post (Event event) {
 	if (isDisposed ()) error (SWT.ERROR_DEVICE_DISPOSED);
 	if (event == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -2515,6 +2854,27 @@
 	}
 	return widget;
 }
+/**
+ * Removes the listener from the collection of listeners who will
+ * be notifed when an event of the given type occurs anywhere in
+ * this display.
+ *
+ * @param eventType the type of event to listen for
+ * @param listener the listener which should no longer be notified when the event occurs
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @see Listener
+ * @see #addFilter
+ * @see #addListener
+ * 
+ * @since 3.0
+ */
 public void removeFilter (int eventType, Listener listener) {
 	checkDevice ();
 	if (listener == null) error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java
index f0a2a41..86d33fc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java
@@ -42,16 +42,7 @@
 	static final char SEPARATOR = System.getProperty ("file.separator").charAt (0);
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -79,15 +70,9 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FontDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FontDialog.java
index ff704e4..cd28ecd 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FontDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FontDialog.java
@@ -20,6 +20,12 @@
 /**
  * Instances of this class allow the user to select a font
  * from all available fonts in the system.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
+ * <dt><b>Events:</b></dt>
+ * <dd>(none)</dd>
+ * </dl>
  * <p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
@@ -94,18 +100,10 @@
 	}
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
+ *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
  * </ul>
@@ -130,15 +128,10 @@
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
  * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
+ *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
  * </ul>
@@ -409,7 +402,7 @@
  * Returns a FontData set describing the font that was
  * selected in the dialog, or null if none is available.
  * 
- * @return the FontData set for the selected font, or null
+ * @return the FontData for the selected font, or null
  * @since 2.1.1
  */
 public FontData [] getFontList () {
@@ -436,7 +429,9 @@
  * Returns the currently selected color in the receiver.
  *
  * @return the RGB value for the selected color, may be null
+ *
  * @see PaletteData#getRGBs
+ * 
  * @since 2.1
  */
 public RGB getRGB () {
@@ -856,6 +851,7 @@
  *
  * @return a FontData object describing the font that was selected,
  *         or null if the dialog was cancelled or an error occurred
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the dialog has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the dialog</li>
@@ -977,7 +973,7 @@
  * Sets a FontData object describing the font to be
  * selected by default in the dialog, or null to let
  * the platform choose one.
- *
+ * 
  * @param fontData the FontData to use initially, or null
  * @deprecated use #setFontList (FontData [])
  */
@@ -1030,7 +1026,9 @@
  * @param rgb the new RGB value for the selected color, may be
  *        null to let the platform to select a default when
  *        open() is called
+ *
  * @see PaletteData#getRGBs
+ * 
  * @since 2.1
  */
 public void setRGB (RGB rgb) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java
index 8c6e3ec..3791695 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java
@@ -396,8 +396,8 @@
 	OS.XmListDeselectAllItems (handle);
 }
 /**
- * Returns the zero-relative index of the item which is currently
- * has the focus in the receiver, or -1 if no item is has focus.
+ * Returns the zero-relative index of the item which currently
+ * has the focus in the receiver, or -1 if no item has focus.
  *
  * @return the index of the selected item
  *
@@ -738,6 +738,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to start the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1009,11 +1010,16 @@
 	}
 }
 /**
- * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the index was already selected, it remains
- * selected. The range of the indices is inclusive. Indices that are
- * out of range are ignored and no items will be selected if start is
- * greater than end.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If an item in the given range is not selected, it is selected.
+ * If an item in the given range was already selected, it remains selected.
+ * Indices that are out of range are ignored and no items will be selected
+ * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start of the range
  * @param end the end of the range
@@ -1022,6 +1028,8 @@
  *    <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 List#setSelection(int,int)
  */
 public void select (int start, int end) {
 	checkWidget ();
@@ -1067,20 +1075,25 @@
 }
 /**
  * Selects the items at the given zero-relative indices in the receiver.
- * If the item at the given zero-relative index in the receiver 
- * is not selected, it is selected.  If the item at the index
- * was selected, it remains selected. Indices that are out
- * of range and duplicate indices are ignored.
+ * The current selection is not cleared before the new items are selected.
+ * <p>
+ * If the item at a given index is not selected, it is selected.
+ * If the item at a given index was already selected, it remains selected.
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the array of indices for the items to select
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of indices 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>
+ * 
+ * @see List#setSelection(int[])
  */
 public void select (int [] indices) {
 	checkWidget ();
@@ -1146,7 +1159,9 @@
 	OS.XmListUpdateSelectedList (handle);
 }
 /**
- * Selects all the items in the receiver.
+ * Selects all of the items in the receiver.
+ * <p>
+ * If the receiver is single-select, do nothing.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1363,10 +1378,14 @@
 	}
 }
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items in the range specified by the given zero-relative
+ * indices in the receiver. The range of indices is inclusive.
+ * The current selection is cleared before the new items are selected.
+ * <p>
  * Indices that are out of range are ignored and no items will be selected
  * if start is greater than end.
+ * If the receiver is single-select and there is more than one item in the
+ * given range, then all indices are ignored.
  *
  * @param start the start index of the items to select
  * @param end the end index of the items to select
@@ -1376,8 +1395,8 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see Table#deselectAll()
- * @see Table#select(int,int)
+ * @see List#deselectAll()
+ * @see List#select(int,int)
  */
 public void setSelection (int start, int end) {
 	checkWidget ();
@@ -1402,13 +1421,17 @@
 	}
 }
 /**
- * Selects the items at the given zero-relative indices in the receiver. 
- * The current selection is first cleared, then the new items are selected.
+ * Selects the items at the given zero-relative indices in the receiver.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Indices that are out of range and duplicate indices are ignored.
+ * If the receiver is single-select and multiple indices are specified,
+ * then all indices are ignored.
  *
  * @param indices the indices of the items to select
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of indices is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1433,13 +1456,16 @@
 }
 /**
  * Sets the receiver's selection to be the given array of items.
- * The current selected is first cleared, then the new items are
- * selected.
+ * The current selection is cleared before the new items are selected.
+ * <p>
+ * Items that are not in the receiver are ignored.
+ * If the receiver is single-select and multiple items are specified,
+ * then all items are ignored.
  *
  * @param items the array of items
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of items is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the array of items is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1447,7 +1473,8 @@
  * </ul>
  *
  * @see List#deselectAll()
- * @see List#select(int)
+ * @see List#select(int[])
+ * @see List#setSelection(int[])
  */
 public void setSelection (String [] items) {
 	checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
index 41590f4..2f9c404 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
@@ -101,7 +101,7 @@
  * for the instance so that the instance will be a drop-down
  * menu on the given parent's parent.
  *
- * @param parent a menu which will be the parent of the new instance (cannot be null)
+ * @param parentMenu a menu which will be the parent of the new instance (cannot be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -124,7 +124,7 @@
  * for the instance so that the instance will be a drop-down
  * menu on the given parent's parent menu.
  *
- * @param parent a menu item which will be the parent of the new instance (cannot be null)
+ * @param parentItem a menu item which will be the parent of the new instance (cannot be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java
index 411cbca..1e92ed1 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java
@@ -41,16 +41,7 @@
 	String message = "";
 
 /**
- * Constructs a new instance of this class given only its
- * parent.
- * <p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
+ * Constructs a new instance of this class given only its parent.
  *
  * @param parent a shell which will be the parent of the new instance
  *
@@ -77,16 +68,9 @@
  * of those <code>SWT</code> style constants. The class description
  * lists the style constants that are applicable to the class.
  * Style bits are also inherited from superclasses.
- * </p>
- * Note: Currently, null can be passed in for the parent.
- * This has the effect of creating the dialog on the currently active
- * display if there is one. If there is no current display, the 
- * dialog is created on a "default" display. <b>Passing in null as
- * the parent is not considered to be good coding style,
- * and may not be supported in a future release of SWT.</b>
- * </p>
  *
  * @param parent a shell which will be the parent of the new instance
+ * @param style the style of dialog to construct
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java
index e0e00ef..946becc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java
@@ -228,11 +228,12 @@
 	}
 }
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * 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
+ * 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 (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -249,11 +250,12 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value that the receiver will allow.  This new
+ * value will be ignored if it is negative or is not less 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 (must be zero or greater)
+ * @param value the new minimum, which must be nonnegative and less than 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/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java
index 9079fa5..13aa6cd 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java
@@ -266,7 +266,7 @@
  * are pressed to the argument, which must be at least 
  * one.
  *
- * @param value the new increment (must be greater than zero)
+ * @param increment the new increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -277,11 +277,12 @@
 	checkWidget();
 }
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * 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
+ * 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 (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -298,11 +299,12 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value that the receiver will allow.  This new
+ * value will be ignored if it is negative or is not less 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 (must be zero or greater)
+ * @param value the new minimum, which must be nonnegative and less than the current maximum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -324,7 +326,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param pageIncrement the page increment (must be greater than zero)
  *
  * @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/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
index fddfdf7..6164417 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
@@ -459,11 +459,12 @@
 	OS.XtSetValues (handle, argList, argList.length / 2);
 }
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the maximum. If this value is negative or less than or
+ * equal to the minimum, the value is ignored. If necessary, first
+ * the thumb and then the selection are adjusted to fit within the
+ * new range.
  *
- * @param value the new maximum (must be zero or greater)
+ * @param value the new maximum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -480,11 +481,12 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value. If this value is negative or greater
+ * than or equal to the maximum, the value is ignored. If necessary,
+ * first the thumb and then the selection are adjusted to fit within
+ * the new range.
  *
- * @param value the new minimum (must be zero or greater)
+ * @param value the new minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -525,7 +527,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -543,7 +545,7 @@
  * value to the argument which must be greater than or equal
  * to zero.
  *
- * @param value the new selection (must be zero or greater)
+ * @param selection the new selection (must be zero or greater)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -560,17 +562,17 @@
 }
 /**
  * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values to the
- * argument which must be at least one.
+ * difference between its maximum and minimum values.  This new
+ * value will be ignored if it is less than one, and will be
+ * clamped if it exceeds the receiver's current range.
  *
- * @param value the new thumb value (must be at least one)
+ * @param value the new thumb value, which must be at least one and not
+ * larger than the size of the current range
  *
  * @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 ScrollBar
  */
 public void setThumb (int value) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scrollable.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scrollable.java
index 9d17dc6..e06d152 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scrollable.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scrollable.java
@@ -81,6 +81,10 @@
  * receiver's parent).
  * </p>
  * 
+ * @param x the desired x coordinate of the client area
+ * @param y the desired y coordinate of the client area
+ * @param width the desired width of the client area
+ * @param height the desired height of the client area
  * @return the required bounds to produce the given client area
  *
  * @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
index b8d3942..e427740 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
@@ -497,6 +497,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
+ * @see SWT#Close
  * @see #dispose
  */
 public void close () {
@@ -860,9 +861,10 @@
 	return super.getMaximized ();
 }
 /** 
- * Returns the region that defines the shape of the shell.
+ * Returns the region that defines the shape of the shell,
+ * or null if the shell has the default shape.
  *
- * @return the region that defines the shape of the shell
+ * @return the region that defines the shape of the shell (or null)
  *	
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -992,8 +994,8 @@
  * the display on which it was created (so that all other
  * shells on that display, which are not the receiver's
  * children will be drawn behind it), marks it visible,
- * and sets focus to its default button (if it has one)
- * and asks the window manager to make the shell active.
+ * sets the focus and asks the window manager to make the
+ * shell active.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1266,11 +1268,16 @@
 }
 /**
  * Sets the shape of the shell to the region specified
- * by the argument.  A null region will restore the default shape.
- * Shell must be created with the style SWT.NO_TRIM.
+ * by the argument.  When the argument is null, the
+ * default shape of the shell is restored.  The shell
+ * must be created with the style SWT.NO_TRIM in order
+ * to specify a region.
  *
- * @param rgn the region that defines the shape of the shell
- * 
+ * @param region the region that defines the shape of the shell (or null)
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the region 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>
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 fc7a3e5..c31817a 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
@@ -334,11 +334,12 @@
 	OS.XtSetValues (handle, argList, argList.length / 2);
 }
 /**
- * Sets the maximum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the maximum. If this value is negative or less than or
+ * equal to the minimum, the value is ignored. If necessary, first
+ * the thumb and then the selection are adjusted to fit within the
+ * new range.
  *
- * @param value the new maximum (must be zero or greater)
+ * @param value the new maximum, which must be greater than the current minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -355,11 +356,12 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the minimum value which the receiver will allow
- * to be the argument which must be greater than or
- * equal to zero.
+ * Sets the minimum value. If this value is negative or greater
+ * than or equal to the maximum, the value is ignored. If necessary,
+ * first the thumb and then the selection are adjusted to fit within
+ * the new range.
  *
- * @param value the new minimum (must be zero or greater)
+ * @param value the new minimum
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -400,7 +402,7 @@
  * are selected to the argument, which must be at least
  * one.
  *
- * @return the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -435,17 +437,17 @@
 }
 /**
  * Sets the size of the receiver's thumb relative to the
- * difference between its maximum and minimum values to the
- * argument which must be at least one.
+ * difference between its maximum and minimum values.  This new
+ * value will be ignored if it is less than one, and will be
+ * clamped if it exceeds the receiver's current range.
  *
- * @param value the new thumb value (must be at least one)
+ * @param value the new thumb value, which must be at least one and not
+ * larger than the size of the current range
  *
  * @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 ScrollBar
  */
 public void setThumb (int value) {
 	checkWidget();
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 0f590bc..def7c66 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
@@ -23,7 +23,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>CENTER, LEFT, MULTI, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
+ * <dd>CENTER, LEFT, MULTI, PASSWORD, SINGLE, RIGHT, READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>DefaultSelection, Modify, Verify</dd>
  * </dl>
@@ -41,7 +41,16 @@
 	int drawCount;
 	
 	static final boolean IsGB18030;
+	/**
+	* The maximum number of characters that can be entered
+	* into a text widget.
+	*/
 	public static final int LIMIT;
+	/**
+	* The delimiter used by multi-line text widgets.  When text
+	* is queried and from the widget, it will be delimited using
+	* this delimiter.
+	*/
 	public static final String DELIMITER;
 	
 	/*
@@ -478,6 +487,8 @@
  * default action of the text widget when the user
  * double clicks.
  * </p>
+ * 
+ * @return whether or not double click is enabled
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -497,6 +508,8 @@
  * displayed when the user enters text or the
  * text is changed by the programmer.
  * </p>
+ * 
+ * @return the echo character
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -510,6 +523,8 @@
 /**
  * Gets the editable state.
  *
+ * @return whether or not the reciever is editable
+ * 
  * @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>
@@ -629,7 +644,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -757,7 +772,8 @@
 	return new String (Converter.mbcsToWcs (getCodePage (), buffer));
 }
 /**
- * Gets a range of text.
+ * Gets a range of text.  Returns an empty string if the
+ * start of the range is greater than the end.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N-1 where N is
@@ -1159,10 +1175,10 @@
 }
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1331,7 +1347,7 @@
  * SINGLE and the argument contains multiple lines of text, the result of this
  * operation is undefined and may vary from platform to platform.
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolBar.java
index 1068b6e..c3d0b80 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolBar.java
@@ -72,8 +72,8 @@
  * @see SWT#HORIZONTAL
  * @see SWT#SHADOW_OUT
  * @see SWT#VERTICAL
- * @see Widget#checkSubclass
- * @see Widget#getStyle
+ * @see Widget#checkSubclass()
+ * @see Widget#getStyle()
  */
 public ToolBar (Composite parent, int style) {
 	super (parent, checkStyle (style));
@@ -226,7 +226,7 @@
 	return itemCount;
 }
 /**
- * Returns an array of <code>TabItem</code>s which are the items
+ * Returns an array of <code>ToolItem</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/motif/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java
index 4739956..595e354 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java
@@ -845,7 +845,7 @@
  * @param rectangles the bounds of the rectangles to be drawn
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the set of rectangles is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the set of rectangles is null or contains a null rectangle</li>
  * </ul>
  * @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/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
index 76096ea..4f3e763 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
@@ -86,7 +86,7 @@
  * </p>
  *
  * @param device the device on which to allocate the color
- * @param RGB the RGB values of the desired color
+ * @param rgb the RGB values of the desired color
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -180,6 +180,8 @@
 /**
  * Returns an <code>RGB</code> representing the receiver.
  *
+ * @return the RGB for the color
+ *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
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 dcb5e11..fbf3a41 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
@@ -138,7 +138,7 @@
 /**	 
  * Constructs a new cursor given a device, image and mask
  * data describing the desired cursor appearance, and the x
- * and y co-ordinates of the <em>hotspot</em> (that is, the point
+ * and y coordinates of the <em>hotspot</em> (that is, the point
  * within the area covered by the cursor which is considered
  * to be where the on-screen pointer is "pointing").
  * <p>
@@ -250,6 +250,33 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**	 
+ * Constructs a new cursor given a device, image data describing
+ * the desired cursor appearance, and the x and y coordinates of
+ * the <em>hotspot</em> (that is, the point within the area
+ * covered by the cursor which is considered to be where the
+ * on-screen pointer is "pointing").
+ * <p>
+ * You must dispose the cursor when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the cursor
+ * @param source the image data for the cursor
+ * @param hotspotX the x coordinate of the cursor's hotspot
+ * @param hotspotY the y coordinate of the cursor's hotspot
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the hotspot is outside the bounds of the
+ * 		 image</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java
index a652fa9..e8b804f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java
@@ -298,7 +298,7 @@
  * <code>faceName</code> is null, all fonts will be returned.
  *
  * @param faceName the name of the font to look for, or null
- * @param scalable true if scalable fonts should be returned.
+ * @param scalable if true only scalable fonts are returned, otherwise only non-scalable fonts are returned.
  * @return the matching font data
  *
  * @exception SWTException <ul>
@@ -488,7 +488,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public abstract void internal_dispose_GC (int handle, GCData data);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java
index 12f551f..abf2fd6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java
@@ -17,7 +17,6 @@
 
 /**
  * Instances of this class describe operating system fonts.
- * Only the public API of this type is platform independent.
  * <p>
  * For platform-independent behaviour, use the get and set methods
  * corresponding to the following properties:
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 a0d81b6..0200685 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
@@ -19,6 +19,17 @@
  * Class <code>GC</code> is where all of the drawing capabilities that are 
  * supported by SWT are located. Instances are used to draw on either an 
  * <code>Image</code>, a <code>Control</code>, or directly on a <code>Display</code>.
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
+ * </dl>
+ * 
+ * <p>
+ * The SWT drawing coordinate system is the two-dimensional space with the origin
+ * (0,0) at the top left corner of the drawing area and with (x,y) values increasing
+ * to the right and downward respectively.
+ * </p>
+ * 
  * <p>
  * Application code must explicitly invoke the <code>GC.dispose()</code> 
  * method to release the operating system resources managed by each instance
@@ -26,6 +37,10 @@
  * important on Windows95 and Windows98 where the operating system has a limited
  * number of device contexts available.
  * </p>
+ * 
+ * <p>
+ * Note: Only one of LEFT_TO_RIGHT and RIGHT_TO_LEFT may be specified.
+ * </p>
  *
  * @see org.eclipse.swt.events.PaintEvent
  */
@@ -89,6 +104,32 @@
 	this(drawable, 0);
 }
 
+/**	 
+ * Constructs a new instance of this class which has been
+ * configured to draw on the specified drawable. Sets the
+ * foreground and background color in the GC to match those
+ * in the drawable.
+ * <p>
+ * You must dispose the graphics context when it is no longer required. 
+ * </p>
+ * 
+ * @param drawable the drawable to draw on
+ * @param style the style of GC to construct
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the drawable is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if there is no current device</li>
+ *    <li>ERROR_INVALID_ARGUMENT
+ *          - if the drawable is an image that is not a bitmap or an icon
+ *          - if the drawable is an image or printer that is already selected
+ *            into another graphics context</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li>
+ * </ul>
+ *  
+ * @since 2.1.2
+ */
 public GC(Drawable drawable, int style) {
 	int flags = OS.PtEnter(0);
 	try {
@@ -116,6 +157,7 @@
  * Copies a rectangular area of the receiver at the specified
  * position into the image, which must be of type <code>SWT.BITMAP</code>.
  *
+ * @param image the image to copy into
  * @param x the x coordinate in the receiver of the area to be copied
  * @param y the y coordinate in the receiver of the area to be copied
  *
@@ -387,9 +429,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -946,6 +985,23 @@
 	}
 }
 
+/** 
+ * Draws a pixel, using the foreground color, at the specified
+ * point (<code>x</code>, <code>y</code>).
+ * <p>
+ * Note that the receiver's line attributes do not affect this
+ * operation.
+ * </p>
+ *
+ * @param x the point's x coordinate
+ * @param y the point's y coordinate
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *  
+ * @since 3.0
+ */
 public void drawPoint (int x, int y) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	int flags = OS.PtEnter(0);
@@ -1439,9 +1495,6 @@
  * @param startAngle the beginning angle
  * @param arcAngle the angular extent of the arc, relative to the start angle
  *
- * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if any of the width, height or endAngle is zero.</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
@@ -1674,7 +1727,7 @@
  * Fills the interior of the specified rectangle, using the receiver's
  * background color. 
  *
- * @param rectangle the rectangle to be filled
+ * @param rect the rectangle to be filled
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
@@ -1976,6 +2029,24 @@
 	return data.lineWidth;
 }
 
+/**
+ * Returns the receiver's style information.
+ * <p>
+ * Note that the value which is returned by this method <em>may
+ * not match</em> the value which was provided to the constructor
+ * when the receiver was created. This can occur when the underlying
+ * operating system does not support a particular combination of
+ * requested styles. 
+ * </p>
+ *
+ * @return the style bits
+ *  
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *   
+ * @since 2.1.2
+ */
 public int getStyle () {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.style;
@@ -2177,7 +2248,7 @@
  * by drawing operations to the region specified
  * by the argument.
  *
- * @param rect the clipping region.
+ * @param region the clipping region.
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
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 9b0f370..03f9dcc 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
@@ -71,7 +71,7 @@
 	public int type;
 
 	/**
-	 * the OS resource of the image
+	 * the handle to the OS image resource
 	 * (Warning: This field is platform dependent)
 	 */
 	public int handle;
@@ -165,6 +165,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon, or
  *          is otherwise in an invalid state</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the Image is not supported</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -341,6 +342,9 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li>
+ * </ul>
  */
 public Image(Device device, ImageData data) {
 	if (device == null) device = Device.getDevice();
@@ -421,6 +425,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -453,6 +458,7 @@
  * @exception SWTException <ul>
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
  *    <li>ERROR_IO - if an IO error occurs while reading data</li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li>
  * </ul>
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
@@ -931,7 +937,7 @@
  * application code.
  * </p>
  *
- * @param handle the platform specific GC handle
+ * @param hDC the platform specific GC handle
  * @param data the platform specific GC data 
  */
 public void internal_dispose_GC (int pmMC, GCData data) {
@@ -963,7 +969,7 @@
  * these cases. For example:
  * <pre>
  *    Button b = new Button();
- *    image.setBackground(b.getBackground());>
+ *    image.setBackground(b.getBackground());
  *    b.setImage(image);
  * </pre>
  * </p><p>
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 502c11f..10e0d01 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
@@ -49,6 +49,25 @@
 public Region () {
 	this(null);
 }
+/**
+ * Constructs a new empty region.
+ * <p>
+ * You must dispose the region when it is no longer required. 
+ * </p>
+ *
+ * @param device the device on which to allocate the region
+ *
+* @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ *
+ * @see #dispose
+ * 
+ * @since 3.0
+ */
 public Region (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -266,6 +285,22 @@
 	return handle;
 }
 
+/**
+ * Intersects the given rectangle to the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to intersect with the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect (Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -285,6 +320,23 @@
 	if (handle == 0) handle = EMPTY_REGION;
 }
 
+/**
+ * Intersects all of the rectangles which make up the area covered
+ * by the argument to the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to intersect
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void intersect (Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -391,7 +443,7 @@
  * Subtracts the given polygon from the collection of rectangles
  * the receiver maintains to describe its area.
  *
- * param pointArray points that describe the polygon to merge with the receiver
+ * @param pointArray points that describe the polygon to merge with the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
@@ -408,6 +460,22 @@
 	// TODO
 }
 
+/**
+ * Subtracts the given rectangle from the collection of rectangles
+ * the receiver maintains to describe its area.
+ *
+ * @param rect the rectangle to subtract from the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract (Rectangle rect) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -425,6 +493,23 @@
 	if (handle == 0) handle = EMPTY_REGION;
 }
 
+/**
+ * Subtracts all of the rectangles which make up the area covered
+ * by the argument from the collection of rectangles the receiver
+ * maintains to describe its area.
+ *
+ * @param region the region to subtract
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.0
+ */
 public void subtract (Region region) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (region == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
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 374235b..8709e3e 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
@@ -322,7 +322,8 @@
 
 /**
  * Returns the receiver's text, which will be an empty
- * string if it has never been set.
+ * string if it has never been set or if the receiver is
+ * an <code>ARROW</code> button.
  *
  * @return the receiver's text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Caret.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Caret.java
index a797055..faf771d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Caret.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Caret.java
@@ -369,7 +369,7 @@
  * to the image specified by the argument, or to the default
  * which is a filled rectangle if the argument is null
  *
- * @param font the new font (or null)
+ * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
@@ -446,7 +446,6 @@
  * Sets the receiver's size to the point specified by the argument.
  *
  * @param size the new extent for the receiver
- * @param height the new height for the receiver
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ColorDialog.java
index ce3010a..a1f6b39 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ColorDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ColorDialog.java
@@ -36,7 +36,7 @@
 /**
  * Constructs a new instance of this class given only its parent.
  *
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a composite control which will be the parent of the new instance
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
@@ -136,7 +136,7 @@
  * Sets the receiver's selected color to be the argument.
  *
  * @param rgb the new RGB value for the selected color, may be
- *        null to let the platform to select a default when
+ *        null to let the platform select a default when
  *        open() is called
  * @see PaletteData#getRGBs
  */
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 eb53e5a..72a9df1 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
@@ -620,7 +620,7 @@
 /**
  * Returns the orientation of the receiver.
  *
- * @return the orientation bit.
+ * @return the orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -805,6 +805,7 @@
  * returns -1.
  *
  * @param string the search item
+ * @param start the zero-relative index at which to begin the search
  * @return the index of the item
  *
  * @exception IllegalArgumentException <ul>
@@ -1078,6 +1079,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1108,6 +1110,9 @@
  *
  * @param items the array of items
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the items array 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>
@@ -1137,10 +1142,10 @@
 
 /**
  * Sets the orientation of the receiver, which must be one
- * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.LEFT_TO_RIGHT</code>.
+ * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
  *
- * @param orientation new orientation bit
+ * @param orientation new orientation style
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1159,7 +1164,7 @@
  * start of the selection and whose y coordinate is the end
  * of the selection. 
  *
- * @param a point representing the new selection start and end
+ * @param selection a point representing the new selection start and end
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
@@ -1186,7 +1191,7 @@
  * display incorrectly.
  * </p>
  *
- * @param text the new text
+ * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the string is null</li>
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 1b69c0f..1e48a31 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
@@ -20,7 +20,7 @@
  * of containing other controls.
  * <dl>
  * <dt><b>Styles:</b>&