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 5dc18d8..5efecd4 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
@@ -75,6 +75,7 @@
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the display is null</li>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent's peer is not created</li>
  * </ul>
  * 
  * @since 3.0
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 5d4d2a8..4f0b314 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
@@ -94,7 +94,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
  * </ul>
  * 
- * @see #getStyle
+ * @see Widget#getStyle
  * 
  * @since 3.0
  */
@@ -377,7 +377,7 @@
 
 /**	 
  * Adds the listener to the collection of listeners who will be
- * notified when the current location is changed or about to be changed.
+ * notified when the current location has changed or is about to change.
  * <p>
  * This notification typically occurs when the application navigates
  * to a new location with {@link #setUrl(String)} or when the user
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 94b827e..90568f6 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
@@ -107,7 +107,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
  * </ul>
  * 
- * @see #getStyle
+ * @see Widget#getStyle
  * 
  * @since 3.0
  */
@@ -376,7 +376,7 @@
 
 /**	 
  * Adds the listener to the collection of listeners who will be
- * notified when the current location is changed or about to be changed.
+ * notified when the current location has changed or is about to change.
  * <p>
  * This notification typically occurs when the application navigates
  * to a new location with {@link #setUrl(String)} or when the user
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 8f2e79d..c48e3de 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
@@ -81,7 +81,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
  * </ul>
  * 
- * @see #getStyle
+ * @see Widget#getStyle
  * 
  * @since 3.0
  */
@@ -208,7 +208,7 @@
 
 /**	 
  * Adds the listener to the collection of listeners who will be
- * notified when the current location is changed or about to be changed.
+ * notified when the current location has changed or is about to change.
  * <p>
  * This notification typically occurs when the application navigates
  * to a new location with {@link #setUrl(String)} or when the user
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 078418e..144be0a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -25,7 +25,7 @@
  * <code>byte[]</code>, you should sub-class <code>Transfer</code> directly 
  * and do your own mapping to a platform data type.</p>
  * 
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
  * data defined by the class <code>MyType</code>.</p>
  * 
  * <pre><code>
@@ -36,7 +36,7 @@
  * }
  * </code></pre>
  * 
- * <code><pre>
+ * <pre><code>
  * public class MyTypeTransfer extends ByteArrayTransfer {
  *	
  *	private static final String MYTYPENAME = "my_type_name";
@@ -113,6 +113,7 @@
  * 	return new int[] {MYTYPEID};
  * }
  * }
+ * </code></pre>
  */
 public abstract class ByteArrayTransfer extends Transfer {
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java
index c93c418..2e353e0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java
@@ -132,7 +132,7 @@
  * <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
  * recoverable error, but can not be changed due to backward compatability.</p>
  * 
- * @see DropTarget#dispose
+ * @see Widget#dispose
  * @see DropTarget#checkSubclass
  * @see DND#DROP_NONE
  * @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
index 2c9b92e..b115961 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
@@ -16,8 +16,7 @@
 /**
  * The class <code>TextTransfer</code> provides a platform specific mechanism 
  * for converting plain text represented as a java <code>String</code> 
- * to a platform specific representation of the data and vice versa.  See 
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
  * 
  * <p>An example of a java <code>String</code> containing plain text is shown 
  * below:</p>
@@ -25,6 +24,8 @@
  * <code><pre>
  *     String textData = "Hello World";
  * </code></pre>
+ * 
+ * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
 
@@ -48,11 +49,12 @@
 /**
  * This implementation of <code>javaToNative</code> converts plain text
  * represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
  * 
  * @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- *  object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ *  will be filled in on return with the platform specific format of the data
+ *  
+ * @see Transfer#javaToNative
  */
 public void javaToNative (Object object, TransferData transferData) {
 	if (!checkText(object) || !isSupportedType(transferData)) {
@@ -99,12 +101,11 @@
 /**
  * This implementation of <code>nativeToJava</code> converts a platform specific 
  * representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
  * 
- * @param transferData the platform specific representation of the data to be 
- * been converted
- * @return a java <code>String</code> containing text if the 
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ * 
+ * @see Transfer#nativeToJava
  */
 public Object nativeToJava(TransferData transferData){
 	if (!isSupportedType(transferData) || transferData.data == null) return null;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java
index d4c9069..c93d6a5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java
@@ -38,7 +38,8 @@
 
 /**
  * Returns true if the <code>TransferData</code> data type can be converted 
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
  *
  * @param transferData a platform specific description of a data type; only the data
  *  type fields of the <code>TransferData</code> object need to be filled in
@@ -92,6 +93,10 @@
  *
  * @param transferData an empty TransferData object; this object will be 
  * filled in on return with the platform specific representation of the data
+ * 
+ * @exception org.eclipse.swt.SWTException <ul>
+ *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
  */
 abstract protected void javaToNative (Object object, TransferData transferData);
 
@@ -102,8 +107,9 @@
  * converted
  *
  * @return a java representation of the converted data if the conversion was 
- * successful; otherwise null.  The type of Object that is returned is dependant 
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null.  If transferData is <code>null</code> then
+ * <code>null</code> is returned.  The type of Object that is returned is 
+ * dependant on the <code>Transfer</code> subclass.
  */
 abstract protected Object nativeToJava(TransferData transferData);
 
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 11ba0a7..3354598 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
@@ -25,7 +25,7 @@
  * <code>byte[]</code>, you should sub-class <code>Transfer</code> directly 
  * and do your own mapping to a platform data type.</p>
  * 
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
  * data defined by the class <code>MyType</code>.</p>
  * 
  * <pre><code>
@@ -36,7 +36,7 @@
  * }
  * </code></pre>
  * 
- * <code><pre>
+ * <pre><code>
  * public class MyTypeTransfer extends ByteArrayTransfer {
  *	
  *	private static final String MYTYPENAME = "my_type_name";
@@ -113,6 +113,7 @@
  * 	return new int[] {MYTYPEID};
  * }
  * }
+ * </code></pre>
  */
 public abstract class ByteArrayTransfer extends Transfer {
 	
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java
index be28cad..2f65e4d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java
@@ -99,7 +99,7 @@
  * <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
  * recoverable error, but can not be changed due to backward compatability.</p>
  * 
- * @see DropTarget#dispose
+ * @see Widget#dispose
  * @see DropTarget#checkSubclass
  * @see DND#DROP_NONE
  * @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
index 4f3c06d..c80269c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
@@ -14,8 +14,7 @@
 /**
  * The class <code>TextTransfer</code> provides a platform specific mechanism 
  * for converting plain text represented as a java <code>String</code> 
- * to a platform specific representation of the data and vice versa.  See 
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
  * 
  * <p>An example of a java <code>String</code> containing plain text is shown 
  * below:</p>
@@ -23,6 +22,8 @@
  * <code><pre>
  *     String textData = "Hello World";
  * </code></pre>
+ * 
+ * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
 
@@ -47,23 +48,23 @@
 /**
  * This implementation of <code>javaToNative</code> converts plain text
  * represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
  * 
  * @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- *  object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ *  will be filled in on return with the platform specific format of the data
+ *  
+ * @see Transfer#javaToNative
  */
 public void javaToNative (Object object, TransferData transferData){
 }
 /**
  * This implementation of <code>nativeToJava</code> converts a platform specific 
  * representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
  * 
- * @param transferData the platform specific representation of the data to be 
- * been converted
- * @return a java <code>String</code> containing text if the 
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ * 
+ * @see Transfer#nativeToJava
  */
 public Object nativeToJava(TransferData transferData){
 	return null;
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 961deb1..16682cf 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
@@ -38,7 +38,8 @@
 
 /**
  * Returns true if the <code>TransferData</code> data type can be converted 
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
  *
  * @param transferData a platform specific description of a data type; only the data
  *  type fields of the <code>TransferData</code> object need to be filled in
@@ -92,6 +93,10 @@
  *
  * @param transferData an empty TransferData object; this object will be 
  * filled in on return with the platform specific representation of the data
+ * 
+ * @exception org.eclipse.swt.SWTException <ul>
+ *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
  */
 abstract protected void javaToNative (Object object, TransferData transferData);
 
@@ -102,8 +107,9 @@
  * converted
  *
  * @return a java representation of the converted data if the conversion was 
- * successful; otherwise null.  The type of Object that is returned is dependant 
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null.  If transferData is <code>null</code> then
+ * <code>null</code> is returned.  The type of Object that is returned is 
+ * dependant on the <code>Transfer</code> subclass.
  */
 abstract protected Object nativeToJava(TransferData transferData);
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java
index a37fb1f..c79080c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -26,7 +26,7 @@
  * <code>byte[]</code>, you should sub-class <code>Transfer</code> directly 
  * and do your own mapping to a platform data type.</p>
  * 
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
  * data defined by the class <code>MyType</code>.</p>
  * 
  * <pre><code>
@@ -37,7 +37,7 @@
  * }
  * </code></pre>
  * 
- * <code><pre>
+ * <pre><code>
  * public class MyTypeTransfer extends ByteArrayTransfer {
  *	
  *	private static final String MYTYPENAME = "my_type_name";
@@ -114,6 +114,7 @@
  * 	return new int[] {MYTYPEID};
  * }
  * }
+ * </code></pre>
  */
 public abstract class ByteArrayTransfer extends Transfer {
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java
index 9ef36ed..f4ee0e5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java
@@ -135,6 +135,7 @@
  * <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
  * recoverable error, but can not be changed due to backward compatability.</p>
  * 
+ * @see Widget#dispose
  * @see DropTarget#checkSubclass
  * @see DND#DROP_NONE
  * @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
index 378566a..c0e4e43 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
@@ -16,8 +16,7 @@
 /**
  * The class <code>TextTransfer</code> provides a platform specific mechanism 
  * for converting plain text represented as a java <code>String</code> 
- * to a platform specific representation of the data and vice versa.  See 
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
  * 
  * <p>An example of a java <code>String</code> containing plain text is shown 
  * below:</p>
@@ -25,6 +24,8 @@
  * <code><pre>
  *     String textData = "Hello World";
  * </code></pre>
+ * 
+ * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
 
@@ -48,11 +49,12 @@
 /**
  * This implementation of <code>javaToNative</code> converts plain text
  * represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
  * 
  * @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- *  object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ *  will be filled in on return with the platform specific format of the data
+ *  
+ * @see Transfer#javaToNative
  */
 public void javaToNative (Object object, TransferData transferData) {
 	transferData.result = 0;
@@ -89,12 +91,11 @@
 /**
  * This implementation of <code>nativeToJava</code> converts a platform specific 
  * representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
  * 
- * @param transferData the platform specific representation of the data to be 
- * been converted
- * @return a java <code>String</code> containing text if the 
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ * 
+ * @see Transfer#nativeToJava
  */
 public Object nativeToJava(TransferData transferData){
 	if (!isSupportedType(transferData) ||  transferData.pValue == 0) return null;
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 8beb3ed..b0b8afc 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
@@ -41,7 +41,8 @@
 
 /**
  * Returns true if the <code>TransferData</code> data type can be converted 
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
  *
  * @param transferData a platform specific description of a data type; only the data
  *  type fields of the <code>TransferData</code> object need to be filled in
@@ -95,6 +96,10 @@
  *
  * @param transferData an empty TransferData object; this object will be 
  * filled in on return with the platform specific representation of the data
+ * 
+ * @exception org.eclipse.swt.SWTException <ul>
+ *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
  */
 abstract protected void javaToNative (Object object, TransferData transferData);
 
@@ -105,8 +110,9 @@
  * converted
  *
  * @return a java representation of the converted data if the conversion was 
- * successful; otherwise null.  The type of Object that is returned is dependant 
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null.  If transferData is <code>null</code> then
+ * <code>null</code> is returned.  The type of Object that is returned is 
+ * dependant on the <code>Transfer</code> subclass.
  */
 abstract protected Object nativeToJava(TransferData transferData);
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java
index aba2149..df11116 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -26,7 +26,7 @@
  * <code>byte[]</code>, you should sub-class <code>Transfer</code> directly 
  * and do your own mapping to a platform data type.</p>
  * 
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
  * data defined by the class <code>MyType</code>.</p>
  * 
  * <pre><code>
@@ -37,7 +37,7 @@
  * }
  * </code></pre>
  * 
- * <code><pre>
+ * <pre><code>
  * public class MyTypeTransfer extends ByteArrayTransfer {
  *	
  *	private static final String MYTYPENAME = "my_type_name";
@@ -114,6 +114,7 @@
  * 	return new int[] {MYTYPEID};
  * }
  * }
+ * </code></pre>
  */
 public abstract class ByteArrayTransfer extends Transfer {
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java
index 784c3d8..d3eb670 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java
@@ -142,7 +142,7 @@
  * <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
  * recoverable error, but can not be changed due to backward compatability.</p>
  * 
- * @see DropTarget#dispose
+ * @see Widget#dispose
  * @see DropTarget#checkSubclass
  * @see DND#DROP_NONE
  * @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
index c36e8f5..b88d646 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
@@ -18,8 +18,7 @@
 /**
  * The class <code>TextTransfer</code> provides a platform specific mechanism 
  * for converting plain text represented as a java <code>String</code> 
- * to a platform specific representation of the data and vice versa.  See 
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
  * 
  * <p>An example of a java <code>String</code> containing plain text is shown 
  * below:</p>
@@ -27,6 +26,8 @@
  * <code><pre>
  *     String textData = "Hello World";
  * </code></pre>
+ * 
+ * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
 
@@ -50,11 +51,12 @@
 /**
  * This implementation of <code>javaToNative</code> converts plain text
  * represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
  * 
  * @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- *  object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ *  will be filled in on return with the platform specific format of the data
+ *  
+ * @see Transfer#javaToNative
  */
 public void javaToNative (Object object, TransferData transferData) {
 	transferData.result = 0;
@@ -102,12 +104,11 @@
 /**
  * This implementation of <code>nativeToJava</code> converts a platform specific 
  * representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
  * 
- * @param transferData the platform specific representation of the data to be 
- * been converted
- * @return a java <code>String</code> containing text if the 
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ * 
+ * @see Transfer#nativeToJava
  */
 public Object nativeToJava(TransferData transferData){
 	if (!isSupportedType(transferData) ||  transferData.pValue == 0) return null;
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 28b4f23..0df0b58 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
@@ -42,7 +42,8 @@
 
 /**
  * Returns true if the <code>TransferData</code> data type can be converted 
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
  *
  * @param transferData a platform specific description of a data type; only the data
  *  type fields of the <code>TransferData</code> object need to be filled in
@@ -96,6 +97,10 @@
  *
  * @param transferData an empty TransferData object; this object will be 
  * filled in on return with the platform specific representation of the data
+ * 
+ * @exception org.eclipse.swt.SWTException <ul>
+ *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
  */
 abstract protected void javaToNative (Object object, TransferData transferData);
 
@@ -106,8 +111,9 @@
  * converted
  *
  * @return a java representation of the converted data if the conversion was 
- * successful; otherwise null.  The type of Object that is returned is dependant 
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null.  If transferData is <code>null</code> then
+ * <code>null</code> is returned.  The type of Object that is returned is 
+ * dependant on the <code>Transfer</code> subclass.
  */
 abstract protected Object nativeToJava(TransferData transferData);
 
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 24a2d0c..73e22f2 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
@@ -27,7 +27,7 @@
  * <code>byte[]</code>, you should sub-class <code>Transfer</code> directly 
  * and do your own mapping to a platform data type.</p>
  * 
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
  * data defined by the class <code>MyType</code>.</p>
  * 
  * <pre><code>
@@ -38,7 +38,7 @@
  * }
  * </code></pre>
  * 
- * <code><pre>
+ * <pre><code>
  * public class MyTypeTransfer extends ByteArrayTransfer {
  *	
  *	private static final String MYTYPENAME = "my_type_name";
@@ -115,6 +115,7 @@
  * 	return new int[] {MYTYPEID};
  * }
  * }
+ * </code></pre>
  */
 public abstract class ByteArrayTransfer extends Transfer {
 	
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
index e492b9d..8c2d3c6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
@@ -99,7 +99,7 @@
  * <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
  * recoverable error, but can not be changed due to backward compatability.</p>
  * 
- * @see DropTarget#dispose
+ * @see Widget#dispose
  * @see DropTarget#checkSubclass
  * @see DND#DROP_NONE
  * @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
index 9e3ff38..4c52fe3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
@@ -17,8 +17,7 @@
 /**
  * The class <code>TextTransfer</code> provides a platform specific mechanism 
  * for converting plain text represented as a java <code>String</code> 
- * to a platform specific representation of the data and vice versa.  See 
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
  * 
  * <p>An example of a java <code>String</code> containing plain text is shown 
  * below:</p>
@@ -26,6 +25,8 @@
  * <code><pre>
  *     String textData = "Hello World";
  * </code></pre>
+ * 
+ * @see Transfer
  */
 public class TextTransfer extends ByteArrayTransfer {
 
@@ -46,11 +47,12 @@
 /**
  * This implementation of <code>javaToNative</code> converts plain text
  * represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
  * 
  * @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- *  object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ *  will be filled in on return with the platform specific format of the data
+ *  
+ * @see Transfer#javaToNative
  */
 public void javaToNative (Object object, TransferData transferData){
 	if (!checkText(object) || !isSupportedType(transferData)) {
@@ -63,12 +65,11 @@
 /**
  * This implementation of <code>nativeToJava</code> converts a platform specific 
  * representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
  * 
- * @param transferData the platform specific representation of the data to be 
- * been converted
- * @return a java <code>String</code> containing text if the 
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ * 
+ * @see Transfer#nativeToJava
  */
 public Object nativeToJava(TransferData transferData){
 
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 3202f56..35a7eba 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
@@ -37,7 +37,8 @@
 abstract public TransferData[] getSupportedTypes();
 /**
  * Returns true if the <code>TransferData</code> data type can be converted 
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
  *
  * @param transferData a platform specific description of a data type; only the data
  *  type fields of the <code>TransferData</code> object need to be filled in
@@ -91,6 +92,10 @@
  *
  * @param transferData an empty TransferData object; this object will be 
  * filled in on return with the platform specific representation of the data
+ * 
+ * @exception org.eclipse.swt.SWTException <ul>
+ *    <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
  */
 abstract protected void javaToNative (Object object, TransferData transferData);
 
@@ -101,8 +106,9 @@
  * converted
  *
  * @return a java representation of the converted data if the conversion was 
- * successful; otherwise null.  The type of Object that is returned is dependant 
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null.  If transferData is <code>null</code> then
+ * <code>null</code> is returned.  The type of Object that is returned is 
+ * dependant on the <code>Transfer</code> subclass.
  */
 abstract protected Object nativeToJava(TransferData transferData);
 
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 5f4759e..1d5726f 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
@@ -232,6 +232,7 @@
  * Creates the printer handle.
  * This method is called internally by the instance creation
  * mechanism of the <code>Device</code> class.
+ * @param deviceData the device data
  */
 protected void create(DeviceData deviceData) {
 	data = (PrinterData)deviceData;
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 dcd2b91..8a53b2c 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
@@ -275,6 +275,7 @@
  * Creates the printer handle.
  * This method is called internally by the instance creation
  * mechanism of the <code>Device</code> class.
+ * @param deviceData the device data
  */
 protected void create(DeviceData deviceData) {
 	data = (PrinterData)deviceData;
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 d68eea5..6191177 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
@@ -282,17 +282,21 @@
  * the program has no descriptive name, this string may
  * be the executable name, path or empty.
  *
- * @return an the name of the program
+ * @return the name of the program
  */
 public String getName () {
 	return name;
 }
 
 /**
- * Returns true if the receiver and the argument represent
- * the same program.
- * 
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
  */
 public boolean equals(Object other) {
 	if (this == other) return true;
@@ -305,14 +309,25 @@
 }
 
 /**
- * Returns a hash code suitable for this object.
- * 
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two 
+ * objects that return <code>true</code> when passed to 
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
  */
 public int hashCode() {
 	return name.hashCode() ^ command.hashCode() ^ iconName.hashCode();
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
 public String toString () {
 	return "Program {" + name + "}";
 }
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 58b0aae..7d04a21 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
@@ -711,10 +711,14 @@
 }
 
 /**
- * Returns true if the receiver and the argument represent
- * the same program.
- * 
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
  */
 public boolean equals(Object other) {
 	if (this == other) return true;
@@ -769,21 +773,32 @@
  * the program has no descriptive name, this string may
  * be the executable name, path or empty.
  *
- * @return an the name of the program
+ * @return the name of the program
  */
 public String getName() {
 	return name;
 }
 
 /**
- * Returns a hash code suitable for this object.
- * 
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two 
+ * objects that return <code>true</code> when passed to 
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
  */
 public int hashCode() {
 	return name.hashCode() ^ command.hashCode() ^ display.hashCode();
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
 public String toString() {
 	return "Program {" + name + "}";
 }
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 593f994..e844de7 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
@@ -746,10 +746,14 @@
 }
 
 /**
- * Returns true if the receiver and the argument represent
- * the same program.
- * 
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
  */
 public boolean equals(Object other) {
 	if (this == other) return true;
@@ -804,21 +808,32 @@
  * the program has no descriptive name, this string may
  * be the executable name, path or empty.
  *
- * @return an the name of the program
+ * @return the name of the program
  */
 public String getName() {
 	return name;
 }
 
 /**
- * Returns a hash code suitable for this object.
- * 
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two 
+ * objects that return <code>true</code> when passed to 
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
  */
 public int hashCode() {
 	return name.hashCode() ^ command.hashCode() ^ display.hashCode();
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
 public String toString() {
 	return "Program {" + name + "}";
 }
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 7d1bd91..a0e14f0 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
@@ -319,17 +319,21 @@
  * the program has no descriptive name, this string may
  * be the executable name, path or empty.
  *
- * @return an the name of the program
+ * @return the name of the program
  */
 public String getName () {
 	return name;
 }
 
 /**
- * Returns true if the receiver and the argument represent
- * the same program.
- * 
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
  */
 public boolean equals(Object other) {
 	if (this == other) return true;
@@ -342,14 +346,25 @@
 }
 
 /**
- * Returns a hash code suitable for this object.
- * 
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two 
+ * objects that return <code>true</code> when passed to 
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
  */
 public int hashCode() {
 	return extension.hashCode() ^ name.hashCode() ^ command.hashCode();
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
 public String toString () {
 	return "Program {" + name + "}";
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
index 5299c44..90e54b1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
@@ -14,16 +14,49 @@
 import org.eclipse.swt.internal.*;
 import org.eclipse.swt.internal.cairo.*;
 
+/**
+ * Instances of this class represent paths through the two-dimensional
+ * coordinate system. Paths do not have to be continuous, and can be
+ * described using lines, rectangles, arcs, cubic or quadratic bezier curves,
+ * glyphs, or other paths.
+ * <p>
+ * Application code must explicitly invoke the <code>Path.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
+ */
 public class Path extends Resource {
 	
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Path
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int /*long*/ handle;
 	
 	boolean move;
 
+/**
+ * Constructs a new empty Path.
+ * 
+ * @param device the device on which to allocate the path
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the path could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Path (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -34,6 +67,35 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**
+ * Adds to the receiver a circular or elliptical arc that lies within
+ * the specified rectangular area.
+ * <p>
+ * The resulting arc begins at <code>startAngle</code> and extends  
+ * for <code>arcAngle</code> degrees.
+ * Angles are interpreted such that 0 degrees is at the 3 o'clock
+ * position. A positive value indicates a counter-clockwise rotation
+ * while a negative value indicates a clockwise rotation.
+ * </p><p>
+ * The center of the arc is the center of the rectangle whose origin 
+ * is (<code>x</code>, <code>y</code>) and whose size is specified by the 
+ * <code>width</code> and <code>height</code> arguments. 
+ * </p><p>
+ * The resulting arc covers an area <code>width + 1</code> pixels wide
+ * by <code>height + 1</code> pixels tall.
+ * </p>
+ *
+ * @param x the x coordinate of the upper-left corner of the arc
+ * @param y the y coordinate of the upper-left corner of the arc
+ * @param width the width of the arc
+ * @param height the height of the arc
+ * @param startAngle the beginning angle
+ * @param arcAngle the angular extent of the arc, relative to the start angle
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addArc(float x, float y, float width, float height, float startAngle, float arcAngle) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	move = true;
@@ -49,6 +111,19 @@
 	Cairo.cairo_destroy(matrix);
 }
 
+/**
+ * Adds to the receiver the path described by the parameter.
+ *
+ * @param path the path to add to the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addPath(Path path) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -57,12 +132,41 @@
 	Cairo.cairo_add_path(handle, path.handle);
 }
 
+/**
+ * Adds to the receiver the rectangle specified by x, y, width and height.
+ *
+ * @param x the x coordinate of the rectangle to add
+ * @param y the y coordinate of the rectangle to add
+ * @param width the width of the rectangle to add
+ * @param height the height of the rectangle to add
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addRectangle(float x, float y, float width, float height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	move = false;
 	Cairo.cairo_rectangle(handle, x, y, width, height);
 }
 
+/**
+ * Adds to the receiver the pattern of glyphs generated by drawing
+ * the given string using the given font starting at the point (x, y).
+ *
+ * @param string the text to use
+ * @param x the x coordinate of the starting point
+ * @param y the y coordinate of the starting point
+ * @param font the font to use
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the font is null</li>
+ *    <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 addString(String string, float x, float y, Font font) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (font == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -77,12 +181,44 @@
 	Cairo.cairo_text_path(handle, buffer);
 }
 
+/**
+ * Closes the current sub path by adding to the receiver a line
+ * from the current point of the path back to the starting point
+ * of the sub path.
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void close() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	Cairo.cairo_close_path(handle);
 	move = false;
 }
 
+/**
+ * Returns <code>true</code> if the specified point is contained by
+ * the receiver and false otherwise.
+ * <p>
+ * If outline is <code>true</code>, the point (x, y) checked for containment in
+ * the receiver's outline. If outline is <code>false</code>, the point is
+ * checked to see if it is contained within the bounds of the (closed) area
+ * covered by the receiver.
+ *
+ * @param x the x coordinate of the point to test for containment
+ * @param y the y coordinate of the point to test for containment
+ * @param gc the GC to use when testing for containment
+ * @param outline controls wether to check the outline or contained area of the path
+ * @return <code>true</code> if the path contains the point and <code>false</code> otherwise
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public boolean contains(float x, float y, GC gc, boolean outline) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -101,6 +237,20 @@
 	return result;
 }
 
+/**
+ * Adds to the receiver a cubic bezier curve based on the parameters.
+ *
+ * @param cx1 the x coordinate of the first control point of the spline
+ * @param cy1 the y coordinate of the first control of the spline
+ * @param cx2 the x coordinate of the second control of the spline
+ * @param cy2 the y coordinate of the second control of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (!move) {
@@ -112,6 +262,21 @@
 	Cairo.cairo_curve_to(handle, cx1, cy1, cx2, cy2, x, y);
 }
 
+/**
+ * Replaces the first four elements in the parameter with values that
+ * describe the smallest rectangle that will completely contain the
+ * receiver (i.e. the bounding box).
+ *
+ * @param bounds the array to hold the result
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void getBounds(float[] bounds) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -124,6 +289,20 @@
 	bounds[3] = (float)(extents[3] - extents[1]);
 }
 
+/**
+ * Replaces the first two elements in the parameter with values that
+ * describe the current point of the path.
+ *
+ * @param point the array to hold the result
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void getCurrentPoint(float[] point) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -134,6 +313,17 @@
 	point[1] = (float)y[0];
 }
 
+/**
+ * Returns a device independent representation of the receiver.
+ * 
+ * @return the PathData for the receiver
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see PathData
+ */
 public PathData getPathData() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	int[] n_types = new int[1];
@@ -148,6 +338,17 @@
 	return result;
 }
 
+/**
+ * Adds to the receiver a line from the current point to
+ * the point specified by (x, y).
+ *
+ * @param x the x coordinate of the end of the line to add
+ * @param y the y coordinate of the end of the line to add
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void lineTo(float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (!move) {
@@ -159,6 +360,18 @@
 	Cairo.cairo_line_to(handle, x, y);
 }
 
+/**
+ * Sets the current point of the receiver to the point
+ * specified by (x, y). Note that this starts a new
+ * sub path.
+ *
+ * @param x the x coordinate of the new end point
+ * @param y the y coordinate of the new end point
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void moveTo(float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	/*
@@ -172,6 +385,18 @@
 	Cairo.cairo_move_to(handle, x, y);
 }
 
+/**
+ * Adds to the receiver a quadratic curve based on the parameters.
+ *
+ * @param cx the x coordinate of the control point of the spline
+ * @param cy the y coordinate of the control point of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void quadTo(float cx, float cy, float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	double[] currentX = new double[1], currentY = new double[1];
@@ -189,6 +414,11 @@
 	Cairo.cairo_curve_to(handle, cx1, cy1, cx2, cy2, x, y);
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Path. Applications must dispose of all Paths that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	Cairo.cairo_destroy(handle);
@@ -197,10 +427,26 @@
 	device = null;
 }
 
+/**
+ * Returns <code>true</code> if the Path has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Path.
+ * When a Path has been disposed, it is an error to
+ * invoke any other method using the Path.
+ *
+ * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Path {*DISPOSED*}";
 	return "Path {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
index 2b818f4..8cfe85f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
@@ -14,16 +14,47 @@
 import org.eclipse.swt.internal.cairo.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent patterns to use while drawing. Patterns
+ * can be specified either as bitmaps or gradients.
+ * <p>
+ * Application code must explicitly invoke the <code>Pattern.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Pattern extends Resource {
 
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Pattern
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int /*long*/ handle;
 
+/**
+ * Constructs a new Pattern given an image. Drawing with the resulting
+ * pattern will cause the image to be tiled over the resulting area.
+ * 
+ * @param device the device on which to allocate the pattern
+ * @param image the image that the pattern will draw
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Pattern(Device device, Image image) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -38,6 +69,30 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**
+ * Constructs a new Pattern that represents a linear, two color
+ * gradient. Drawing with the pattern will cause the resulting area to be
+ * tiled with the gradient specified by the arguments.
+ * 
+ * @param device the device on which to allocate the pattern
+ * @param x1 the x coordinate of the starting corner of the gradient
+ * @param y1 the y coordinate of the starting corner of the gradient
+ * @param x2 the x coordinate of the ending corner of the gradient
+ * @param y2 the y coordinate of the ending corner of the gradient
+ * @param color1 the starting color of the gradient
+ * @param color2 the ending color of the gradient
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, 
+ *                              or if either color1 or color2 is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Pattern(Device device, float x1, float y1, float x2, float y2, Color color1, Color color2) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -56,6 +111,11 @@
 	if (device.tracking) device.new_Object(this);
 }
 	
+/**
+ * Disposes of the operating system resources associated with
+ * the Pattern. Applications must dispose of all Patterns that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	if (device.isDisposed()) return;
@@ -65,10 +125,26 @@
 	device = null;
 }
 
+/**
+ * Returns <code>true</code> if the Pattern has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Pattern.
+ * When a Pattern has been disposed, it is an error to
+ * invoke any other method using the Pattern.
+ *
+ * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Pattern {*DISPOSED*}";
 	return "Pattern {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
index 6ff290e..848128a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
@@ -14,21 +14,90 @@
 import org.eclipse.swt.internal.*;
 import org.eclipse.swt.internal.cairo.*;
 
+/**
+ * Instances of this class represent transformation matrices for 
+ * points expressed as (x, y) pairs of floating point numbers.
+ * <p>
+ * Application code must explicitly invoke the <code>Transform.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
+ */
 public class Transform extends Resource {
 	/**
-	 * the handle to the OS transform resource
+	 * the OS resource for the Transform
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int /*long*/ handle;
 	
+/**
+ * Constructs a new identity Transform.
+ * 
+ * @param device the device on which to allocate the Transform
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform (Device device) {
 	this(device, 1, 0, 0, 1, 0, 0);
 }
 
+/**
+ * Constructs a new Transform given an array of elements that represent the 
+ * matrix that describes the transformation.
+ * 
+ * @param device the device on which to allocate the Transform
+ * @param elements an array of floats that describe the transformation matrix
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform(Device device, float[] elements) {
 	this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
 }
 
+/**
+ * Constructs a new Transform given all of the elements that represent the 
+ * matrix that describes the transformation.
+ * 
+ * @param device the device on which to allocate the Transform
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -46,6 +115,11 @@
 	return elements;
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Transform. Applications must dispose of all Transforms that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	if (device.isDisposed()) return;
@@ -55,6 +129,21 @@
 	device = null;
 }
 
+/**
+ * Fills the parameter with the values of the transformation matrix
+ * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
+ *
+ * @param elements array to hold the matrix values
+ * @return (in elements array) the transformation matrix represented by the receiver
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
+ * </ul>
+ */
 public void getElements(float[] elements) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -70,6 +159,15 @@
 	elements[5] = (float)ty[0];
 }
 
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the mathematical inverse of the matrix it previously represented. 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertable</li>
+ * </ul>
+ */
 public void invert() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (Cairo.cairo_matrix_invert(handle) != 0) {
@@ -77,10 +175,26 @@
 	}
 }
 
+/**
+ * Returns <code>true</code> if the Transform has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Transform.
+ * When a Transform has been disposed, it is an error to
+ * invoke any other method using the Transform.
+ *
+ * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Returns <code>true</code> if the Transform represents the identity matrix
+ * and false otherwise.
+ *
+ * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
+ */
 public boolean isIdentity() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	float[] m  = new float[6];
@@ -88,6 +202,21 @@
 	return m[0] == 1 && m[1] == 0 && m[2] == 0 && m[3] == 1 && m[4] == 0 && m[5] == 0;
 }
 
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the result of multiplying the matrix it previously represented by the
+ * argument. 
+ *
+ * @param matrix the matrix to multiply the receiver by
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ */
 public void multiply(Transform matrix) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -95,21 +224,74 @@
 	Cairo.cairo_matrix_multiply(handle, matrix.handle, handle);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation rotated by the specified angle.
+ * The angle is specified in degrees and for the identity transform 0 degrees
+ * is at the 3 o'clock position. A positive value indicates a clockwise rotation
+ * while a negative value indicates a counter-clockwise rotation.
+ *
+ * @param angle the angle to rotate the transformation by
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void rotate(float angle) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	Cairo.cairo_matrix_rotate(handle, angle * (float)Compatibility.PI / 180);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation scaled by (scaleX, scaleY).
+ * 
+ * @param scaleX the amount to scale in the X direction
+ * @param scaleY the amount to scale in the Y direction
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void scale(float scaleX, float scaleY) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	Cairo.cairo_matrix_scale(handle, scaleX, scaleY);
 }
 
+/**
+ * Modifies the receiver to represent a new transformation given all of
+ * the elements that represent the matrix that describes that transformation.
+ * 
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	Cairo.cairo_matrix_set_affine(handle, m11, m12, m21, m22, dx, dy);
 }
 
+/** 
+ * Given an array containing points described by alternating x and y values,
+ * modify that array such that each point has been replaced with the result of
+ * applying the transformation represented by the receiver to that point.
+ *
+ * @param pointArray an array of alternating x and y values to be transformed
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
+ * </ul>	
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void transform(float[] pointArray) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -124,11 +306,28 @@
 	}
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation translated by (offsetX, offsetY).
+ * 
+ * @param offsetX the distance to translate in the X direction
+ * @param offsetY the distance to translate in the Y direction
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void translate(float offsetX, float offsetY) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	Cairo.cairo_matrix_translate(handle, offsetX, offsetY);
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Transform {*DISPOSED*}";
 	float[] elements = new float[6];
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 dac0cef..53519bb 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
@@ -176,7 +176,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 e57c199..8cd0a4a 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
@@ -496,7 +496,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 1a7384e..ef6a468 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
@@ -416,7 +416,7 @@
  * specified in class <code>SWT</code>. Any value other
  * than one of the SWT color constants which is passed
  * in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
  * not the application.
  *
  * @param id the color constant
@@ -455,7 +455,7 @@
  * Returns a reasonable font for applications to use.
  * On some platforms, this will match the "default font"
  * or "system font" if such can be found.  This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
  * system, not the application.
  * <p>
  * Typically, applications which want the default look
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 425e8a4..c3650fe 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
@@ -311,7 +311,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 65bddd4..d73858c 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
@@ -278,7 +278,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -378,7 +378,8 @@
 /**
  * Sets the style of the receiver to the argument which must
  * be a bitwise OR of one or more of the <code>SWT</code> 
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC.  All other style bits are
+ * ignored.
  *
  * @param style the new style for this <code>FontData</code>
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java
index c66cb01..ba51ca8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java
@@ -117,7 +117,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 f029fef..cd0a7f3 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
@@ -260,6 +260,24 @@
 public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY) {
 	copyArea(srcX, srcY, width, height, destX, destY, true);
 }
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1 
+ */
 public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY, boolean paint) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (data.updateClip) setCGClipping();
@@ -505,7 +523,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void drawFocus(int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -704,8 +722,22 @@
 	flush();
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void drawPath(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1215,7 +1247,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1291,8 +1323,22 @@
 	flush();
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void fillPath(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1360,7 +1406,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle(int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1395,7 +1441,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle(Rectangle rect) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1509,21 +1555,64 @@
 	return Color.carbon_new (data.device, data.background);
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public Pattern getBackgroundPattern() {	
 	if (handle == 0) SWT.error(SWT.ERROR_WIDGET_DISPOSED);
 	return data.backgroundPattern;	
 }
 
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem.  Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, <code>false</code> is always returned.  Some operating system have
+ * only one graphics subsystem.  If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned.  If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned.  If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAdvanced
+ * @since 3.1
+ */
 public boolean getAdvanced() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return true;
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getAlpha() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1531,7 +1620,20 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getTextAntialias
+ * 
+ * @since 3.1
  */
 public int getAntialias() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1648,6 +1750,18 @@
 	}
 }
 
+/** 
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public int getFillRule() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.fillRule;
@@ -1708,16 +1822,37 @@
 	return Color.carbon_new(data.device, data.foreground);	
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public Pattern getForegroundPattern() {	
 	if (handle == 0) SWT.error(SWT.ERROR_WIDGET_DISPOSED);
 	return data.foregroundPattern;	
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getInterpolation() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1750,7 +1885,8 @@
 }
 
 /** 
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
  *
  * @return the lin dash style used for drawing lines
  *
@@ -1845,15 +1981,43 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAntialias
+ * 
+ * @since 3.1
  */
 public int getTextAntialias() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.textAntialias;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void getTransform (Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1884,7 +2048,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -1956,6 +2120,48 @@
 	 	&& transform[3] == 1 && transform[4] == 0 && transform[5] == 0;
 }
 
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is 
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested.  When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations.  Because the two subsystems are
+ * different, their output may differ.  Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, this operation does nothing.  Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing.  However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ * 
+ * @since 3.1
+ */
 public void setAdvanced(boolean advanced) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (!advanced) {
@@ -1971,7 +2177,15 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setAlpha(int alpha) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1980,7 +2194,24 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setTextAntialias
+ * 
+ * @since 3.1
  */
 public void setAntialias(int antialias) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2027,6 +2258,22 @@
 	data.backgroundPattern = null;
 }
 
+/** 
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
+ */
 public void setBackgroundPattern(Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (pattern != null && pattern.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -2094,7 +2341,22 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void setClipping(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2109,9 +2371,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
  *
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -2129,9 +2393,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the region specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
  *
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
  * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -2186,6 +2452,22 @@
 	OS.CGContextTranslateCTM(handle, rect.left, -(portRect.bottom - portRect.top) + rect.top);
 }
 
+/** 
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ *                                 or <code>SWT.FILL_WINDING</code></li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public void setFillRule(int rule) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	switch (rule) {
@@ -2264,8 +2546,21 @@
 	data.foregroundPattern = null;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public void setForegroundPattern(Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2287,8 +2582,22 @@
 	data.foregroundPattern = pattern;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>, 
+ *                                 <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setInterpolation(int interpolation) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2341,7 +2650,10 @@
 }
 
 /** 
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
  *
  * @param dashes the dash style to be used for drawing lines
  * 
@@ -2468,6 +2780,12 @@
  * for all of the figure drawing operations (that is,
  * <code>drawLine</code>, <code>drawRectangle</code>, 
  * <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
  *
  * @param lineWidth the width of a line
  *
@@ -2566,12 +2884,19 @@
  * and the destination, and if the argument is <code>false</code>,
  * puts the receiver in a drawing mode where the destination color
  * is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
  *
  * @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @deprecated this functionality is not supported on some platforms
  */
 public void setXORMode(boolean xor) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2610,7 +2935,24 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAntialias
+ * 
+ * @since 3.1
  */
 public void setTextAntialias(int antialias) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2625,8 +2967,23 @@
 	data.textAntialias = antialias;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void setTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 e706c61..4d3782a 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
@@ -53,7 +53,7 @@
  * loading process should use the support provided in class
  * <code>ImageLoader</code>.
  * </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code> 
+ * Application code must explicitly invoke the <code>Image.dispose()</code> 
  * method to release the operating system resources managed by each instance
  * when those instances are no longer required.
  * </p>
@@ -415,7 +415,20 @@
  * This constructor may be used to load a resource as follows:
  * </p>
  * <pre>
- *     new Image(device, clazz.getResourceAsStream("file.gif"));
+ *     static Image loadImage (Display display, Class clazz, String string) {
+ *          InputStream stream = clazz.getResourceAsStream (string);
+ *          if (stream == null) return null;
+ *          Image image = null;
+ *          try {
+ *               image = new Image (display, stream);
+ *          } catch (SWTException ex) {
+ *          } finally {
+ *               try {
+ *                    stream.close ();
+ *               } catch (IOException ex) {}
+ *          }
+ *          return image;
+ *     }
  * </pre>
  *
  * @param device the device on which to create the image
@@ -672,7 +685,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
index 093455c..4cd7e76 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
@@ -15,16 +15,46 @@
 import org.eclipse.swt.internal.carbon.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent paths through the two-dimensional
+ * coordinate system. Paths do not have to be continuous, and can be
+ * described using lines, rectangles, arcs, cubic or quadratic bezier curves,
+ * glyphs, or other paths.
+ * <p>
+ * Application code must explicitly invoke the <code>Path.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Path extends Resource {
 	
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Path
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int handle;
 	
+/**
+ * Constructs a new empty Path.
+ * 
+ * @param device the device on which to allocate the path
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the path could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Path (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -34,6 +64,35 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**
+ * Adds to the receiver a circular or elliptical arc that lies within
+ * the specified rectangular area.
+ * <p>
+ * The resulting arc begins at <code>startAngle</code> and extends  
+ * for <code>arcAngle</code> degrees.
+ * Angles are interpreted such that 0 degrees is at the 3 o'clock
+ * position. A positive value indicates a counter-clockwise rotation
+ * while a negative value indicates a clockwise rotation.
+ * </p><p>
+ * The center of the arc is the center of the rectangle whose origin 
+ * is (<code>x</code>, <code>y</code>) and whose size is specified by the 
+ * <code>width</code> and <code>height</code> arguments. 
+ * </p><p>
+ * The resulting arc covers an area <code>width + 1</code> pixels wide
+ * by <code>height + 1</code> pixels tall.
+ * </p>
+ *
+ * @param x the x coordinate of the upper-left corner of the arc
+ * @param y the y coordinate of the upper-left corner of the arc
+ * @param width the width of the arc
+ * @param height the height of the arc
+ * @param startAngle the beginning angle
+ * @param arcAngle the angular extent of the arc, relative to the start angle
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addArc(float x, float y, float width, float height, float startAngle, float arcAngle) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	float[] cmt = new float[6];
@@ -41,6 +100,19 @@
 	OS.CGPathAddArc(handle, cmt, 0, 0, 1, -startAngle * (float)Compatibility.PI / 180,  -(startAngle + arcAngle) * (float)Compatibility.PI / 180, true);
 }
 
+/**
+ * Adds to the receiver the path described by the parameter.
+ *
+ * @param path the path to add to the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addPath(Path path) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -48,6 +120,18 @@
 	OS.CGPathAddPath(handle, null, path.handle);
 }
 
+/**
+ * Adds to the receiver the rectangle specified by x, y, width and height.
+ *
+ * @param x the x coordinate of the rectangle to add
+ * @param y the y coordinate of the rectangle to add
+ * @param width the width of the rectangle to add
+ * @param height the height of the rectangle to add
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addRectangle(float x, float y, float width, float height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	CGRect rect = new CGRect();
@@ -95,6 +179,23 @@
 float originX, originY;
 float[] point = new float[2];
 boolean first;
+/**
+ * Adds to the receiver the pattern of glyphs generated by drawing
+ * the given string using the given font starting at the point (x, y).
+ *
+ * @param string the text to use
+ * @param x the x coordinate of the starting point
+ * @param y the y coordinate of the starting point
+ * @param font the font to use
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the font is null</li>
+ *    <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 addString(String string, float x, float y, Font font) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (font == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -195,11 +296,43 @@
 	return 0;
 }
 
+/**
+ * Closes the current sub path by adding to the receiver a line
+ * from the current point of the path back to the starting point
+ * of the sub path.
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void close() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGPathCloseSubpath(handle);
 }
 
+/**
+ * Returns <code>true</code> if the specified point is contained by
+ * the receiver and false otherwise.
+ * <p>
+ * If outline is <code>true</code>, the point (x, y) checked for containment in
+ * the receiver's outline. If outline is <code>false</code>, the point is
+ * checked to see if it is contained within the bounds of the (closed) area
+ * covered by the receiver.
+ *
+ * @param x the x coordinate of the point to test for containment
+ * @param y the y coordinate of the point to test for containment
+ * @param gc the GC to use when testing for containment
+ * @param outline controls wether to check the outline or contained area of the path
+ * @return <code>true</code> if the path contains the point and <code>false</code> otherwise
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public boolean contains(float x, float y, GC gc, boolean outline) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -235,11 +368,30 @@
 	return buffer[0] != 0xFFFFFFFF;
 }
 
+/**
+ * Adds to the receiver a cubic bezier curve based on the parameters.
+ *
+ * @param cx1 the x coordinate of the first control point of the spline
+ * @param cy1 the y coordinate of the first control of the spline
+ * @param cx2 the x coordinate of the second control of the spline
+ * @param cy2 the y coordinate of the second control of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGPathAddCurveToPoint(handle, null, cx1, cy1, cx2, cy2, x, y);
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Path. Applications must dispose of all Paths that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	OS.CGPathRelease(handle);
@@ -248,6 +400,21 @@
 	device = null;
 }
 
+/**
+ * Replaces the first four elements in the parameter with values that
+ * describe the smallest rectangle that will completely contain the
+ * receiver (i.e. the bounding box).
+ *
+ * @param bounds the array to hold the result
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void getBounds(float[] bounds) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -260,6 +427,20 @@
 	bounds[3] = rect.height;
 }
 
+/**
+ * Replaces the first two elements in the parameter with values that
+ * describe the current point of the path.
+ *
+ * @param point the array to hold the result
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void getCurrentPoint(float[] point) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -270,6 +451,17 @@
 	point[1] = pt.y;
 }
 
+/**
+ * Returns a device independent representation of the receiver.
+ * 
+ * @return the PathData for the receiver
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see PathData
+ */
 public PathData getPathData() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	Callback callback = new Callback(this, "applierFunc", 2);
@@ -294,25 +486,76 @@
 	return result;
 }
 
+/**
+ * Returns <code>true</code> if the Path has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Path.
+ * When a Path has been disposed, it is an error to
+ * invoke any other method using the Path.
+ *
+ * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Adds to the receiver a line from the current point to
+ * the point specified by (x, y).
+ *
+ * @param x the x coordinate of the end of the line to add
+ * @param y the y coordinate of the end of the line to add
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void lineTo(float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGPathAddLineToPoint(handle, null, x, y);
 }
 
+/**
+ * Sets the current point of the receiver to the point
+ * specified by (x, y). Note that this starts a new
+ * sub path.
+ *
+ * @param x the x coordinate of the new end point
+ * @param y the y coordinate of the new end point
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void moveTo(float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGPathMoveToPoint(handle, null, x, y);
 }
 
+/**
+ * Adds to the receiver a quadratic curve based on the parameters.
+ *
+ * @param cx the x coordinate of the control point of the spline
+ * @param cy the y coordinate of the control point of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void quadTo(float cx, float cy, float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGPathAddQuadCurveToPoint(handle, null, cx, cy, x, y);
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString () {
 	if (isDisposed()) return "Path {*DISPOSED*}";
 	return "Path {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
index 7f4a4ed..72e1bb9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
@@ -14,7 +14,15 @@
 import org.eclipse.swt.internal.carbon.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent patterns to use while drawing. Patterns
+ * can be specified either as bitmaps or gradients.
+ * <p>
+ * Application code must explicitly invoke the <code>Pattern.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Pattern extends Resource {
 	int jniRef;
@@ -23,6 +31,23 @@
 	float x1, y1, x2, y2;
 	int shading;
 
+/**
+ * Constructs a new Pattern given an image. Drawing with the resulting
+ * pattern will cause the image to be tiled over the resulting area.
+ * 
+ * @param device the device on which to allocate the pattern
+ * @param image the image that the pattern will draw
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Pattern(Device device, Image image) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -36,6 +61,30 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**
+ * Constructs a new Pattern that represents a linear, two color
+ * gradient. Drawing with the pattern will cause the resulting area to be
+ * tiled with the gradient specified by the arguments.
+ * 
+ * @param device the device on which to allocate the pattern
+ * @param x1 the x coordinate of the starting corner of the gradient
+ * @param y1 the y coordinate of the starting corner of the gradient
+ * @param x2 the x coordinate of the ending corner of the gradient
+ * @param y2 the y coordinate of the ending corner of the gradient
+ * @param color1 the starting color of the gradient
+ * @param color2 the ending color of the gradient
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, 
+ *                              or if either color1 or color2 is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Pattern(Device device, float x1, float y1, float x2, float y2, Color color1, Color color2) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -105,6 +154,11 @@
 	return pattern;
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Pattern. Applications must dispose of all Patterns that
+ * they allocate.
+ */
 public void dispose() {
 	if (jniRef == 0) return;
 	if (device.isDisposed()) return;
@@ -133,10 +187,26 @@
 	return 0;
 }
 
+/**
+ * Returns <code>true</code> if the Pattern has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Pattern.
+ * When a Pattern has been disposed, it is an error to
+ * invoke any other method using the Pattern.
+ *
+ * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return jniRef == 0;
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Pattern {*DISPOSED*}";
 	return "Pattern {" + jniRef + "}";
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 e7ef188..a4383d9 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
@@ -143,7 +143,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
@@ -281,7 +280,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -383,7 +382,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects (int x, int y, int width, int height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -407,7 +406,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects(Rectangle rect) {
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -507,7 +506,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
index f47c2bc..93a247f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
@@ -15,23 +15,89 @@
 import org.eclipse.swt.internal.carbon.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent transformation matrices for 
+ * points expressed as (x, y) pairs of floating point numbers.
+ * <p>
+ * Application code must explicitly invoke the <code>Transform.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Transform extends Resource {
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Transform
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public float[] handle;
 	
+/**
+ * Constructs a new identity Transform.
+ * 
+ * @param device the device on which to allocate the Transform
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform (Device device) {
 	this(device, 1, 0, 0, 1, 0, 0);
 }
 
+/**
+ * Constructs a new Transform given an array of elements that represent the 
+ * matrix that describes the transformation.
+ * 
+ * @param device the device on which to allocate the Transform
+ * @param elements an array of floats that describe the transformation matrix
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform(Device device, float[] elements) {
 	this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
 }
 
+/**
+ * Constructs a new Transform given all of the elements that represent the 
+ * matrix that describes the transformation.
+ * 
+ * @param device the device on which to allocate the Transform
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -48,6 +114,11 @@
 	return elements;
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Transform. Applications must dispose of all Transforms that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == null) return;
 	if (device.isDisposed()) return;
@@ -56,6 +127,21 @@
 	device = null;
 }
 
+/**
+ * Fills the parameter with the values of the transformation matrix
+ * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
+ *
+ * @param elements array to hold the matrix values
+ * @return (in elements array) the transformation matrix represented by the receiver
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
+ * </ul>
+ */
 public void getElements(float[] elements) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -63,6 +149,15 @@
 	System.arraycopy(handle, 0, elements, 0, handle.length);
 }
 
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the mathematical inverse of the matrix it previously represented. 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertable</li>
+ * </ul>
+ */
 public void invert() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if ((handle [0] * handle [3] - handle [1] * handle [2]) == 0) {
@@ -71,15 +166,46 @@
 	OS.CGAffineTransformInvert(handle, handle);
 }
 
+/**
+ * Returns <code>true</code> if the Transform has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Transform.
+ * When a Transform has been disposed, it is an error to
+ * invoke any other method using the Transform.
+ *
+ * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == null;
 }
 
+/**
+ * Returns <code>true</code> if the Transform represents the identity matrix
+ * and false otherwise.
+ *
+ * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
+ */
 public boolean isIdentity() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return handle[0] == 1 && handle[1] == 0 && handle[2] == 0 && handle[3] == 1 && handle[4] == 0 && handle[5] == 0;
 }
 
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the result of multiplying the matrix it previously represented by the
+ * argument. 
+ *
+ * @param matrix the matrix to multiply the receiver by
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ */
 public void multiply(Transform matrix) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -87,21 +213,74 @@
 	OS.CGAffineTransformConcat(matrix.handle, handle, handle);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation rotated by the specified angle.
+ * The angle is specified in degrees and for the identity transform 0 degrees
+ * is at the 3 o'clock position. A positive value indicates a clockwise rotation
+ * while a negative value indicates a counter-clockwise rotation.
+ *
+ * @param angle the angle to rotate the transformation by
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void rotate(float angle) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGAffineTransformRotate(handle, angle * (float)Compatibility.PI / 180, handle);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation scaled by (scaleX, scaleY).
+ * 
+ * @param scaleX the amount to scale in the X direction
+ * @param scaleY the amount to scale in the Y direction
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void scale(float scaleX, float scaleY) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGAffineTransformScale(handle, scaleX, scaleY, handle);
 }
 
+/**
+ * Modifies the receiver to represent a new transformation given all of
+ * the elements that represent the matrix that describes that transformation.
+ * 
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGAffineTransformMake(m11, m12, m21, m22, dx, dy, handle);
 }
 
+/** 
+ * Given an array containing points described by alternating x and y values,
+ * modify that array such that each point has been replaced with the result of
+ * applying the transformation represented by the receiver to that point.
+ *
+ * @param pointArray an array of alternating x and y values to be transformed
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
+ * </ul>	
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void transform(float[] pointArray) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -116,11 +295,28 @@
 	}
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation translated by (offsetX, offsetY).
+ * 
+ * @param offsetX the distance to translate in the X direction
+ * @param offsetY the distance to translate in the Y direction
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void translate(float offsetX, float offsetY) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	OS.CGAffineTransformTranslate(handle, offsetX, offsetY, handle);
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Transform {*DISPOSED*}";
 	float[] elements = new float[6];
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 40b54cc..5a7dc0055 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
@@ -610,9 +610,9 @@
 
 /**
  * Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
  *
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
index 27f4b8c..72f67cf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
@@ -63,7 +63,6 @@
  * </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
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 c672b57..1ec451b 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
@@ -647,8 +647,8 @@
 }
 
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list. 
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -692,11 +692,16 @@
 }
 
 /**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
  *
  * @return a point representing the selection start and end
  *
@@ -738,7 +743,8 @@
 
 /**
  * Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
  *
  * @return the receiver's text
  *
@@ -805,6 +811,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -1358,8 +1366,8 @@
 /**
  * Sets the text of the item in the receiver's list at the given
  * zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
  *
  * @param index the index for the item
  * @param string the new text for the item
@@ -1531,7 +1539,11 @@
 /**
  * Sets the maximum number of characters that the receiver's
  * text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
  * @param limit new text limit
  *
  * @exception IllegalArgumentException <ul>
@@ -1541,6 +1553,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget ();
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 d93c0f6..22f767e 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, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
@@ -305,7 +305,7 @@
 }
 
 /**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
  * Children are returned in the order that they are drawn.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -376,7 +376,7 @@
 }
 
 /**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
  *
  * @return tabList the ordered list of controls representing the tab order
  *
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 9be57b1..f115880 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
@@ -398,7 +398,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint) {
@@ -436,7 +436,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -1613,7 +1613,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack () {
 	checkWidget();
@@ -1639,7 +1639,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack (boolean changed) {
 	checkWidget();
@@ -2489,7 +2489,8 @@
  * @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2522,7 +2523,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see #update
  */
 public void setRedraw (boolean redraw) {
@@ -3012,7 +3013,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see PaintListener
  * @see SWT#Paint
  */
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 63ee644..09027e9 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
@@ -225,9 +225,9 @@
  * 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.
+ * chooses the icon with the "best" attributes.  It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
  * 
  * <p>
  * Note: This method will return an empty array if called before
@@ -392,7 +392,11 @@
  * <em>saved default button</em>). If no default button had
  * previously been set, or the saved default button was
  * disposed, the receiver's default button will be set to
- * null. 
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
  *
  * @param button the new default button
  *
@@ -457,8 +461,9 @@
  * 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.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
  * 
  * @param images the new image array
  *
@@ -503,7 +508,7 @@
  * causes the receiver to switch back to either the minimized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -557,7 +562,7 @@
  * causes the receiver to switch back to either the maximized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -584,7 +589,7 @@
 /**
  * Sets the receiver's text, which is the string that the
  * window manager will typically display as the receiver's
- * <em>title</em>, to the argument, which may not be null. 
+ * <em>title</em>, to the argument, which must not be null. 
  *
  * @param string the new text
  *
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 8ba03e0..b46930b 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
@@ -83,6 +83,8 @@
  * the directories it shows.
  *
  * @return the filter path
+ * 
+ * @see #setFilterPath
  */
 public String getFilterPath () {
 	return filterPath;
@@ -192,9 +194,15 @@
 }
 
 /**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the filter path
  */
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 312ade5..09c8a42 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
@@ -491,9 +491,16 @@
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The caller of this method continues 
  * to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed.  Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -647,7 +654,7 @@
  * </p>
  *
  * @exception SWTException <ul>
- *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
  *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
  * </ul>
  *
@@ -660,6 +667,11 @@
 	this (null);
 }
 
+/**
+ * Constructs a new instance of this class using the parameter.
+ * 
+ * @param data the device data
+ */
 public Display (DeviceData data) {
 	super (data);
 }
@@ -888,7 +900,7 @@
  * <p>
  * This method is called after <code>release</code>.
  * </p>
- * @see #dispose
+ * @see Device#dispose
  * @see #release
  */
 protected void destroy () {
@@ -903,7 +915,8 @@
 /**
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed.  Specifying a <code>null</code> runnable
+ * is ignored.
  *
  * @param runnable code to run at dispose time.
  * 
@@ -1021,7 +1034,9 @@
 /**
  * Returns the display which the given thread is the
  * user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display.  Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display. 
  *
  * @param thread the user-interface thread
  * @return the display for the given thread
@@ -1230,7 +1245,7 @@
  * Applications may have associated arbitrary objects with the
  * receiver in this fashion. If the objects stored in the
  * properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1267,7 +1282,7 @@
  * Applications may put arbitrary objects in this field. If
  * the object stored in the display specific data needs to
  * be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1386,9 +1401,8 @@
 }
 
 /**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
  *
  * @return the maximum icon depth
  *
@@ -1396,6 +1410,8 @@
  *    <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 Device#getDepth
  */
 public int getIconDepth () {
 	return getDepth ();
@@ -1539,8 +1555,8 @@
 }
 
 /**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
  *
  * @return the receiver's shells
  *
@@ -2733,7 +2749,7 @@
  * </p>
  * This method is called before <code>destroy</code>.
  * 
- * @see #dispose
+ * @see Device#dispose
  * @see #destroy
  */
 protected void release () {
@@ -3200,9 +3216,10 @@
 /**
  * On platforms which support it, sets the application name
  * to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup.  Specifying
+ * <code>null</code> for the name clears it.
  *
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
  */
 public static void setAppName (String name) {
 	APP_NAME = name;
@@ -3470,9 +3487,16 @@
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes.  Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ * 
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -3512,6 +3536,12 @@
  * be invoked by the user-interface thread after the specified
  * number of milliseconds have elapsed. If milliseconds is less
  * than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
  * @param milliseconds the delay before running the runnable
  * @param runnable code to run on the user-interface thread
@@ -3651,7 +3681,7 @@
 }
 
 /**
- * If the receiver's user-interface thread was <code>sleep</code>'ing, 
+ * If the receiver's user-interface thread was <code>sleep</code>ing, 
  * causes it to be awakened and start running again. Note that this
  * method may be called from any thread.
  * 
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 19486b3..7ef3bcd 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
@@ -24,6 +24,8 @@
  * <dd>(none)</dd>
  * </dl>
  * <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
@@ -82,7 +84,8 @@
 
 /**
  * Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
  * 
  * @return the relative path of the file
  */
@@ -91,8 +94,8 @@
 }
 
 /**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
  * 
  * @return the relative paths of the files
  */
@@ -111,19 +114,19 @@
 }
 
 /**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
  *
- * @return the file name filter
+ * @return the list of filter names
  */
 public String [] getFilterNames () {
 	return filterNames;
 }
 
 /**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set.  File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
  *
  * @return the directory path string
  * 
@@ -300,6 +303,11 @@
  * Set the file extensions which the dialog will
  * use to filter the files it shows to the argument,
  * which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
  *
  * @param extensions the file extension filter
  */
@@ -308,11 +316,11 @@
 }
 
 /**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
  *
- * @param names the file name filter
+ * @param names the list of filter names
  */
 public void setFilterNames (String [] names) {
 	filterNames = names;
@@ -322,7 +330,14 @@
  * Sets the directory path that the dialog will use
  * to the argument, which may be null. File names in this
  * path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the directory path
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
index b5bbb2f..f1ca24e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
@@ -24,6 +24,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection</dd>
  * </dl>
@@ -665,7 +666,7 @@
  * is delimited by an anchor tag, &lt;A&gt; and &lt;/A&gt;.  Within an
  * anchor, a single HREF attribute is supported.  When a hyperlink is
  * selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
  * In the rare case of identical hyperlinks within the same string, the
  * HREF tag can be used to distinguish between them.  The string may
  * include the mnemonic character and line delimiters.
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 e20bd08..271d9fd 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
@@ -22,7 +22,7 @@
 
 /** 
  * Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
  * when a string selected.  A list may be single or multi select.
  * <p>
  * <dl>
@@ -504,7 +504,7 @@
 
 /**
  * Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
  *
  * @return the height of one item
  *
@@ -523,8 +523,8 @@
 }
 
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -547,8 +547,8 @@
 
 /**
  * Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver.  The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -605,7 +605,7 @@
  * Returns the zero-relative index of the item which is currently
  * selected in the receiver, or -1 if no item is selected.
  *
- * @return the index of the selected item
+ * @return the index of the selected item or -1
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -621,7 +621,8 @@
 
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver.  The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1258,7 +1259,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 selected.
+ * The current selection is first cleared, then the new item is 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/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
index 60bf8a0..7616426 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
@@ -366,7 +366,7 @@
 
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -422,8 +422,8 @@
 }
 
 /**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -806,7 +806,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -961,7 +961,7 @@
 
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -984,11 +984,15 @@
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param x the new x coordinate for the receiver
@@ -1007,11 +1011,15 @@
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param location the new location for the receiver
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 924a5f2..2d28134 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
@@ -172,7 +172,7 @@
 
 /**
  * Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
  * it one of the messages defined in the <code>SelectionListener</code>
  * interface.
  * <p>
@@ -241,11 +241,13 @@
 }
 
 /**
- * Return the widget accelerator.  An accelerator is the bit-wise
+ * Returns the widget accelerator.  An accelerator is the bit-wise
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
- * @return the accelerator
+ * @return the accelerator or 0
  *
  * </ul>
  * @exception SWTException <ul>
@@ -285,7 +287,7 @@
 
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -392,7 +394,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -552,6 +554,8 @@
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
  * @param accelerator an integer that is the bit-wise OR of masks and a key
  *
@@ -595,7 +599,7 @@
 
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -627,8 +631,9 @@
 /**
  * Sets the image the receiver will display to the argument.
  * <p>
- * Note: This feature is not available on all window systems (for example, Window NT),
- * in which case, calling this method will silently do nothing.
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept (for example, Windows NT).
+ * </p>
  *
  * @param image the image to display
  *
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 79f6c5f..82e859a 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
@@ -102,9 +102,9 @@
 }
 
 /**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
  *
  * @return the message
  */
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 d3dd8b3..1448c98 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
@@ -134,7 +134,7 @@
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
  *
  * @return the selection
  *
@@ -193,7 +193,7 @@
 }
 
 /**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
  * position to the argument which must be greater than or equal
  * to zero.
  *
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 2b0be7a..03b412d 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
@@ -204,7 +204,7 @@
 }
 
 /**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
  *
  * @return the selection
  *
@@ -350,9 +350,8 @@
 }
 
 /**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
  *
  * @param value the new selection (must be zero or greater)
  *
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 f1e5bcf..336499e 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
@@ -23,7 +23,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given scroll bar will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the scroll bar represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -106,6 +106,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -301,7 +302,7 @@
 }
 
 /**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
  *
  * @return the receiver's parent
  *
@@ -316,7 +317,7 @@
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
  *
  * @return the selection
  *
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 8a3edd4..7afa773 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
@@ -70,7 +70,7 @@
  * it would be upgraded to <code>APPLICATION_MODAL</code>.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
  * <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -268,7 +268,7 @@
  * @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>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -302,6 +302,9 @@
  * @param parent a shell which will be the parent of the new instance
  * @param style the style of control to construct
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</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>
@@ -316,6 +319,8 @@
  * @see SWT#NO_TRIM
  * @see SWT#SHELL_TRIM
  * @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
  * @see SWT#MODELESS
  * @see SWT#PRIMARY_MODAL
  * @see SWT#APPLICATION_MODAL
@@ -1297,7 +1302,7 @@
 }
 
 /**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
@@ -1334,7 +1339,7 @@
 }
 
 /**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
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 30825a4..96af397 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
@@ -23,7 +23,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given slider will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the slider represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -111,7 +111,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -279,7 +279,7 @@
 }
 
 /**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
  *
  * @return the selection
  *
@@ -475,7 +475,7 @@
 }
 
 /**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
  * value, to the argument which must be greater than or equal
  * to zero.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
index 45c9ab5..ac7393a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
@@ -27,7 +27,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection, Modify</dd>
  * </dl>
@@ -69,6 +69,7 @@
  * </ul>
  *
  * @see SWT#READ_ONLY
+ * @see SWT#WRAP
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -363,6 +364,16 @@
 	return textHandle;
 }
 
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public int getDigits () {
 	checkWidget ();
 	return digits;
@@ -797,6 +808,25 @@
 	setBackground (textHandle, color);
 }
 
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with 
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs. 
+ * 
+ * @param value the new digits (must be greater than or equal to zero)
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</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 setDigits (int value) {
 	checkWidget ();
 	if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT);
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 b919388..d497864 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
@@ -90,6 +90,7 @@
  * @see SWT#CHECK
  * @see SWT#FULL_SELECTION
  * @see SWT#HIDE_SELECTION
+ * @see SWT#VIRTUAL
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -1236,8 +1237,8 @@
 }
 
 /**
- * Returns an array of <code>TableItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>TableItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -1288,8 +1289,8 @@
 
 /**
  * Returns an array of <code>TableItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1362,7 +1363,8 @@
 
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -2313,7 +2315,7 @@
 
 /**
  * Selects the item at the given zero-relative index in the receiver. 
- * The current selected is first cleared, then the new item is selected.
+ * The current selection is first cleared, then the new item is selected.
  *
  * @param index the index of the item to select
  *
@@ -2507,8 +2509,8 @@
  * @param column the column to be shown
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the item is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the column is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the column 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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
index 2901f4d..577c533 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
@@ -160,7 +160,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public Color getBackground () {
 	checkWidget ();
@@ -298,7 +297,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public Color getForeground () {
 	checkWidget ();
@@ -379,7 +377,8 @@
 /**
  * Returns a rectangle describing the size and location
  * relative to its parent of an image at a column in the
- * table.
+ * table.  An empty rectangle is returned if index exceeds
+ * the index of the table's last column.
  *
  * @param index the index that specifies the column
  * @return the receiver's bounding image rectangle
@@ -546,7 +545,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public void setBackground (Color color) {
 	checkWidget ();
@@ -576,7 +574,6 @@
  * </ul>
  * 
  * @since 3.0
- * 
  */
 public void setBackground (int index, Color color) {
 	checkWidget ();
@@ -692,7 +689,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public void setForeground (Color color) {
 	checkWidget ();
@@ -722,7 +718,6 @@
  * </ul>
  * 
  * @since 3.0
- * 
  */
 public void setForeground (int index, Color color){
 	checkWidget ();
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 3574bee..54b8e66 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
@@ -45,6 +45,10 @@
 	/**
 	* The maximum number of characters that can be entered
 	* into a text widget.
+	* <p>
+	* Note that this value is platform dependent, based upon
+	* the native widget implementation.
+	* </p>
 	*/
 	public static final int LIMIT;
 	/**
@@ -446,7 +450,7 @@
 }
 
 /**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
  * <p>
  * The line number of the caret is returned.
  * </p>
@@ -465,7 +469,8 @@
 }
 
 /**
- * Gets the location the caret.
+ * Returns a point describing the receiver's location relative
+ * to its parent (or its display if its parent is null).
  * <p>
  * The location of the caret is returned.
  * </p>
@@ -489,9 +494,9 @@
 }
 
 /**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
  * <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
  * </p>
  *
  * @return the position of the caret
@@ -509,7 +514,7 @@
 }
 
 /**
- * Gets the number of characters.
+ * Returns the number of characters.
  *
  * @return number of characters in the widget
  *
@@ -534,7 +539,7 @@
 }
 
 /**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
  * <p>
  * The double click flag enables or disables the
  * default action of the text widget when the user
@@ -555,7 +560,7 @@
 }
 
 /**
- * Gets the echo character.
+ * Returns the echo character.
  * <p>
  * The echo character is the character that is
  * displayed when the user enters text or the
@@ -568,6 +573,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 #setEchoChar
  */
 public char getEchoChar () {
 	checkWidget();
@@ -575,7 +582,7 @@
 }
 
 /**
- * Gets the editable state.
+ * Returns the editable state.
  *
  * @return whether or not the reciever is editable
  * 
@@ -590,7 +597,7 @@
 }
 
 /**
- * Gets the number of lines.
+ * Returns the number of lines.
  *
  * @return the number of lines in the widget
  *
@@ -607,7 +614,7 @@
 }
 
 /**
- * Gets the line delimiter.
+ * Returns the line delimiter.
  *
  * @return a string that is the line delimiter
  *
@@ -615,6 +622,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 #DELIMITER
  */
 public String getLineDelimiter () {
 	checkWidget();
@@ -622,7 +631,7 @@
 }
 
 /**
- * Gets the height of a line.
+ * Returns the height of a line.
  *
  * @return the height of a row of text
  *
@@ -639,7 +648,8 @@
 }
 
 /**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  *
  * @return the orientation style
  * 
@@ -656,14 +666,17 @@
 }
 
 /**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
  * <p>
- * Indexing is zero based.  The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
  * </p>
- * 
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -678,7 +691,7 @@
 }
 
 /**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
  *
  * @return the number of selected characters.
  *
@@ -695,7 +708,7 @@
 }
 
 /**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
  *
  * @return the selected text
  * 
@@ -710,7 +723,7 @@
 }
 
 /**
- * Gets the number of tabs.
+ * Returns the number of tabs.
  * <p>
  * Tab stop spacing is specified in terms of the
  * space (' ') character.  The width of a single
@@ -731,9 +744,10 @@
 }
 
 /**
- * Gets the widget text.
+ * Returns the widget text.
  * <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
  * </p>
  *
  * @return the widget text
@@ -749,7 +763,7 @@
 }
 
 /**
- * Gets a range of text.  Returns an empty string if the
+ * Returns 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
@@ -788,6 +802,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -815,7 +831,7 @@
 }
 
 /**
- * Gets the top pixel.
+ * Returns the top pixel.
  * <p>
  * The top pixel is the pixel position of the line
  * that is currently at the top of the widget.  On
@@ -888,6 +904,9 @@
  *
  * @param string the string
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1228,6 +1247,9 @@
  * The double click flag enables or disables the
  * default action of the text widget when the user
  * double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
  * </p>
  * 
  * @param doubleClick the new double click flag
@@ -1251,8 +1273,9 @@
  * the echo character to '\0' clears the echo
  * character and redraws the original text.
  * If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
  * </p>
  *
  * @param echo the new echo character
@@ -1336,6 +1359,9 @@
  * Sets the orientation of the receiver, which must be one
  * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
  *
  * @param orientation new orientation style
  * 
@@ -1379,7 +1405,8 @@
 }
 
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1412,7 +1439,10 @@
 }
 
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1556,6 +1586,8 @@
  * creating a read-only text widget.
  * </p><p>
  * To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
  * </p>
  *
  * @param limit new text limit
@@ -1567,6 +1599,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget();
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 e998fc1..d31b639 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
@@ -24,7 +24,7 @@
 
 /**
  * Instances of this class provide a selectable user interface object
- * that displays a hierarchy of items and issue notificiation when an
+ * that displays a hierarchy of items and issue notification when an
  * item in the hierarchy is selected.
  * <p>
  * The item children that may be added to instances of this class
@@ -921,6 +921,23 @@
 	return height [0] != 0;
 }
 
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @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>
+ * 
+ * @since 3.1
+ */
 public TreeItem getItem (int index) {
 	checkWidget ();
 	if (index < 0) error (SWT.ERROR_INVALID_RANGE);
@@ -1024,8 +1041,8 @@
 }
 
 /**
- * Returns the items contained in the receiver
- * that are direct item children of the receiver.  These
+ * Returns a (possibly empty) array of items contained in the
+ * receiver that are direct item children of the receiver.  These
  * are the roots of the tree.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -1103,8 +1120,8 @@
 
 /**
  * Returns an array of <code>TreeItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1219,6 +1236,25 @@
 	OS.SetDataBrowserCustomCallbacks (handle, custom);
 }
 
+/**
+ * Searches the receiver's list starting at the first column
+ * (index 0) until a column is found that is equal to the 
+ * argument, and returns the index of that column. If no column
+ * is found, returns -1.
+ *
+ * @param column the search column
+ * @return the index of the column
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <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>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public int indexOf (TreeColumn column) {
 	checkWidget ();
 	if (column == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1229,6 +1265,26 @@
 	return -1;
 }
 
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the 
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the tool item 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.1
+ */
 public int indexOf (TreeItem item) {
 	checkWidget ();
 	if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
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 c9d3b0d..5031e7c 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
@@ -58,7 +58,7 @@
  * 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 parent a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  *
  * @exception IllegalArgumentException <ul>
@@ -94,7 +94,7 @@
  * 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 parent a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  * @param index the index to store the receiver in its parent
  *
@@ -132,7 +132,7 @@
  * Style bits are also inherited from superclasses.
  * </p>
  *
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  *
  * @exception IllegalArgumentException <ul>
@@ -169,7 +169,7 @@
  * Style bits are also inherited from superclasses.
  * </p>
  *
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  * @param index the index to store the receiver in its parent
  *
@@ -544,6 +544,23 @@
 	return new Rectangle (x, y, width, height);
 }
 
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @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>
+ * 
+ * @since 3.1
+ */
 public TreeItem getItem (int index) {
 	checkWidget ();
 	if (index < 0) error (SWT.ERROR_INVALID_RANGE);
@@ -577,8 +594,8 @@
 }
 
 /**
- * Returns an array of <code>TreeItem</code>s which are the
- * direct item children of the receiver.
+ * Returns a (possibly empty) array of <code>TreeItem</code>s which
+ * are the direct item children of the receiver.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -663,6 +680,26 @@
 	return "";
 }
 
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the 
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the tool item 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.1
+ */
 public int indexOf (TreeItem item) {
 	checkWidget ();
 	if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -723,6 +760,16 @@
 	cellFont = null;
 }
 
+/**
+ * Removes all of the items from the receiver.
+ * <p>
+ * @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.1
+ */
 public void removeAll () {
 	checkWidget ();
 	TreeItem [] items = parent.items;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
index 4d91a6f..669d93a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
@@ -96,6 +96,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -741,7 +742,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(Object)
  */
 public Object getData () {
 	checkWidget();
@@ -770,7 +771,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(String, Object)
  */
 public Object getData (String key) {
 	checkWidget();
@@ -797,7 +798,6 @@
  *
  * @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 Display getDisplay () {
@@ -1544,6 +1544,8 @@
  *    <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
+ * 
+ * @see #getData()
  */
 public void setData (Object data) {
 	checkWidget();
@@ -1576,7 +1578,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #getData
+ * @see #getData(String)
  */
 public void setData (String key, Object value) {
 	checkWidget();
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 bec30ed..b4b17c7 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
@@ -201,9 +201,9 @@
  * @see Layout
  * @see #getBounds
  * @see #getSize
- * @see CoolBar#getBorderWidth
- * @see CoolBar#computeTrim
- * @see CoolBar#getClientArea
+ * @see Control#getBorderWidth
+ * @see Scrollable#computeTrim
+ * @see Scrollable#getClientArea
  */
 public Point computeSize (int wHint, int hHint) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
index 0613f50..d8fdff2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
@@ -13,16 +13,46 @@
 import org.eclipse.swt.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent paths through the two-dimensional
+ * coordinate system. Paths do not have to be continuous, and can be
+ * described using lines, rectangles, arcs, cubic or quadratic bezier curves,
+ * glyphs, or other paths.
+ * <p>
+ * Application code must explicitly invoke the <code>Path.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Path extends Resource {
 	
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Path
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int handle;
 	
+/**
+ * Constructs a new empty Path.
+ * 
+ * @param device the device on which to allocate the path
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the path could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Path (Device device) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -32,26 +62,120 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**
+ * Adds to the receiver a circular or elliptical arc that lies within
+ * the specified rectangular area.
+ * <p>
+ * The resulting arc begins at <code>startAngle</code> and extends  
+ * for <code>arcAngle</code> degrees.
+ * Angles are interpreted such that 0 degrees is at the 3 o'clock
+ * position. A positive value indicates a counter-clockwise rotation
+ * while a negative value indicates a clockwise rotation.
+ * </p><p>
+ * The center of the arc is the center of the rectangle whose origin 
+ * is (<code>x</code>, <code>y</code>) and whose size is specified by the 
+ * <code>width</code> and <code>height</code> arguments. 
+ * </p><p>
+ * The resulting arc covers an area <code>width + 1</code> pixels wide
+ * by <code>height + 1</code> pixels tall.
+ * </p>
+ *
+ * @param x the x coordinate of the upper-left corner of the arc
+ * @param y the y coordinate of the upper-left corner of the arc
+ * @param width the width of the arc
+ * @param height the height of the arc
+ * @param startAngle the beginning angle
+ * @param arcAngle the angular extent of the arc, relative to the start angle
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addArc(float x, float y, float width, float height, float startAngle, float arcAngle) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Adds to the receiver the path described by the parameter.
+ *
+ * @param path the path to add to the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addPath(Path path) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	if (path.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 }
 
+/**
+ * Adds to the receiver the rectangle specified by x, y, width and height.
+ *
+ * @param x the x coordinate of the rectangle to add
+ * @param y the y coordinate of the rectangle to add
+ * @param width the width of the rectangle to add
+ * @param height the height of the rectangle to add
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void addRectangle(float x, float y, float width, float height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Adds to the receiver the pattern of glyphs generated by drawing
+ * the given string using the given font starting at the point (x, y).
+ *
+ * @param string the text to use
+ * @param x the x coordinate of the starting point
+ * @param y the y coordinate of the starting point
+ * @param font the font to use
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the font is null</li>
+ *    <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 addString(String string, float x, float y, Font font) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (font == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	if (font.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 }
 
+/**
+ * Returns <code>true</code> if the specified point is contained by
+ * the receiver and false otherwise.
+ * <p>
+ * If outline is <code>true</code>, the point (x, y) checked for containment in
+ * the receiver's outline. If outline is <code>false</code>, the point is
+ * checked to see if it is contained within the bounds of the (closed) area
+ * covered by the receiver.
+ *
+ * @param x the x coordinate of the point to test for containment
+ * @param y the y coordinate of the point to test for containment
+ * @param gc the GC to use when testing for containment
+ * @param outline controls wether to check the outline or contained area of the path
+ * @return <code>true</code> if the path contains the point and <code>false</code> otherwise
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public boolean contains(float x, float y, GC gc, boolean outline) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -59,6 +183,15 @@
 	return false;
 }
 
+/**
+ * Closes the current sub path by adding to the receiver a line
+ * from the current point of the path back to the starting point
+ * of the sub path.
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void close() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
@@ -67,30 +200,99 @@
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Replaces the first four elements in the parameter with values that
+ * describe the smallest rectangle that will completely contain the
+ * receiver (i.e. the bounding box).
+ *
+ * @param bounds the array to hold the result
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void getBounds(float[] bounds) {
     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
     if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
     if (bounds.length < 4) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 }
 
+/**
+ * Replaces the first two elements in the parameter with values that
+ * describe the current point of the path.
+ *
+ * @param point the array to hold the result
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void getCurrentPoint(float[] point) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	if (point.length < 2) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 }
 
+/**
+ * Adds to the receiver a line from the current point to
+ * the point specified by (x, y).
+ *
+ * @param x the x coordinate of the end of the line to add
+ * @param y the y coordinate of the end of the line to add
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void lineTo(float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Sets the current point of the receiver to the point
+ * specified by (x, y). Note that this starts a new
+ * sub path.
+ *
+ * @param x the x coordinate of the new end point
+ * @param y the y coordinate of the new end point
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void moveTo(float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Adds to the receiver a quadratic curve based on the parameters.
+ *
+ * @param cx the x coordinate of the control point of the spline
+ * @param cy the y coordinate of the control point of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void quadTo(float cx, float cy, float x, float y) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Path. Applications must dispose of all Paths that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	handle = 0;
@@ -98,10 +300,26 @@
 	device = null;
 }
 
+/**
+ * Returns <code>true</code> if the Path has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Path.
+ * When a Path has been disposed, it is an error to
+ * invoke any other method using the Path.
+ *
+ * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Path {*DISPOSED*}";
 	return "Path {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
index 48967f3..c0a8d2c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
@@ -13,16 +13,47 @@
 import org.eclipse.swt.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent patterns to use while drawing. Patterns
+ * can be specified either as bitmaps or gradients.
+ * <p>
+ * Application code must explicitly invoke the <code>Pattern.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Pattern extends Resource {
 
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Pattern
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int handle;
 
+/**
+ * Constructs a new Pattern given an image. Drawing with the resulting
+ * pattern will cause the image to be tiled over the resulting area.
+ * 
+ * @param device the device on which to allocate the pattern
+ * @param image the image that the pattern will draw
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Pattern(Device device, Image image) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -33,6 +64,30 @@
 	if (device.tracking) device.new_Object(this);
 }
 
+/**
+ * Constructs a new Pattern that represents a linear, two color
+ * gradient. Drawing with the pattern will cause the resulting area to be
+ * tiled with the gradient specified by the arguments.
+ * 
+ * @param device the device on which to allocate the pattern
+ * @param x1 the x coordinate of the starting corner of the gradient
+ * @param y1 the y coordinate of the starting corner of the gradient
+ * @param x2 the x coordinate of the ending corner of the gradient
+ * @param y2 the y coordinate of the ending corner of the gradient
+ * @param color1 the starting color of the gradient
+ * @param color2 the ending color of the gradient
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, 
+ *                              or if either color1 or color2 is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Pattern(Device device, float x1, float y1, float x2, float y2, Color color1, Color color2) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -45,6 +100,11 @@
 	if (device.tracking) device.new_Object(this);
 }
 	
+/**
+ * Disposes of the operating system resources associated with
+ * the Pattern. Applications must dispose of all Patterns that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	if (device.isDisposed()) return;
@@ -53,10 +113,26 @@
 	device = null;
 }
 
+/**
+ * Returns <code>true</code> if the Pattern has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Pattern.
+ * When a Pattern has been disposed, it is an error to
+ * invoke any other method using the Pattern.
+ *
+ * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Pattern {*DISPOSED*}";
 	return "Pattern {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
index bc15868..4d75e26 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
@@ -13,23 +13,89 @@
 import org.eclipse.swt.*;
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent transformation matrices for 
+ * points expressed as (x, y) pairs of floating point numbers.
+ * <p>
+ * Application code must explicitly invoke the <code>Transform.dispose()</code> 
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Transform extends Resource {
 	/**
-	 * the handle to the OS path resource
+	 * the OS resource for the Transform
 	 * (Warning: This field is platform dependent)
+	 * <p>
+	 * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+	 * public API. It is marked public only so that it can be shared
+	 * within the packages provided by SWT. It is not available on all
+	 * platforms and should never be accessed from application code.
+	 * </p>
 	 */
 	public int handle;
 	
+/**
+ * Constructs a new identity Transform.
+ * 
+ * @param device the device on which to allocate the Transform
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform (Device device) {
 	this(device, 1, 0, 0, 1, 0, 0);
 }
 
+/**
+ * Constructs a new Transform given an array of elements that represent the 
+ * matrix that describes the transformation.
+ * 
+ * @param device the device on which to allocate the Transform
+ * @param elements an array of floats that describe the transformation matrix
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform(Device device, float[] elements) {
 	this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
 }
 
+/**
+ * Constructs a new Transform given all of the elements that represent the 
+ * matrix that describes the transformation.
+ * 
+ * @param device the device on which to allocate the Transform
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ * 
+ * @see #dispose()
+ */
 public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
 	if (device == null) device = Device.getDevice();
 	if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -44,6 +110,11 @@
 	return elements;
 }
 
+/**
+ * Disposes of the operating system resources associated with
+ * the Transform. Applications must dispose of all Transforms that
+ * they allocate.
+ */
 public void dispose() {
 	if (handle == 0) return;
 	if (device.isDisposed()) return;
@@ -52,20 +123,60 @@
 	device = null;
 }
 
+/**
+ * Fills the parameter with the values of the transformation matrix
+ * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
+ *
+ * @param elements array to hold the matrix values
+ * @return (in elements array) the transformation matrix represented by the receiver
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
+ * </ul>
+ */
 public void getElements(float[] elements) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	if (elements.length < 6) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 }
 
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the mathematical inverse of the matrix it previously represented. 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertable</li>
+ * </ul>
+ */
 public void invert() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Returns <code>true</code> if the Transform has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Transform.
+ * When a Transform has been disposed, it is an error to
+ * invoke any other method using the Transform.
+ *
+ * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
+ */
 public boolean isDisposed() {
 	return handle == 0;
 }
 
+/**
+ * Returns <code>true</code> if the Transform represents the identity matrix
+ * and false otherwise.
+ *
+ * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
+ */
 public boolean isIdentity() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	float[] m  = new float[6];
@@ -73,33 +184,118 @@
 	return m[0] == 1 && m[1] == 0 && m[2] == 0 && m[3] == 1 && m[4] == 0 && m[5] == 0;
 }
 
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the result of multiplying the matrix it previously represented by the
+ * argument. 
+ *
+ * @param matrix the matrix to multiply the receiver by
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ */
 public void multiply(Transform matrix) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 	if (matrix.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation rotated by the specified angle.
+ * The angle is specified in degrees and for the identity transform 0 degrees
+ * is at the 3 o'clock position. A positive value indicates a clockwise rotation
+ * while a negative value indicates a counter-clockwise rotation.
+ *
+ * @param angle the angle to rotate the transformation by
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void rotate(float angle) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation scaled by (scaleX, scaleY).
+ * 
+ * @param scaleX the amount to scale in the X direction
+ * @param scaleY the amount to scale in the Y direction
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void scale(float scaleX, float scaleY) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Modifies the receiver to represent a new transformation given all of
+ * the elements that represent the matrix that describes that transformation.
+ * 
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/** 
+ * Given an array containing points described by alternating x and y values,
+ * modify that array such that each point has been replaced with the result of
+ * applying the transformation represented by the receiver to that point.
+ *
+ * @param pointArray an array of alternating x and y values to be transformed
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
+ * </ul>	
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void transform(float[] pointArray) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 }
 
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation translated by (offsetX, offsetY).
+ * 
+ * @param offsetX the distance to translate in the X direction
+ * @param offsetY the distance to translate in the Y direction
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
 public void translate(float offsetX, float offsetY) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
 public String toString() {
 	if (isDisposed()) return "Transform {*DISPOSED*}";
 	float[] elements = new float[6];
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 fe0616c..a55c4a9 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
@@ -105,6 +105,7 @@
  * @see SWT#CHECK
  * @see SWT#FULL_SELECTION
  * @see SWT#HIDE_SELECTION
+ * @see SWT#VIRTUAL
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -933,8 +934,8 @@
 	return itemHeight;
 }
 /**
- * Returns an array of <code>TableItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>TableItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -987,8 +988,8 @@
 }
 /**
  * Returns an array of <code>TableItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1049,7 +1050,8 @@
 }
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -3171,7 +3173,7 @@
 }
 /**
  * Selects the item at the given zero-relative index in the receiver. 
- * The current selected is first cleared, then the new item is selected.
+ * The current selection is first cleared, then the new item is selected.
  *
  * @param index the index of the item to select
  *
@@ -3300,8 +3302,8 @@
  * @param column the column to be shown
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the item is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the column is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the column 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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
index ea935ed..4465ca1 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
@@ -753,7 +753,8 @@
 /**
  * Returns a rectangle describing the size and location
  * relative to its parent of an image at a column in the
- * table.
+ * table.  An empty rectangle is returned if index exceeds
+ * the index of the table's last column.
  *
  * @param index the index that specifies the column
  * @return the receiver's bounding image rectangle
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 1bbae92..b7883b4 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
@@ -17,7 +17,7 @@
 
 /**
  * Instances of this class provide a selectable user interface object
- * that displays a hierarchy of items and issue notificiation when an
+ * that displays a hierarchy of items and issue notification when an
  * item in the hierarchy is selected.
  * <p>
  * The item children that may be added to instances of this class
@@ -694,12 +694,14 @@
  * @return the item at the given index
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of root elements minus 1 (inclusive)</li>
+ *    <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>
+ * 
+ * @since 3.1
  */
 public TreeItem getItem (int index) {
 	checkWidget ();
@@ -739,8 +741,8 @@
 	return itemHeight;
 }
 /**
- * Returns the items contained in the receiver
- * that are direct item children of the receiver.  These
+ * Returns a (possibly empty) array of items contained in the
+ * receiver that are direct item children of the receiver.  These
  * are the roots of the tree.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -810,8 +812,8 @@
 }
 /**
  * Returns an array of <code>TreeItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1078,12 +1080,51 @@
 	gc.setForeground (display.getSystemColor (SWT.COLOR_WIDGET_DARK_SHADOW));
 	gc.drawLine (endX - 1, y, endX - 1, height - 1);		/* dark outer shadow */
 }
+/**
+ * Searches the receiver's list starting at the first column
+ * (index 0) until a column is found that is equal to the 
+ * argument, and returns the index of that column. If no column
+ * is found, returns -1.
+ *
+ * @param column the search column
+ * @return the index of the column
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <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>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public int indexOf (TreeColumn column) {
 	checkWidget ();
 	if (column == null) error (SWT.ERROR_NULL_ARGUMENT);
 	if (column.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT);
 	return column.getIndex ();
 }
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the 
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the tool item 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.1
+ */
 public int indexOf (TreeItem item) {
 	checkWidget ();
 	if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
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 e1d6e4c..0cf96c9 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
@@ -66,7 +66,7 @@
  * 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 parent a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  *
  * @exception IllegalArgumentException <ul>
@@ -111,7 +111,7 @@
  * 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 parent a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  * @param index the index to store the receiver in its parent
  *
@@ -158,7 +158,7 @@
  * Style bits are also inherited from superclasses.
  * </p>
  *
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  *
  * @exception IllegalArgumentException <ul>
@@ -205,7 +205,7 @@
  * Style bits are also inherited from superclasses.
  * </p>
  *
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  * @param index the index to store the receiver in its parent
  *
@@ -1082,19 +1082,21 @@
 	return -1;
 }
 /**
- * Returns the child item with the given, zero-relative index in the
+ * Returns the item at the given, zero-relative index in the
  * receiver. Throws an exception if the index is out of range.
  *
  * @param index the index of the item to return
  * @return the item at the given index
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of child elements minus 1 (inclusive)</li>
+ *    <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>
+ * 
+ * @since 3.1
  */
 public TreeItem getItem (int index) {
 	checkWidget ();
@@ -1117,8 +1119,8 @@
 	return items.length;
 }
 /**
- * Returns an array of <code>TreeItem</code>s which are the
- * direct item children of the receiver.
+ * Returns a (possibly empty) array of <code>TreeItem</code>s which
+ * are the direct item children of the receiver.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -1238,6 +1240,26 @@
 	if (parentItem == null) return false;
 	return parentItem.hasAncestor (item);
 }
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the 
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the tool item 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.1
+ */
 public int indexOf (TreeItem item) {
 	checkWidget ();
 	if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1578,6 +1600,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>
+ *
+ * @since 3.1
  */
 public void removeAll () {
 	checkWidget ();
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 06b52e7..15f71c6 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
@@ -191,7 +191,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 a7f20b0..8c74fd0 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
@@ -417,7 +417,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 2cd7ac8..ca2baf8 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
@@ -433,7 +433,7 @@
  * specified in class <code>SWT</code>. Any value other
  * than one of the SWT color constants which is passed
  * in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
  * not the application.
  *
  * @param id the color constant
@@ -472,7 +472,7 @@
  * Returns a reasonable font for applications to use.
  * On some platforms, this will match the "default font"
  * or "system font" if such can be found.  This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
  * system, not the application.
  * <p>
  * Typically, applications which want the default look
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
index 0137471..9b1d8b5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
@@ -227,7 +227,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 76b22c8..68798e3 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
@@ -290,7 +290,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -392,7 +392,8 @@
 /**
  * Sets the style of the receiver to the argument which must
  * be a bitwise OR of one or more of the <code>SWT</code> 
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC.  All other style bits are
+ * ignored.
  *
  * @param style the new style for this <code>FontData</code>
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java
index 96b962c..8abe3cf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java
@@ -117,7 +117,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 e44ada9..8c10ea7 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
@@ -195,6 +195,24 @@
 public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY) {
 	copyArea(srcX, srcY, width, height, destX, destY, true);
 }
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1 
+ */
 public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY, boolean paint) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (width <= 0 || height <= 0) return;
@@ -354,7 +372,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void drawFocus(int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -713,8 +731,22 @@
 	OS.gdk_draw_arc(data.drawable, handle, 0, x, y, width, height, 0, 23040);
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void drawPath(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1259,7 +1291,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1372,8 +1404,22 @@
 	OS.gdk_gc_set_foreground(handle, color);
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void fillPath (Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1458,7 +1504,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle(int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1508,7 +1554,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle(Rectangle rect) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1648,13 +1694,45 @@
 	return stringExtent(new String(new char[]{ch})).x;
 }
 
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem.  Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, <code>false</code> is always returned.  Some operating system have
+ * only one graphics subsystem.  If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned.  If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned.  If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAdvanced
+ * @since 3.1
+ */
 public boolean getAdvanced() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.cairo != 0;
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getAlpha() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1663,7 +1741,20 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getTextAntialias
+ * 
+ * @since 3.1
  */
 public int getAntialias() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1691,8 +1782,19 @@
 	return Color.gtk_new(data.device, color);	
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public Pattern getBackgroundPattern() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1791,6 +1893,18 @@
 	}
 }
 
+/** 
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public int getFillRule() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	int /*long*/ cairo = data.cairo;
@@ -1858,16 +1972,37 @@
 	return Color.gtk_new(data.device, color);	
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public Pattern getForegroundPattern() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.foregroundPattern;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getInterpolation() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1901,7 +2036,8 @@
 }
 
 /** 
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
  *
  * @return the lin dash style used for drawing lines
  *
@@ -2006,15 +2142,43 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAntialias
+ * 
+ * @since 3.1
  */
 public int getTextAntialias() {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
     return data.textAntialias;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void getTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2051,7 +2215,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -2200,6 +2364,48 @@
 	return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0;
 }
 
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is 
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested.  When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations.  Because the two subsystems are
+ * different, their output may differ.  Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, this operation does nothing.  Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing.  However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ * 
+ * @since 3.1
+ */
 public void setAdvanced(boolean advanced) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (advanced && data.cairo != 0) return;
@@ -2222,7 +2428,15 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setAlpha(int alpha) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2232,7 +2446,24 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setTextAntialias
+ * 
+ * @since 3.1
  */
 public void setAntialias(int antialias) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2272,8 +2503,21 @@
 	data.backgroundPattern = null;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public void setBackgroundPattern(Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2391,7 +2635,22 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void setClipping(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2409,9 +2668,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
  *
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -2428,9 +2689,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the region specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
  *
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
  * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -2473,6 +2736,22 @@
 	}
 }
 
+/** 
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ *                                 or <code>SWT.FILL_WINDING</code></li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public void setFillRule(int rule) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	int cairo_mode = Cairo.CAIRO_FILL_RULE_EVEN_ODD;
@@ -2519,8 +2798,21 @@
 	data.foregroundPattern = null;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public void setForegroundPattern(Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2542,8 +2834,22 @@
 	data.foregroundPattern = pattern;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>, 
+ *                                 <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setInterpolation(int interpolation) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2607,7 +2913,10 @@
 }
 
 /** 
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
  *
  * @param dashes the dash style to be used for drawing lines
  * 
@@ -2771,6 +3080,12 @@
  * for all of the figure drawing operations (that is,
  * <code>drawLine</code>, <code>drawRectangle</code>, 
  * <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
  *
  * @param lineWidth the width of a line
  *
@@ -2840,7 +3155,24 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAntialias
+ * 
+ * @since 3.1
  */
 public void setTextAntialias(int antialias) {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2855,8 +3187,23 @@
     data.textAntialias = antialias;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void setTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2923,12 +3270,19 @@
  * and the destination, and if the argument is <code>false</code>,
  * puts the receiver in a drawing mode where the destination color
  * is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
  *
  * @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @deprecated this functionality is not supported on some platforms
  */
 public void setXORMode(boolean xor) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 5d7d965..775ba8b 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
@@ -54,7 +54,7 @@
  * loading process should use the support provided in class
  * <code>ImageLoader</code>.
  * </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code> 
+ * Application code must explicitly invoke the <code>Image.dispose()</code> 
  * method to release the operating system resources managed by each instance
  * when those instances are no longer required.
  * </p>
@@ -451,7 +451,20 @@
  * This constructor may be used to load a resource as follows:
  * </p>
  * <pre>
- *     new Image(device, clazz.getResourceAsStream("file.gif"));
+ *     static Image loadImage (Display display, Class clazz, String string) {
+ *          InputStream stream = clazz.getResourceAsStream (string);
+ *          if (stream == null) return null;
+ *          Image image = null;
+ *          try {
+ *               image = new Image (display, stream);
+ *          } catch (SWTException ex) {
+ *          } finally {
+ *               try {
+ *                    stream.close ();
+ *               } catch (IOException ex) {}
+ *          }
+ *          return image;
+ *     }
  * </pre>
  *
  * @param device the device on which to create the image
@@ -806,7 +819,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 2600613..935ee20 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
@@ -135,7 +135,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
@@ -272,7 +271,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -376,7 +375,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects (int x, int y, int width, int height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -402,7 +401,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects(Rectangle rect) {
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -494,7 +493,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
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 ab8460f..cd10658 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
@@ -614,9 +614,9 @@
 
 /**
  * Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
  *
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
index b6971ef..b15398c1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
@@ -60,7 +60,6 @@
  * </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
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 377047c..144a51c 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
@@ -662,8 +662,8 @@
 }
 
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list. 
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -702,11 +702,16 @@
 }
 
 /**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
  *
  * @return a point representing the selection start and end
  *
@@ -754,7 +759,8 @@
 
 /**
  * Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
  *
  * @return the receiver's text
  *
@@ -808,6 +814,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -1338,8 +1346,8 @@
 /**
  * Sets the text of the item in the receiver's list at the given
  * zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
  *
  * @param index the index for the item
  * @param string the new text for the item
@@ -1532,7 +1540,11 @@
 /**
  * Sets the maximum number of characters that the receiver's
  * text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
  * @param limit new text limit
  *
  * @exception IllegalArgumentException <ul>
@@ -1542,6 +1554,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget();
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 c2b1519..5a13446 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, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
@@ -386,7 +386,7 @@
 }
 
 /**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
  * Children are returned in the order that they are drawn.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -474,7 +474,7 @@
 }
 
 /**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
  *
  * @return tabList the ordered list of controls representing the tab order
  *
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 68a7352..490a58a 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
@@ -270,7 +270,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint) {
@@ -355,7 +355,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -821,7 +821,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack () {
 	pack (true);
@@ -846,7 +846,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack (boolean changed) {
 	setSize (computeSize (SWT.DEFAULT, SWT.DEFAULT, changed));
@@ -2846,7 +2846,8 @@
  * @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2903,7 +2904,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see #update
  */
 public void setRedraw (boolean redraw) {
@@ -3363,7 +3364,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see PaintListener
  * @see SWT#Paint
  */
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 49140c1..735212c 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
@@ -326,9 +326,9 @@
  * 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.
+ * chooses the icon with the "best" attributes.  It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
  * 
  * <p>
  * Note: This method will return an empty array if called before
@@ -501,7 +501,11 @@
  * <em>saved default button</em>). If no default button had
  * previously been set, or the saved default button was
  * disposed, the receiver's default button will be set to
- * null. 
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
  *
  * @param button the new default button
  *
@@ -554,8 +558,9 @@
  * 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.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
  * 
  * @param images the new image array
  *
@@ -588,7 +593,7 @@
  * causes the receiver to switch back to either the minimized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -641,7 +646,7 @@
  * causes the receiver to switch back to either the maximized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -669,7 +674,7 @@
 /**
  * Sets the receiver's text, which is the string that the
  * window manager will typically display as the receiver's
- * <em>title</em>, to the argument, which may not be null. 
+ * <em>title</em>, to the argument, which must not be null. 
  *
  * @param string the new text
  *
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 3a28547..f2ba3bc 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
@@ -82,6 +82,8 @@
  * the directories it shows.
  *
  * @return the filter path
+ * 
+ * @see #setFilterPath
  */
 public String getFilterPath () {
 	return filterPath;
@@ -258,9 +260,15 @@
 	return answer;
 }
 /**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the filter path
  */
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 7b0f169..8c04cde 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
@@ -407,7 +407,7 @@
  * </p>
  *
  * @exception SWTException <ul>
- *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
  *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
  * </ul>
  *
@@ -420,6 +420,11 @@
 	this (null);
 }
 
+/**
+ * Constructs a new instance of this class using the parameter.
+ * 
+ * @param data the device data
+ */
 public Display (DeviceData data) {
 	super (data);
 }
@@ -574,9 +579,16 @@
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The caller of this method continues 
  * to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed.  Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -911,7 +923,7 @@
  * <p>
  * This method is called after <code>release</code>.
  * </p>
- * @see #dispose
+ * @see Device#dispose
  * @see #release
  */
 protected void destroy () {
@@ -926,7 +938,9 @@
 /**
  * Returns the display which the given thread is the
  * user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display.  Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display. 
  *
  * @param thread the user-interface thread
  * @return the display for the given thread
@@ -944,7 +958,8 @@
 /**
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed.  Specifying a <code>null</code> runnable
+ * is ignored.
  *
  * @param runnable code to run at dispose time.
  * 
@@ -1314,7 +1329,7 @@
  * Applications may have associated arbitrary objects with the
  * receiver in this fashion. If the objects stored in the
  * properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1354,7 +1369,7 @@
  * Applications may put arbitrary objects in this field. If
  * the object stored in the display specific data needs to
  * be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1518,9 +1533,8 @@
 }
 
 /**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
  *
  * @return the maximum icon depth
  *
@@ -1528,6 +1542,8 @@
  *    <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 Device#getDepth
  */
 public int getIconDepth () {
 	checkDevice ();
@@ -1624,8 +1640,8 @@
 }
 
 /**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
  *
  * @return the receiver's shells
  *
@@ -2593,7 +2609,7 @@
  * </p>
  * This method is called before <code>destroy</code>.
  * 
- * @see #dispose
+ * @see Device#dispose
  * @see #destroy
  */
 protected void release () {
@@ -2884,9 +2900,10 @@
 /**
  * On platforms which support it, sets the application name
  * to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup.  Specifying
+ * <code>null</code> for the name clears it.
  *
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
  */
 public static void setAppName (String name) {
 	APP_NAME = name;
@@ -3192,6 +3209,12 @@
  * be invoked by the user-interface thread after the specified
  * number of milliseconds have elapsed. If milliseconds is less
  * than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
  * @param milliseconds the delay before running the runnable
  * @param runnable code to run on the user-interface thread
@@ -3320,9 +3343,16 @@
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes.  Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ * 
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -3368,7 +3398,7 @@
 }
 
 /**
- * If the receiver's user-interface thread was <code>sleep</code>'ing, 
+ * If the receiver's user-interface thread was <code>sleep</code>ing, 
  * causes it to be awakened and start running again. Note that this
  * method may be called from any thread.
  * 
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 18c7256..95404d5 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
@@ -25,6 +25,8 @@
  * <dd>(none)</dd>
  * </dl>
  * <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
@@ -233,7 +235,8 @@
 }
 /**
  * Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
  * 
  * @return the relative path of the file
  */
@@ -241,8 +244,8 @@
 	return fileName;
 }
 /**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
  * 
  * @return the relative paths of the files
  */
@@ -259,18 +262,18 @@
 	return filterExtensions;
 }
 /**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
  *
- * @return the file name filter
+ * @return the list of filter names
  */
 public String [] getFilterNames () {
 	return filterNames;
 }
 /**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set.  File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
  *
  * @return the directory path string
  * 
@@ -467,6 +470,11 @@
  * Set the file extensions which the dialog will
  * use to filter the files it shows to the argument,
  * which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
  *
  * @param extensions the file extension filter
  */
@@ -474,11 +482,11 @@
 	filterExtensions = extensions;
 }
 /**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
  *
- * @param names the file name filter
+ * @param names the list of filter names
  */
 public void setFilterNames (String [] names) {
 	filterNames = names;
@@ -487,7 +495,14 @@
  * Sets the directory path that the dialog will use
  * to the argument, which may be null. File names in this
  * path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the directory path
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
index 6c53c6b..1f07d8b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
@@ -23,6 +23,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection</dd>
  * </dl>
@@ -652,7 +653,7 @@
  * is delimited by an anchor tag, &lt;A&gt; and &lt;/A&gt;.  Within an
  * anchor, a single HREF attribute is supported.  When a hyperlink is
  * selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
  * In the rare case of identical hyperlinks within the same string, the
  * HREF tag can be used to distinguish between them.  The string may
  * include the mnemonic character and line delimiters.
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 910f962..486567d 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
@@ -19,7 +19,7 @@
 
 /** 
  * Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
  * when a string selected.  A list may be single or multi select.
  * <p>
  * <dl>
@@ -420,7 +420,7 @@
 
 /**
  * Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
  *
  * @return the height of one item
  *
@@ -449,8 +449,8 @@
 }
 
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -487,8 +487,8 @@
 
 /**
  * Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver.  The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -534,7 +534,7 @@
  * Returns the zero-relative index of the item which is currently
  * selected in the receiver, or -1 if no item is selected.
  *
- * @return the index of the selected item
+ * @return the index of the selected item or -1
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -554,7 +554,8 @@
 
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver.  The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1224,7 +1225,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 selected.
+ * The current selection is first cleared, then the new item is 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/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
index 6d897bf..626c463 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
@@ -344,7 +344,7 @@
 
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -413,8 +413,8 @@
 }
 
 /**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -622,7 +622,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -808,7 +808,7 @@
 
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -829,11 +829,15 @@
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param x the new x coordinate for the receiver
@@ -853,11 +857,15 @@
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param location the new location for the receiver
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 dd0de64..356e314 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
@@ -186,7 +186,7 @@
 
 /**
  * Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
  * it one of the messages defined in the <code>SelectionListener</code>
  * interface.
  * <p>
@@ -277,11 +277,13 @@
 }
 
 /**
- * Return the widget accelerator.  An accelerator is the bit-wise
+ * Returns the widget accelerator.  An accelerator is the bit-wise
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
- * @return the accelerator
+ * @return the accelerator or 0
  *
  * </ul>
  * @exception SWTException <ul>
@@ -318,7 +320,7 @@
 
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -460,7 +462,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -593,6 +595,8 @@
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
  * @param accelerator an integer that is the bit-wise OR of masks and a key
  *
@@ -613,7 +617,7 @@
 
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -636,8 +640,9 @@
 /**
  * Sets the image the receiver will display to the argument.
  * <p>
- * Note: This feature is not available on all window systems (for example, Window NT),
- * in which case, calling this method will silently do nothing.
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept (for example, Windows NT).
+ * </p>
  *
  * @param image the image to display
  *
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 f0396de..90c4f56 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
@@ -85,9 +85,9 @@
 }
 
 /**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
  *
  * @return the message
  */
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 47f00b6..0a46089 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
@@ -120,7 +120,7 @@
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
  *
  * @return the selection
  *
@@ -196,7 +196,7 @@
 }
 
 /**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
  * position to the argument which must be greater than or equal
  * to zero.
  *
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 c26b47e..aa67875 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
@@ -213,7 +213,7 @@
 }
 
 /**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
  *
  * @return the selection
  *
@@ -348,9 +348,8 @@
 }
 
 /**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
  *
  * @param value the new selection (must be zero or greater)
  *
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 65ca2a5..7c31f5b 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
@@ -21,7 +21,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given scroll bar will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the scroll bar represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -102,6 +102,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -237,7 +238,7 @@
 }
 
 /**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
  *
  * @return the receiver's parent
  *
@@ -252,7 +253,7 @@
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
  *
  * @return the selection
  *
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 b97a539..d47f1d9 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
@@ -67,7 +67,7 @@
  * it would be upgraded to <code>APPLICATION_MODAL</code>.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
  * <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -262,7 +262,7 @@
  * @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>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -296,6 +296,9 @@
  * @param parent a shell which will be the parent of the new instance
  * @param style the style of control to construct
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</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>
@@ -310,6 +313,8 @@
  * @see SWT#NO_TRIM
  * @see SWT#SHELL_TRIM
  * @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
  * @see SWT#MODELESS
  * @see SWT#PRIMARY_MODAL
  * @see SWT#APPLICATION_MODAL
@@ -1262,7 +1267,7 @@
 }
 
 /**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
@@ -1285,7 +1290,7 @@
 }
 
 /**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
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 83632cd..4c4dd9a 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
@@ -21,7 +21,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given slider will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the slider represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -106,7 +106,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -272,7 +272,7 @@
 }
 
 /**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
  *
  * @return the selection
  *
@@ -444,7 +444,7 @@
 }
 
 /**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
  * value, to the argument which must be greater than or equal
  * to zero.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
index fe5e347..9405d91 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
@@ -24,7 +24,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection, Modify</dd>
  * </dl>
@@ -65,6 +65,7 @@
  * </ul>
  *
  * @see SWT#READ_ONLY
+ * @see SWT#WRAP
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -446,6 +447,16 @@
 	return (int) adjustment.value;
 }
 
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public int getDigits () {
 	checkWidget ();
 	return OS.gtk_spin_button_get_digits (handle);
@@ -871,6 +882,25 @@
 	OS.g_signal_handlers_unblock_matched (handle, OS.G_SIGNAL_MATCH_DATA, 0, 0, 0, 0, VALUE_CHANGED);
 }
 
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with 
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs. 
+ * 
+ * @param value the new digits (must be greater than or equal to zero)
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</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 setDigits (int value) {
 	checkWidget ();
 	if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT);
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 62aedc5..426d792 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
@@ -93,6 +93,7 @@
  * @see SWT#CHECK
  * @see SWT#FULL_SELECTION
  * @see SWT#HIDE_SELECTION
+ * @see SWT#VIRTUAL
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -1200,8 +1201,8 @@
 }
 
 /**
- * Returns an array of <code>TableItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>TableItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -1270,8 +1271,8 @@
 
 /**
  * Returns an array of <code>TableItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1337,7 +1338,8 @@
 
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -2361,7 +2363,7 @@
 
 /**
  * Selects the item at the given zero-relative index in the receiver. 
- * The current selected is first cleared, then the new item is selected.
+ * The current selection is first cleared, then the new item is selected.
  *
  * @param index the index of the item to select
  *
@@ -2531,8 +2533,8 @@
  * @param column the column to be shown
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the item is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the column is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the column 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/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
index b3b3e9f..bcadc13 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
@@ -170,7 +170,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public Color getBackground () {
 	checkWidget ();
@@ -346,7 +345,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public Color getForeground () {
 	checkWidget ();
@@ -442,7 +440,8 @@
 /**
  * Returns a rectangle describing the size and location
  * relative to its parent of an image at a column in the
- * table.
+ * table.  An empty rectangle is returned if index exceeds
+ * the index of the table's last column.
  *
  * @param index the index that specifies the column
  * @return the receiver's bounding image rectangle
@@ -613,7 +612,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public void setBackground (Color color) {
 	checkWidget ();
@@ -642,7 +640,6 @@
  * </ul>
  * 
  * @since 3.0
- * 
  */
 public void setBackground (int index, Color color) {
 	checkWidget ();
@@ -816,7 +813,6 @@
  * </ul>
  * 
  * @since 2.0
- * 
  */
 public void setForeground (Color color){
 	checkWidget ();
@@ -845,7 +841,6 @@
  * </ul>
  * 
  * @since 3.0
- * 
  */
 public void setForeground (int index, Color color){
 	checkWidget ();
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 7bc11bd..603d486 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
@@ -45,6 +45,10 @@
 	/**
 	* The maximum number of characters that can be entered
 	* into a text widget.
+	* <p>
+	* Note that this value is platform dependent, based upon
+	* the native widget implementation.
+	* </p>
 	*/
 	public final static int LIMIT;
 	/**
@@ -457,7 +461,7 @@
 }
 
 /**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
  * <p>
  * The line number of the caret is returned.
  * </p>
@@ -479,7 +483,8 @@
 }
 
 /**
- * Gets the location the caret.
+ * Returns a point describing the receiver's location relative
+ * to its parent (or its display if its parent is null).
  * <p>
  * The location of the caret is returned.
  * </p>
@@ -506,9 +511,9 @@
 }
 
 /**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
  * <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
  * </p>
  *
  * @return the position of the caret
@@ -530,7 +535,7 @@
 }
 
 /**
- * Gets the number of characters.
+ * Returns the number of characters.
  *
  * @return number of characters in the widget
  *
@@ -549,7 +554,7 @@
 }
 
 /**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
  * <p>
  * The double click flag enables or disables the
  * default action of the text widget when the user
@@ -569,7 +574,7 @@
 }
 
 /**
- * Gets the echo character.
+ * Returns the echo character.
  * <p>
  * The echo character is the character that is
  * displayed when the user enters text or the
@@ -582,6 +587,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 #setEchoChar
  */
 public char getEchoChar () {
 	checkWidget ();
@@ -594,7 +601,7 @@
 }
 
 /**
- * Gets the editable state.
+ * Returns the editable state.
  *
  * @return whether or not the reciever is editable
  * 
@@ -616,7 +623,7 @@
 }
 
 /**
- * Gets the number of lines.
+ * Returns the number of lines.
  *
  * @return the number of lines in the widget
  *
@@ -632,7 +639,7 @@
 }
 
 /**
- * Gets the line delimiter.
+ * Returns the line delimiter.
  *
  * @return a string that is the line delimiter
  *
@@ -640,6 +647,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 #DELIMITER
  */
 public String getLineDelimiter () {
 	checkWidget ();
@@ -647,7 +656,7 @@
 }
 
 /**
- * Gets the height of a line.
+ * Returns the height of a line.
  *
  * @return the height of a row of text
  *
@@ -662,7 +671,8 @@
 }
 
 /**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  *
  * @return the orientation style
  * 
@@ -679,14 +689,17 @@
 }
 
 /**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
  * <p>
- * Indexing is zero based.  The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
  * </p>
- * 
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -708,7 +721,7 @@
 }
 
 /**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
  *
  * @return the number of selected characters.
  *
@@ -724,7 +737,7 @@
 }
 
 /**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
  *
  * @return the selected text
  * 
@@ -740,7 +753,7 @@
 }
 
 /**
- * Gets the number of tabs.
+ * Returns the number of tabs.
  * <p>
  * Tab stop spacing is specified in terms of the
  * space (' ') character.  The width of a single
@@ -770,9 +783,10 @@
 }
 
 /**
- * Gets the widget text.
+ * Returns the widget text.
  * <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
  * </p>
  *
  * @return the widget text
@@ -802,7 +816,7 @@
 }
 
 /**
- * Gets a range of text.  Returns an empty string if the
+ * Returns 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
@@ -856,6 +870,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget ();
@@ -889,7 +905,7 @@
 }
 
 /**
- * Gets the top pixel.
+ * Returns the top pixel.
  * <p>
  * The top pixel is the pixel position of the line
  * that is currently at the top of the widget.  On
@@ -1141,6 +1157,9 @@
  *
  * @param string the string
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1342,6 +1361,9 @@
  * The double click flag enables or disables the
  * default action of the text widget when the user
  * double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
  * </p>
  * 
  * @param doubleClick the new double click flag
@@ -1365,8 +1387,9 @@
  * the echo character to '\0' clears the echo
  * character and redraws the original text.
  * If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
  * </p>
  *
  * @param echo the new echo character
@@ -1419,6 +1442,9 @@
  * Sets the orientation of the receiver, which must be one
  * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
  *
  * @param orientation new orientation style
  * 
@@ -1470,7 +1496,8 @@
 }
 
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1511,7 +1538,10 @@
 }
 
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1635,6 +1665,8 @@
  * creating a read-only text widget.
  * </p><p>
  * To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
  * </p>
  *
  * @param limit new text limit
@@ -1646,6 +1678,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget ();
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 1810f68..f3b4d67 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
@@ -18,7 +18,7 @@
 
 /**
  * Instances of this class provide a selectable user interface object
- * that displays a hierarchy of items and issue notificiation when an
+ * that displays a hierarchy of items and issue notification when an
  * item in the hierarchy is selected.
  * <p>
  * The item children that may be added to instances of this class
@@ -891,6 +891,23 @@
 	return OS.gtk_tree_view_get_headers_visible (handle);
 }
 
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @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>
+ * 
+ * @since 3.1
+ */
 public TreeItem getItem (int index) {
 	checkWidget();
 	int length = OS.gtk_tree_model_iter_n_children (modelHandle, 0);
@@ -1011,8 +1028,8 @@
 }
 
 /**
- * Returns the items contained in the receiver
- * that are direct item children of the receiver.  These
+ * Returns a (possibly empty) array of items contained in the
+ * receiver that are direct item children of the receiver.  These
  * are the roots of the tree.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -1115,8 +1132,8 @@
 
 /**
  * Returns an array of <code>TreeItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1503,6 +1520,7 @@
  *    <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.1
  */
 public int indexOf (TreeColumn column) {
@@ -1514,6 +1532,26 @@
 	return -1;
 }
 
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the 
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the tool item 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.1
+ */
 public int indexOf (TreeItem item) {
 	checkWidget();
 	if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
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 098e95d..a871b72 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
@@ -52,7 +52,7 @@
  * 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 parent a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  *
  * @exception IllegalArgumentException <ul>
@@ -88,7 +88,7 @@
  * 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 parent a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  * @param index the index to store the receiver in its parent
  *
@@ -126,7 +126,7 @@
  * Style bits are also inherited from superclasses.
  * </p>
  *
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  *
  * @exception IllegalArgumentException <ul>
@@ -162,7 +162,7 @@
  * Style bits are also inherited from superclasses.
  * </p>
  *
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
  * @param style the style of control to construct
  * @param index the index to store the receiver in its parent
  *
@@ -680,6 +680,23 @@
 	return OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle);
 }
 
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @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>
+ * 
+ * @since 3.1
+ */
 public TreeItem getItem (int index) {
 	checkWidget();
 	int length = OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle);
@@ -694,8 +711,8 @@
 }
 
 /**
- * Returns an array of <code>TreeItem</code>s which are the
- * direct item children of the receiver.
+ * Returns a (possibly empty) array of <code>TreeItem</code>s which
+ * are the direct item children of the receiver.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -797,6 +814,26 @@
 	return new String (Converter.mbcsToWcs (null, buffer));
 }
 
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the 
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the tool item 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.1
+ */
 public int indexOf (TreeItem item) {
 	checkWidget();
 	if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -839,6 +876,16 @@
 	cellFont = null;
 }
 
+/**
+ * Removes all of the items from the receiver.
+ * <p>
+ * @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.1
+ */
 public void removeAll () {
 	checkWidget ();
 	int length = OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
index 8a43d58..b46bdb8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
@@ -157,6 +157,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -427,7 +428,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(Object)
  */
 public Object getData () {
 	checkWidget();
@@ -455,7 +456,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(String, Object)
  */
 public Object getData (String key) {
 	checkWidget();
@@ -482,7 +483,6 @@
  *
  * @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 Display getDisplay () {
@@ -1148,6 +1148,8 @@
  *    <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
+ * 
+ * @see #getData()
  */
 public void setData (Object data) {
 	checkWidget();
@@ -1180,7 +1182,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #getData
+ * @see #getData(String)
  */
 public void setData (String key, Object value) {
 	checkWidget();
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 28b3692..f2257bb 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
@@ -197,7 +197,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 45e20e6..d09c033 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
@@ -394,7 +394,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 54377b2..01c43ca 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
@@ -487,7 +487,7 @@
  * specified in class <code>SWT</code>. Any value other
  * than one of the SWT color constants which is passed
  * in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
  * not the application.
  *
  * @param id the color constant
@@ -526,7 +526,7 @@
  * Returns a reasonable font for applications to use.
  * On some platforms, this will match the "default font"
  * or "system font" if such can be found.  This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
  * system, not the application.
  * <p>
  * Typically, applications which want the default look
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
index 2a74951..cda4864 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
@@ -381,7 +381,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 3bc432b..e74f01f 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
@@ -445,7 +445,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -552,7 +552,8 @@
 /**
  * Sets the style of the receiver to the argument which must
  * be a bitwise OR of one or more of the <code>SWT</code> 
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC.  All other style bits are
+ * ignored.
  *
  * @param style the new style for this <code>FontData</code>
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java
index 6216b6e..16fab79 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java
@@ -99,7 +99,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 3fe2e1f..4845ab8 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
@@ -156,6 +156,24 @@
 public void copyArea(int x, int y, int width, int height, int destX, int destY) {
 	copyArea(x, y, width, height, destX, destY, true);
 }
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1 
+ */
 public void copyArea(int x, int y, int width, int height, int destX, int destY, boolean paint) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (width <= 0 || height <= 0) return;
@@ -331,7 +349,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void drawFocus (int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -813,8 +831,22 @@
 	}
 	OS.XDrawArc(data.display, data.drawable, handle, x, y, width, height, 0, 23040);
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void drawPath(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1436,7 +1468,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1586,8 +1618,22 @@
 	OS.XFillArc (display, data.drawable, handle, x, y, width, height, 0, 23040);
 	OS.XSetForeground (display, handle, values.foreground);
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void fillPath (Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1673,7 +1719,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle (int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1721,7 +1767,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle (Rectangle rect) {
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -1982,12 +2028,44 @@
 	OS.XmFontListFreeFontContext(context);
 	return 0;
 }
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem.  Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, <code>false</code> is always returned.  Some operating system have
+ * only one graphics subsystem.  If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned.  If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned.  If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAdvanced
+ * @since 3.1
+ */
 public boolean getAdvanced() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.cairo != 0;
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getAlpha() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1995,7 +2073,20 @@
 	return (int)(Cairo.cairo_current_alpha(data.cairo) * 255);
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getTextAntialias
+ * 
+ * @since 3.1
  */
 public int getAntialias() {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2022,8 +2113,19 @@
 	return Color.motif_new(data.device, xColor);
 	
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public Pattern getBackgroundPattern() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2272,6 +2374,18 @@
 String getCodePage () {
 	return data.font.codePage;
 }
+/** 
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public int getFillRule() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	XGCValues values = new XGCValues();
@@ -2548,15 +2662,36 @@
 	return Color.motif_new(data.device, xColor);
 	
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public Pattern getForegroundPattern() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return data.foregroundPattern;
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getInterpolation() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2588,7 +2723,8 @@
 	return cap;
 }
 /** 
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
  *
  * @return the lin dash style used for drawing lines
  *
@@ -2688,14 +2824,42 @@
 	return data.style;
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAntialias
+ * 
+ * @since 3.1
  */
 public int getTextAntialias() {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
     return data.textAntialias;
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void getTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2730,7 +2894,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -2848,6 +3012,48 @@
 	Cairo.cairo_matrix_get_affine(matrix, a, b, c, d, tx, ty);
 	return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0;
 }
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is 
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested.  When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations.  Because the two subsystems are
+ * different, their output may differ.  Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, this operation does nothing.  Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing.  However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ * 
+ * @since 3.1
+ */
 public void setAdvanced(boolean advanced) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (advanced && data.cairo != 0) return;
@@ -2869,7 +3075,15 @@
 	}
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setAlpha(int alpha) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2878,7 +3092,24 @@
 	Cairo.cairo_set_alpha(data.cairo, (alpha & 0xff) / 255f);
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setTextAntialias
+ * 
+ * @since 3.1
  */
 public void setAntialias(int antialias) {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2957,8 +3188,21 @@
 	OS.XSetBackground(data.display, handle, color.handle.pixel);
 	data.backgroundPattern = null;
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public void setBackgroundPattern(Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3060,7 +3304,22 @@
 	OS.XDestroyRegion(clipRgn);
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void setClipping(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3077,9 +3336,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
  *
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -3096,9 +3357,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the region specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
  *
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
  * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -3112,6 +3375,22 @@
 	if (region != null && region.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
 	setClipping(region != null ? region.handle : 0);
 }
+/** 
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ *                                 or <code>SWT.FILL_WINDING</code></li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public void setFillRule(int rule) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	int mode = OS.EvenOddRule, cairo_mode = Cairo.CAIRO_FILL_RULE_EVEN_ODD;
@@ -3183,8 +3462,21 @@
 	}
 	data.foregroundPattern = null;
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
  */
 public void setForegroundPattern(Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3205,8 +3497,22 @@
 	}
 	data.foregroundPattern = pattern;
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>, 
+ *                                 <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setInterpolation(int interpolation) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3269,7 +3575,10 @@
 	}
 }
 /** 
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
  *
  * @param dashes the dash style to be used for drawing lines
  * 
@@ -3433,6 +3742,12 @@
  * for all of the figure drawing operations (that is,
  * <code>drawLine</code>, <code>drawRectangle</code>, 
  * <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
  *
  * @param lineWidth the width of a line
  *
@@ -3498,7 +3813,24 @@
 	data.drawFlags = flags;
 }
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAntialias
+ * 
+ * @since 3.1
  */
 public void setTextAntialias(int antialias) {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3512,8 +3844,23 @@
     }
     data.textAntialias = antialias;
 }
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void setTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3575,12 +3922,19 @@
  * and the destination, and if the argument is <code>false</code>,
  * puts the receiver in a drawing mode where the destination color
  * is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
  *
  * @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @deprecated this functionality is not supported on some platforms
  */
 public void setXORMode(boolean xor) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 75d8323..6ea0bbd 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
@@ -54,7 +54,7 @@
  * loading process should use the support provided in class
  * <code>ImageLoader</code>.
  * </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code> 
+ * Application code must explicitly invoke the <code>Image.dispose()</code> 
  * method to release the operating system resources managed by each instance
  * when those instances are no longer required.
  * </p>
@@ -590,7 +590,20 @@
  * This constructor may be used to load a resource as follows:
  * </p>
  * <pre>
- *     new Image(device, clazz.getResourceAsStream("file.gif"));
+ *     static Image loadImage (Display display, Class clazz, String string) {
+ *          InputStream stream = clazz.getResourceAsStream (string);
+ *          if (stream == null) return null;
+ *          Image image = null;
+ *          try {
+ *               image = new Image (display, stream);
+ *          } catch (SWTException ex) {
+ *          } finally {
+ *               try {
+ *                    stream.close ();
+ *               } catch (IOException ex) {}
+ *          }
+ *          return image;
+ *     }
  * </pre>
  *
  * @param device the device on which to create the image
@@ -981,7 +994,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 adfc1b1..7e5bbb7 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
@@ -134,7 +134,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
@@ -260,7 +259,7 @@
 }
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -361,7 +360,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects (int x, int y, int width, int height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -382,7 +381,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects (Rectangle rect) {
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -476,7 +475,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
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 2125875..7250019 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
@@ -632,9 +632,9 @@
 }
 /**
  * Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
  *
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
index 510e345..7214d58 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
@@ -61,7 +61,6 @@
  * </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
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 03b09c6..80a4c2d 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
@@ -559,8 +559,8 @@
 	return getFontHeight (fontList) + spacing + (2 * highlight);
 }
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list. 
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -627,11 +627,16 @@
 	return style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT);
 }
 /**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
  *
  * @return a point representing the selection start and end
  *
@@ -680,7 +685,8 @@
 }
 /**
  * Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
  *
  * @return the receiver's text
  *
@@ -757,6 +763,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -1228,8 +1236,8 @@
 /**
  * Sets the text of the item in the receiver's list at the given
  * zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
  *
  * @param index the index for the item
  * @param string the new text for the item
@@ -1440,7 +1448,11 @@
 /**
  * Sets the maximum number of characters that the receiver's
  * text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
  * @param limit new text limit
  *
  * @exception IllegalArgumentException <ul>
@@ -1450,6 +1462,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget();
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 eaaf7b2..9fbc798 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, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
@@ -349,7 +349,7 @@
 	return true;
 }
 /**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
  * Children are returned in the order that they are drawn.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -430,7 +430,7 @@
 	return layoutCount > 0 ;
 }
 /**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
  *
  * @return tabList the ordered list of controls representing the tab order
  *
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 f6ea7d7..8bac8c2 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
@@ -344,7 +344,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint) {
@@ -381,7 +381,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -1356,7 +1356,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack () {
 	checkWidget();
@@ -1381,7 +1381,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack (boolean changed) {
 	checkWidget();
@@ -2233,7 +2233,8 @@
  * @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2286,7 +2287,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see #update
  */
 public void setRedraw (boolean redraw) {
@@ -2811,7 +2812,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see PaintListener
  * @see SWT#Paint
  */
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 3d480b2..9fce63c 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
@@ -304,9 +304,9 @@
  * 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.
+ * chooses the icon with the "best" attributes.  It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
  * 
  * <p>
  * Note: This method will return an empty array if called before
@@ -470,7 +470,11 @@
  * <em>saved default button</em>). If no default button had
  * previously been set, or the saved default button was
  * disposed, the receiver's default button will be set to
- * null. 
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
  *
  * @param button the new default button
  *
@@ -538,8 +542,9 @@
  * 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.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
  * 
  * @param images the new image array
  *
@@ -572,7 +577,7 @@
  * causes the receiver to switch back to either the minimized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -692,7 +697,7 @@
  * causes the receiver to switch back to either the maximized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -718,7 +723,7 @@
 /**
  * Sets the receiver's text, which is the string that the
  * window manager will typically display as the receiver's
- * <em>title</em>, to the argument, which may not be null. 
+ * <em>title</em>, to the argument, which must not be null. 
  *
  * @param string the new text
  *
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 9f0c212..2bfe7ad 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
@@ -89,6 +89,8 @@
  * the directories it shows.
  *
  * @return the filter path
+ * 
+ * @see #setFilterPath
  */
 public String getFilterPath () {
 	return filterPath;
@@ -287,9 +289,15 @@
 	return directoryPath;
 }
 /**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the filter path
  */
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 33bde71..ae5264d 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
@@ -385,7 +385,7 @@
  * </p>
  *
  * @exception SWTException <ul>
- *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
  *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
  * </ul>
  *
@@ -397,6 +397,11 @@
 public Display () {
 	this (null);
 }
+/**
+ * Constructs a new instance of this class using the parameter.
+ * 
+ * @param data the device data
+ */
 public Display (DeviceData data) {
 	super (checkNull (data));
 }
@@ -546,9 +551,16 @@
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The caller of this method continues 
  * to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed.  Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -804,7 +816,7 @@
  * <p>
  * This method is called after <code>release</code>.
  * </p>
- * @see #dispose
+ * @see Device#dispose
  * @see #release
  */
 protected void destroy () {
@@ -845,7 +857,8 @@
 /**
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed.  Specifying a <code>null</code> runnable
+ * is ignored.
  *
  * @param runnable code to run at dispose time.
  * 
@@ -1184,7 +1197,9 @@
 /**
  * Returns the display which the given thread is the
  * user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display.  Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display. 
  *
  * @param thread the user-interface thread
  * @return the display for the given thread
@@ -1293,7 +1308,7 @@
  * Applications may have associated arbitrary objects with the
  * receiver in this fashion. If the objects stored in the
  * properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1332,7 +1347,7 @@
  * Applications may put arbitrary objects in this field. If
  * the object stored in the display specific data needs to
  * be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1441,9 +1456,8 @@
 	return false;
 }
 /**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
  *
  * @return the maximum icon depth
  *
@@ -1451,6 +1465,8 @@
  *    <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 Device#getDepth
  */
 public int getIconDepth () {
 	return getDepth ();
@@ -1600,8 +1616,8 @@
 	return monitor;		
 }
 /**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
  *
  * @return the receiver's shells
  *
@@ -2767,7 +2783,7 @@
  * </p>
  * This method is called before <code>destroy</code>.
  * 
- * @see #dispose
+ * @see Device#dispose
  * @see #destroy
  */
 protected void release () {
@@ -3154,9 +3170,10 @@
 /**
  * On platforms which support it, sets the application name
  * to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup.  Specifying
+ * <code>null</code> for the name clears it.
  *
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
  */
 public static void setAppName (String name) {
 	APP_NAME = name;
@@ -3435,9 +3452,16 @@
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes.  Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ * 
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -3465,6 +3489,12 @@
  * be invoked by the user-interface thread after the specified
  * number of milliseconds have elapsed. If milliseconds is less
  * than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
  * @param milliseconds the delay before running the runnable
  * @param runnable code to run on the user-interface thread
@@ -3562,7 +3592,7 @@
 	OS.XtFree (event);
 }
 /**
- * If the receiver's user-interface thread was <code>sleep</code>'ing, 
+ * If the receiver's user-interface thread was <code>sleep</code>ing, 
  * causes it to be awakened and start running again. Note that this
  * method may be called from any thread.
  * 
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 db44185..c06d1ff 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
@@ -25,6 +25,8 @@
  * <dd>(none)</dd>
  * </dl>
  * <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
@@ -92,7 +94,8 @@
 }
 /**
  * Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
  * 
  * @return the relative path of the file
  */
@@ -101,8 +104,8 @@
 }
 
 /**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
  * 
  * @return the relative paths of the files
  */
@@ -121,19 +124,19 @@
 }
 
 /**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
  *
- * @return the file name filter
+ * @return the list of filter names
  */
 public String [] getFilterNames () {
 	return filterNames;
 }
 
 /**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set.  File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
  *
  * @return the directory path string
  * 
@@ -491,6 +494,11 @@
  * Set the file extensions which the dialog will
  * use to filter the files it shows to the argument,
  * which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
  *
  * @param extensions the file extension filter
  */
@@ -499,11 +507,11 @@
 }
 
 /**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
  *
- * @param names the file name filter
+ * @param names the list of filter names
  */
 public void setFilterNames (String [] names) {
 	filterNames = names;
@@ -513,7 +521,14 @@
  * Sets the directory path that the dialog will use
  * to the argument, which may be null. File names in this
  * path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the directory path
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
index 44bd6d0..72f367b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
@@ -22,6 +22,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection</dd>
  * </dl>
@@ -425,7 +426,7 @@
  * is delimited by an anchor tag, &lt;A&gt; and &lt;/A&gt;.  Within an
  * anchor, a single HREF attribute is supported.  When a hyperlink is
  * selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
  * In the rare case of identical hyperlinks within the same string, the
  * HREF tag can be used to distinguish between them.  The string may
  * include the mnemonic character and line delimiters.
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 312ec35..db53272 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
@@ -20,7 +20,7 @@
 
 /** 
  * Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
  * when a string selected.  A list may be single or multi select.
  * <p>
  * <dl>
@@ -465,7 +465,7 @@
 }
 /**
  * Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
  *
  * @return the height of one item
  *
@@ -487,8 +487,8 @@
 	return getFontHeight (font.handle) + spacing + highlight + 1;
 }
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -534,8 +534,8 @@
 }
 /**
  * Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver.  The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -598,7 +598,7 @@
  * Returns the zero-relative index of the item which is currently
  * selected in the receiver, or -1 if no item is selected.
  *
- * @return the index of the selected item
+ * @return the index of the selected item or -1
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -620,7 +620,8 @@
 }
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver.  The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1304,7 +1305,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 selected.
+ * The current selection is first cleared, then the new item is 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/motif/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
index a9be6ee..31c4005 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
@@ -366,7 +366,7 @@
 }
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -444,8 +444,8 @@
 	return count;	
 }
 /**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -627,7 +627,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -761,7 +761,7 @@
 }
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -778,11 +778,15 @@
 	OS.XtSetValues (handle, argList, argList.length / 2);
 }
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param x the new x coordinate for the receiver
@@ -801,11 +805,15 @@
 	hasLocation = true;
 }
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param location the new location for the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
index a2ba19f..54717f3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
@@ -218,7 +218,7 @@
 }
 /**
  * Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
  * it one of the messages defined in the <code>SelectionListener</code>
  * interface.
  * <p>
@@ -318,11 +318,13 @@
 	super.destroyWidget ();
 }
 /**
- * Return the widget accelerator.  An accelerator is the bit-wise
+ * Returns the widget accelerator.  An accelerator is the bit-wise
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
- * @return the accelerator
+ * @return the accelerator or 0
  *
  * </ul>
  * @exception SWTException <ul>
@@ -343,7 +345,7 @@
 }
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -447,7 +449,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -616,6 +618,8 @@
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
  * @param accelerator an integer that is the bit-wise OR of masks and a key
  *
@@ -639,7 +643,7 @@
 }
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
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 e1320b4..b22dfaf 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
@@ -109,9 +109,9 @@
 }
 
 /**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
  *
  * @return the message
  */
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 ca908c9..5bd84a7 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
@@ -173,7 +173,7 @@
 	return argList [1];
 }
 /**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
  *
  * @return the selection
  *
@@ -270,7 +270,7 @@
 	setThumb(selection - value);
 }
 /**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
  * position to the argument which must be greater than or equal
  * to zero.
  *
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 a84776d..b1b55cf 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
@@ -203,7 +203,7 @@
 	return argList [1];
 }
 /**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
  *
  * @return the selection
  *
@@ -347,9 +347,8 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
  *
  * @param value the new selection (must be zero or greater)
  *
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 ab68d56..bc4788a 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
@@ -21,7 +21,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given scroll bar will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the scroll bar represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -96,6 +96,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -232,7 +233,7 @@
 	return argList [1];
 }
 /**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
  *
  * @return the receiver's parent
  *
@@ -246,7 +247,7 @@
 	return parent;
 }
 /**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
  *
  * @return the selection
  *
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 d6a2b20..703710d 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
@@ -67,7 +67,7 @@
  * it would be upgraded to <code>APPLICATION_MODAL</code>.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
  * <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -261,7 +261,7 @@
  * @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>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -294,6 +294,9 @@
  * @param parent a shell which will be the parent of the new instance
  * @param style the style of control to construct
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</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>
@@ -308,6 +311,8 @@
  * @see SWT#NO_TRIM
  * @see SWT#SHELL_TRIM
  * @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
  * @see SWT#MODELESS
  * @see SWT#PRIMARY_MODAL
  * @see SWT#APPLICATION_MODAL
@@ -1405,7 +1410,7 @@
 	}
 }
 /**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
@@ -1428,7 +1433,7 @@
 	OS.XtSetValues (shellHandle, argList, argList.length / 2);
 }
 /**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
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 7da69fa..fb890ad 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
@@ -21,7 +21,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given slider will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the slider represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -104,7 +104,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -238,7 +238,7 @@
 	return argList [1];
 }
 /**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
  *
  * @return the selection
  *
@@ -416,7 +416,7 @@
 	OS.XtSetValues (handle, argList, argList.length / 2);
 }
 /**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
  * value, to the argument which must be greater than or equal
  * to zero.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
index 99b0a48..e7cc1b2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
@@ -24,7 +24,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection, Modify</dd>
  * </dl>
@@ -61,6 +61,7 @@
  * </ul>
  *
  * @see SWT#READ_ONLY
+ * @see SWT#WRAP
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -310,6 +311,16 @@
 	OS.XtGetValues (handle, argList, argList.length / 2);
 	return argList [1];
 }
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public int getDigits () {
 	checkWidget ();
 	int [] argList = {OS.XmNdecimalPoints, 0};
@@ -552,6 +563,25 @@
 	}
 	return super.setBounds (x, y, width, height, move, resize);
 }
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with 
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs. 
+ * 
+ * @param value the new digits (must be greater than or equal to zero)
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</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 setDigits (int value) {
 	checkWidget ();
 	if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT);
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 31cf120..cb13de0 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
@@ -43,6 +43,10 @@
 	/**
 	* The maximum number of characters that can be entered
 	* into a text widget.
+	* <p>
+	* Note that this value is platform dependent, based upon
+	* the native widget implementation.
+	* </p>
 	*/
 	public static final int LIMIT;
 	/**
@@ -421,7 +425,7 @@
 	return display.textForeground;
 }
 /**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
  * <p>
  * The line number of the caret is returned.
  * </p>
@@ -438,7 +442,8 @@
 	return getLineNumber (OS.XmTextGetInsertionPosition (handle));
 }
 /**
- * Gets the location the caret.
+ * Returns a point describing the receiver's location relative
+ * to its parent (or its display if its parent is null).
  * <p>
  * The location of the caret is returned.
  * </p>
@@ -459,9 +464,9 @@
 	return new Point (x [0], y [0] - getFontAscent (font.handle));
 }
 /**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
  * <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
  * </p>
  *
  * @return the position of the caret
@@ -476,7 +481,7 @@
 	return OS.XmTextGetInsertionPosition (handle);
 }
 /**
- * Gets the number of characters.
+ * Returns the number of characters.
  *
  * @return number of characters in the widget
  *
@@ -490,7 +495,7 @@
 	return OS.XmTextGetLastPosition (handle);
 }
 /**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
  * <p>
  * The double click flag enables or disables the
  * default action of the text widget when the user
@@ -511,7 +516,7 @@
 	return argList [1] != 1;
 }
 /**
- * Gets the echo character.
+ * Returns the echo character.
  * <p>
  * The echo character is the character that is
  * displayed when the user enters text or the
@@ -524,13 +529,15 @@
  *    <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 #setEchoChar
  */
 public char getEchoChar () {
 	checkWidget();
 	return echoCharacter;
 }
 /**
- * Gets the editable state.
+ * Returns the editable state.
  *
  * @return whether or not the reciever is editable
  * 
@@ -553,7 +560,7 @@
 	return argList [1] != 0;
 }
 /**
- * Gets the number of lines.
+ * Returns the number of lines.
  *
  * @return the number of lines in the widget
  *
@@ -569,7 +576,7 @@
 	return getLineNumber (lastChar) + 1;
 }
 /**
- * Gets the line delimiter.
+ * Returns the line delimiter.
  *
  * @return a string that is the line delimiter
  *
@@ -577,13 +584,15 @@
  *    <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 #DELIMITER
  */
 public String getLineDelimiter () {
 	checkWidget();
 	return "\n";
 }
 /**
- * Gets the height of a line.
+ * Returns the height of a line.
  *
  * @return the height of a row of text
  *
@@ -651,7 +660,8 @@
 	return buffer [0];
 }
 /**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  *
  * @return the orientation style
  * 
@@ -667,14 +677,17 @@
 	return style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT);
 }
 /**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
  * <p>
- * Indexing is zero based.  The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
  * </p>
- * 
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -691,7 +704,7 @@
 	return new Point (start [0], end [0]);
 }
 /**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
  *
  * @return the number of selected characters.
  *
@@ -707,7 +720,7 @@
 	return end [0] - start [0];
 }
 /**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
  *
  * @return the selected text
  * 
@@ -731,7 +744,7 @@
 	return new String (Converter.mbcsToWcs (getCodePage (), buffer));
 }
 /**
- * Gets the number of tabs.
+ * Returns the number of tabs.
  * <p>
  * Tab stop spacing is specified in terms of the
  * space (' ') character.  The width of a single
@@ -751,9 +764,10 @@
 	return 8;
 }
 /**
- * Gets the widget text.
+ * Returns the widget text.
  * <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
  * </p>
  *
  * @return the widget text
@@ -775,7 +789,7 @@
 	return new String (Converter.mbcsToWcs (getCodePage (), buffer));
 }
 /**
- * Gets a range of text.  Returns an empty string if the
+ * Returns 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
@@ -826,6 +840,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -857,7 +873,7 @@
 	return argList2 [1];
 }
 /**
- * Gets the top pixel.
+ * Returns the top pixel.
  * <p>
  * The top pixel is the pixel position of the line
  * that is currently at the top of the widget.  On
@@ -902,6 +918,9 @@
  *
  * @param string the string
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1088,6 +1107,9 @@
  * The double click flag enables or disables the
  * default action of the text widget when the user
  * double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
  * </p>
  * 
  * @param doubleClick the new double click flag
@@ -1111,8 +1133,9 @@
  * the echo character to '\0' clears the echo
  * character and redraws the original text.
  * If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
  * </p>
  *
  * @param echo the new echo character
@@ -1164,6 +1187,9 @@
  * Sets the orientation of the receiver, which must be one
  * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
  *
  * @param orientation new orientation style
  * 
@@ -1226,7 +1252,8 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1279,7 +1306,10 @@
 	display.setWarnings (warnings);
 }
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1368,6 +1398,8 @@
  * creating a read-only text widget.
  * </p><p>
  * To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
  * </p>
  *
  * @param limit new text limit
@@ -1379,6 +1411,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
index b11318c..f510c01 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
@@ -121,6 +121,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -382,7 +383,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(Object)
  */
 public Object getData () {
 	checkWidget();
@@ -411,7 +412,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(String, Object)
  */
 public Object getData (String key) {
 	checkWidget();
@@ -438,7 +439,6 @@
  *
  * @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 Display getDisplay () {
@@ -889,6 +889,8 @@
  *    <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
+ * 
+ * @see #getData()
  */
 public void setData (Object data) {
 	checkWidget();
@@ -921,7 +923,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #getData
+ * @see #getData(String)
  */
 public void setData (String key, Object value) {
 	checkWidget();
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 3968469..6305dbc 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
@@ -194,7 +194,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 9238ab3..28788f8 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
@@ -412,7 +412,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 2708825..bdceaf2 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
@@ -390,7 +390,7 @@
  * specified in class <code>SWT</code>. Any value other
  * than one of the SWT color constants which is passed
  * in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
  * not the application.
  *
  * @param id the color constant
@@ -430,7 +430,7 @@
  * Returns a reasonable font for applications to use.
  * On some platforms, this will match the "default font"
  * or "system font" if such can be found.  This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
  * system, not the application.
  * <p>
  * Typically, applications which want the default look
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
index 1e80d67..c919730 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
@@ -193,7 +193,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 d08ddc9..bf8927b 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
@@ -312,7 +312,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -414,7 +414,8 @@
 /**
  * Sets the style of the receiver to the argument which must
  * be a bitwise OR of one or more of the <code>SWT</code> 
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC.  All other style bits are
+ * ignored.
  *
  * @param style the new style for this <code>FontData</code>
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java
index 8012b78..4388c80 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java
@@ -140,7 +140,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 5e07270..94660b2 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
@@ -256,6 +256,24 @@
 public void copyArea(int x, int y, int width, int height, int destX, int destY) {
 	copyArea(x, y, width, height, destX, destY, true);
 }
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1 
+ */
 public void copyArea(int x, int y, int width, int height, int destX, int destY, boolean paint) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (width == 0 || height == 0) return;
@@ -516,7 +534,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void drawFocus (int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -996,8 +1014,22 @@
 	}
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void drawPath(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1598,7 +1630,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1677,8 +1709,22 @@
 	}
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void fillPath (Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1738,7 +1784,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle (int x, int y, int width, int height) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1767,7 +1813,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
  */
 public void fillRectangle (Rectangle rect) {
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -1841,13 +1887,45 @@
 	return getCharWidth(ch);
 }
 
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem.  Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, <code>false</code> is always returned.  Some operating system have
+ * only one graphics subsystem.  If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned.  If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned.  If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAdvanced
+ * @since 3.1
+ */
 public boolean getAdvanced() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return false;
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getAlpha() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1855,7 +1933,20 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getTextAntialias
+ * 
+ * @since 3.1
  */
 public int getAntialias() {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1876,6 +1967,20 @@
 	return Color.photon_new(data.device, data.background);
 }
 
+/** 
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
+ */
 public Pattern getBackgroundPattern() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return null;
@@ -2007,6 +2112,18 @@
 	}
 }
 
+/** 
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public int getFillRule() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	//TODO - implement fill rule
@@ -2060,13 +2177,37 @@
 	return Color.photon_new(data.device, data.foreground);
 }
 
+/** 
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
+ */
 public Pattern getForegroundPattern() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	return null;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public int getInterpolation() {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2092,7 +2233,8 @@
 }
 
 /** 
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
  *
  * @return the lin dash style used for drawing lines
  *
@@ -2189,15 +2331,43 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #getAntialias
+ * 
+ * @since 3.1
  */
 public int getTextAntialias() {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
     return SWT.DEFAULT;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void getTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2226,7 +2396,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -2309,6 +2479,48 @@
 	return handle == 0;
 }
 
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is 
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested.  When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations.  Because the two subsystems are
+ * different, their output may differ.  Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system.  In this
+ * case, this operation does nothing.  Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing.  However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ * 
+ * @since 3.1
+ */
 public void setAdvanced(boolean advanced) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (!advanced) {
@@ -2324,14 +2536,39 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setAlpha(int alpha) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setTextAntialias
+ * 
+ * @since 3.1
  */
 public void setAntialias(int antialias) {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2368,6 +2605,22 @@
 	dirtyBits |= DIRTY_BACKGROUND;
 }
 
+/** 
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
+ */
 public void setBackgroundPattern (Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (pattern == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -2415,7 +2668,22 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Path
+ * 
+ * @since 3.1
  */
 public void setClipping(Path path) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2425,9 +2693,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
  *
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -2449,9 +2719,11 @@
 /**
  * Sets the area of the receiver which can be changed
  * by drawing operations to the region specified
- * by the argument.
+ * by the argument.  Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
  *
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
  * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -2483,6 +2755,22 @@
 	dirtyBits |= DIRTY_CLIPPING;
 }
 
+/** 
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ *                                 or <code>SWT.FILL_WINDING</code></li>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public void setFillRule(int rule) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	switch (rule) {
@@ -2539,8 +2827,22 @@
 	dirtyBits |= DIRTY_FOREGROUND;
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, 
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>, 
+ *                                 <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul> 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
  */
 public void setInterpolation(int interpolation) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2555,6 +2857,22 @@
 	}
 }
 
+/** 
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Pattern
+ * 
+ * @since 3.1
+ */
 public void setForegroundPattern (Pattern pattern) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
 	if (pattern == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -2592,7 +2910,10 @@
 }
 
 /** 
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
  *
  * @param dashes the dash style to be used for drawing lines
  * 
@@ -2691,6 +3012,12 @@
  * for all of the figure drawing operations (that is,
  * <code>drawLine</code>, <code>drawRectangle</code>, 
  * <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
  *
  * @param lineWidth the width of a line
  *
@@ -2870,7 +3197,24 @@
 }
 
 /**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter, 
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ *                                 <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setAntialias
+ * 
+ * @since 3.1
  */
 public void setTextAntialias(int antialias) {
     if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2883,8 +3227,23 @@
     }
 }
 
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/** 
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see Transform
+ * 
+ * @since 3.1
  */
 public void setTransform(Transform transform) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2898,12 +3257,19 @@
  * and the destination, and if the argument is <code>false</code>,
  * puts the receiver in a drawing mode where the destination color
  * is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
  *
  * @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @deprecated this functionality is not supported on some platforms
  */
 public void setXORMode(boolean xor) {
 	if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 67fbbab..fcb05c3 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
@@ -53,7 +53,7 @@
  * loading process should use the support provided in class
  * <code>ImageLoader</code>.
  * </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code> 
+ * Application code must explicitly invoke the <code>Image.dispose()</code> 
  * method to release the operating system resources managed by each instance
  * when those instances are no longer required.
  * </p>
@@ -414,7 +414,20 @@
  * This constructor may be used to load a resource as follows:
  * </p>
  * <pre>
- *     new Image(device, clazz.getResourceAsStream("file.gif"));
+ *     static Image loadImage (Display display, Class clazz, String string) {
+ *          InputStream stream = clazz.getResourceAsStream (string);
+ *          if (stream == null) return null;
+ *          Image image = null;
+ *          try {
+ *               image = new Image (display, stream);
+ *          } catch (SWTException ex) {
+ *          } finally {
+ *               try {
+ *                    stream.close ();
+ *               } catch (IOException ex) {}
+ *          }
+ *          return image;
+ *     }
  * </pre>
  *
  * @param device the device on which to create the image
@@ -678,7 +691,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
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 6404ed4..c44ba76 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
@@ -134,7 +134,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
@@ -298,7 +297,7 @@
 
 /**
  * Returns an integer hash code for the receiver. Any two 
- * objects which return <code>true</code> when passed to 
+ * objects that return <code>true</code> when passed to 
  * <code>equals</code> must return the same value for this
  * method.
  *
@@ -412,7 +411,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects (int x, int y, int width, int height) {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -446,7 +445,7 @@
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
  */
 public boolean intersects (Rectangle rect) {
 	if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -540,7 +539,6 @@
  * @param height the height coordinate of the rectangle
  *
  * @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>
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 50ec642..faa9f4d 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
@@ -507,9 +507,9 @@
 
 /**
  * Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
  *
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
index f890c3a..17030b0 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
@@ -61,7 +61,6 @@
  * </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
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 a41cfba..71b0174 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
@@ -587,8 +587,8 @@
 }
 
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list. 
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -644,11 +644,16 @@
 }
 
 /**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
  *
  * @return a point representing the selection start and end
  *
@@ -705,7 +710,8 @@
 
 /**
  * Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
  *
  * @return the receiver's text
  *
@@ -761,6 +767,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -1119,8 +1127,8 @@
 /**
  * Sets the text of the item in the receiver's list at the given
  * zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
  *
  * @param index the index for the item
  * @param string the new text for the item
@@ -1268,7 +1276,11 @@
 /**
  * Sets the maximum number of characters that the receiver's
  * text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
  * @param limit new text limit
  *
  * @exception IllegalArgumentException <ul>
@@ -1278,6 +1290,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget();
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 06d06c4..c333579 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></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
@@ -437,7 +437,7 @@
 }
 
 /**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
  * Children are returned in the order that they are drawn.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -544,7 +544,7 @@
 }
 
 /**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
  *
  * @return tabList the ordered list of controls representing the tab order
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
index 974b0b2..54b5d1a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
@@ -380,7 +380,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint) {
@@ -418,7 +418,7 @@
  * @see #getBorderWidth
  * @see #getBounds
  * @see #getSize
- * @see #pack
+ * @see #pack(boolean)
  * @see "computeTrim, getClientArea for controls that implement them"
  */
 public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -1226,7 +1226,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack () {
 	checkWidget();
@@ -1252,7 +1252,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
  */
 public void pack (boolean changed) {
 	checkWidget();
@@ -2314,7 +2314,8 @@
  * @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
+ *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2384,7 +2385,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see #update
  */
 public void setRedraw (boolean redraw) {
@@ -2775,7 +2776,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
  * @see PaintListener
  * @see SWT#Paint
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java
index d651c4c..306d5e3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java
@@ -237,9 +237,9 @@
  * 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.
+ * chooses the icon with the "best" attributes.  It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
  * 
  * <p>
  * Note: This method will return an empty array if called before
@@ -415,7 +415,11 @@
  * <em>saved default button</em>). If no default button had
  * previously been set, or the saved default button was
  * disposed, the receiver's default button will be set to
- * null. 
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
  *
  * @param button the new default button
  *
@@ -483,8 +487,9 @@
  * 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.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
  * 
  * @param images the new image array
  *
@@ -516,7 +521,7 @@
  * causes the receiver to switch back to either the minimized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -564,7 +569,7 @@
  * causes the receiver to switch back to either the maximized
  * or normal states.
  * <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
  * and <code>setMinimized(true)</code> will vary by platform. Typically,
  * the behavior will match the platform user's expectations, but not
  * always. This should be avoided if possible.
@@ -586,7 +591,7 @@
 /**
  * Sets the receiver's text, which is the string that the
  * window manager will typically display as the receiver's
- * <em>title</em>, to the argument, which may not be null. 
+ * <em>title</em>, to the argument, which must not be null. 
  *
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java
index 6d1ad39..128466a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -83,6 +83,8 @@
  * the directories it shows.
  *
  * @return the filter path
+ * 
+ * @see #setFilterPath
  */
 public String getFilterPath () {
 	return filterPath;
@@ -135,9 +137,15 @@
 }
 
 /**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the filter path
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
index d78b93b..a80711d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
@@ -313,7 +313,7 @@
  * </p>
  *
  * @exception SWTException <ul>
- *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
  *    <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
  * </ul>
  *
@@ -326,6 +326,11 @@
 	this (null);
 }
 
+/**
+ * Constructs a new instance of this class using the parameter.
+ * 
+ * @param data the device data
+ */
 public Display (DeviceData data) {
 	super (data);
 }
@@ -404,9 +409,16 @@
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The caller of this method continues 
  * to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed.  Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -549,7 +561,7 @@
  * <p>
  * This method is called after <code>release</code>.
  * </p>
- * @see #dispose
+ * @see Device#dispose
  * @see #release
  */
 protected void destroy () {
@@ -565,7 +577,8 @@
 /**
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed.  Specifying a <code>null</code> runnable
+ * is ignored.
  *
  * @param runnable code to run at dispose time.
  * 
@@ -611,7 +624,9 @@
 /**
  * Returns the display which the given thread is the
  * user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display.  Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display. 
  *
  * @param thread the user-interface thread
  * @return the display for the given thread
@@ -824,9 +839,10 @@
 /**
  * On platforms which support it, sets the application name
  * to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup.  Specifying
+ * <code>null</code> for the name clears it.
  *
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
  */
 public static void setAppName (String name) {
 	/* Do nothing */
@@ -929,9 +945,8 @@
 }
 
 /**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
  *
  * @return the maximum icon depth
  *
@@ -939,6 +954,8 @@
  *    <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 Device#getDepth
  */
 public int getIconDepth () {
 	return getDepth ();
@@ -1024,8 +1041,8 @@
 }
 
 /**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
  *
  * @return the receiver's shells
  *
@@ -1585,7 +1602,7 @@
  * Applications may have associated arbitrary objects with the
  * receiver in this fashion. If the objects stored in the
  * properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -1622,7 +1639,7 @@
  * Applications may put arbitrary objects in this field. If
  * the object stored in the display specific data needs to
  * be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
  * <code>disposeExec()</code> handler which does so.
  * </p>
  *
@@ -2003,7 +2020,7 @@
  * </p>
  * This method is called before <code>destroy</code>.
  * 
- * @see #dispose
+ * @see Device#dispose
  * @see #destroy
  */
 protected void release () {
@@ -2394,9 +2411,16 @@
  * Causes the <code>run()</code> method of the runnable to
  * be invoked by the user-interface thread at the next 
  * reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes.  Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ * 
+ * @param runnable code to run on the user-interface thread or <code>null</code>
  *
  * @exception SWTException <ul>
  *    <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -2424,6 +2448,12 @@
  * be invoked by the user-interface thread after the specified
  * number of milliseconds have elapsed. If milliseconds is less
  * than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets 
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
  *
  * @param milliseconds the delay before running the runnable
  * @param runnable code to run on the user-interface thread
@@ -2529,7 +2559,7 @@
 }
 
 /**
- * If the receiver's user-interface thread was <code>sleep</code>'ing, 
+ * If the receiver's user-interface thread was <code>sleep</code>ing, 
  * causes it to be awakened and start running again. Note that this
  * method may be called from any thread.
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java
index 964d721..dbff1ba 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java
@@ -25,6 +25,8 @@
  * <dd>(none)</dd>
  * </dl>
  * <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
@@ -83,7 +85,8 @@
 
 /**
  * Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
  * 
  * @return the relative path of the file
  */
@@ -92,8 +95,8 @@
 }
 
 /**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
  * 
  * @return the relative paths of the files
  */
@@ -113,19 +116,19 @@
 }
 
 /**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
  *
- * @return the file name filter
+ * @return the list of filter names
  */
 public String [] getFilterNames () {
 	return filterNames;
 }
 
 /**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set.  File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
  *
  * @return the directory path string
  * 
@@ -230,6 +233,11 @@
  * Set the file extensions which the dialog will
  * use to filter the files it shows to the argument,
  * which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
  *
  * @param extensions the file extension filter
  */
@@ -238,11 +246,11 @@
 }
 
 /**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
  *
- * @param names the file name filter
+ * @param names the list of filter names
  */
 public void setFilterNames (String [] names) {
 	filterNames = names;
@@ -252,7 +260,14 @@
  * Sets the directory path that the dialog will use
  * to the argument, which may be null. File names in this
  * path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the directory path
  * 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
index 4096f86..1b5a08a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
@@ -22,6 +22,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection</dd>
  * </dl>
@@ -583,7 +584,7 @@
  * is delimited by an anchor tag, &lt;A&gt; and &lt;/A&gt;.  Within an
  * anchor, a single HREF attribute is supported.  When a hyperlink is
  * selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
  * In the rare case of identical hyperlinks within the same string, the
  * HREF tag can be used to distinguish between them.  The string may
  * include the mnemonic character and line delimiters.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java
index 75783b3..bbab8d4 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java
@@ -19,7 +19,7 @@
 
 /** 
  * Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
  * when a string selected.  A list may be single or multi select.
  * <p>
  * <dl>
@@ -415,7 +415,7 @@
 
 /**
  * Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
  *
  * @return the height of one item
  *
@@ -445,8 +445,8 @@
 }
 
 /**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -483,8 +483,8 @@
 
 /**
  * Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver.  The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -528,7 +528,7 @@
  * Returns the zero-relative index of the item which is currently
  * selected in the receiver, or -1 if no item is selected.
  *
- * @return the index of the selected item
+ * @return the index of the selected item or -1
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -550,7 +550,8 @@
 
 /**
  * Returns the zero-relative indices of the items which are currently
- * selected in the receiver.  The array is empty if no items are selected.
+ * selected in the receiver.  The order of the indices is unspecified.
+ * The array is empty if no items are selected.
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its selection, so modifying the array will
@@ -1107,7 +1108,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 selected.
+ * The current selection is first cleared, then the new item is 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/photon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java
index bc439c3..efe4970 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java
@@ -259,7 +259,7 @@
 
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -333,8 +333,8 @@
 }
 
 /**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver. 
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
  * to maintain its list of items, so modifying the array will
@@ -528,7 +528,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -687,7 +687,7 @@
 
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -706,11 +706,15 @@
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param x the new x coordinate for the receiver
@@ -729,11 +733,15 @@
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
  * </p>
  *
  * @param location the new location for the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
index dc44683..769f6d5 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
@@ -186,7 +186,7 @@
 
 /**
  * Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
  * it one of the messages defined in the <code>SelectionListener</code>
  * interface.
  * <p>
@@ -261,11 +261,13 @@
 }
 
 /**
- * Return the widget accelerator.  An accelerator is the bit-wise
+ * Returns the widget accelerator.  An accelerator is the bit-wise
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
- * @return the accelerator
+ * @return the accelerator or 0
  *
  * </ul>
  * @exception SWTException <ul>
@@ -280,7 +282,7 @@
 
 /**
  * Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -385,7 +387,7 @@
 /**
  * Returns <code>true</code> if the receiver is enabled and all
  * of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
  * user interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
@@ -576,6 +578,8 @@
  * OR of zero or more modifier masks and a key. Examples:
  * <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
  * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
  *
  * @param accelerator an integer that is the bit-wise OR of masks and a key
  *
@@ -595,7 +599,7 @@
 
 /**
  * Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
  * not selectable from the user interface and draws with an
  * inactive or "grayed" look.
  *
@@ -621,8 +625,9 @@
 /**
  * Sets the image the receiver will display to the argument.
  * <p>
- * Note: This feature is not available on all window systems (for example, Window NT),
- * in which case, calling this method will silently do nothing.
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept (for example, Windows NT).
+ * </p>
  *
  * @param image the image to display
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java
index a08f6e8..a817c89 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java
@@ -91,9 +91,9 @@
 	return style;
 }
 /**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
  *
  * @return the message
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java
index cb24ebd..263add3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java
@@ -156,7 +156,7 @@
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
  *
  * @return the selection
  *
@@ -215,7 +215,7 @@
 }
 
 /**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
  * position to the argument which must be greater than or equal
  * to zero.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java
index 9555970..414b7a3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java
@@ -221,7 +221,7 @@
 }
 
 /**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
  *
  * @return the selection
  *
@@ -347,9 +347,8 @@
 }
 
 /**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
  *
  * @param value the new selection (must be zero or greater)
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
index 606d8e3..36c5cb6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
@@ -21,7 +21,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given scroll bar will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the scroll bar represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -107,6 +107,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -263,7 +264,7 @@
 }
 
 /**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
  *
  * @return the receiver's parent
  *
@@ -278,7 +279,7 @@
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
  *
  * @return the selection
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
index f859478..0839d57 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
@@ -67,7 +67,7 @@
  * it would be upgraded to <code>APPLICATION_MODAL</code>.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
  * <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -260,7 +260,7 @@
  * @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>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -294,6 +294,9 @@
  * @param parent a shell which will be the parent of the new instance
  * @param style the style of control to construct
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</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>
@@ -308,6 +311,8 @@
  * @see SWT#NO_TRIM
  * @see SWT#SHELL_TRIM
  * @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
  * @see SWT#MODELESS
  * @see SWT#PRIMARY_MODAL
  * @see SWT#APPLICATION_MODAL
@@ -1124,7 +1129,7 @@
 }
 
 /**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
@@ -1156,7 +1161,7 @@
 }
 
 /**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
  * If the new minimum size is larger than the current size of the receiver,
  * the receiver is resized to the new minimum size.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
index 4f4755f..0da568e 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
@@ -21,7 +21,7 @@
  * objects that represent a range of positive, numeric values. 
  * <p>
  * At any given moment, a given slider will have a 
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
  * value, which is constrained to be within the range of
  * values the slider represents (that is, between its
  * <em>minimum</em> and <em>maximum</em> values).
@@ -110,7 +110,7 @@
  * interface.
  * <p>
  * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
  * <code>SWT.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
@@ -254,7 +254,7 @@
 }
 
 /**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
  *
  * @return the selection
  *
@@ -467,7 +467,7 @@
 }
 
 /**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
  * value, to the argument which must be greater than or equal
  * to zero.
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
index ecf1aff..89c1c7c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
@@ -22,7 +22,7 @@
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection, Modify</dd>
  * </dl>
@@ -59,6 +59,7 @@
  * </ul>
  *
  * @see SWT#READ_ONLY
+ * @see SWT#WRAP
  * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
@@ -321,6 +322,16 @@
 	return display.TEXT_FOREGROUND;
 }
 
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public int getDigits () {
 	checkWidget ();
 	return 0;
@@ -550,6 +561,25 @@
 	eventTable.unhook (SWT.Verify, listener);	
 }
 
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with 
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs. 
+ * 
+ * @param value the new digits (must be greater than or equal to zero)
+ * 
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</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 setDigits (int value) {
 	checkWidget ();
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
index eae743d..0d399da 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
@@ -43,6 +43,10 @@
 	/**
 	* The maximum number of characters that can be entered
 	* into a text widget.
+	* <p>
+	* Note that this value is platform dependent, based upon
+	* the native widget implementation.
+	* </p>
 	*/
 	public static final int LIMIT;
 	/**
@@ -399,7 +403,7 @@
 }
 
 /**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
  * <p>
  * The line number of the caret is returned.
  * </p>
@@ -418,7 +422,8 @@
 }
 
 /**
- * Gets the location the caret.
+ * Returns a point describing the receiver's location relative
+ * to its parent (or its display if its parent is null).
  * <p>
  * The location of the caret is returned.
  * </p>
@@ -437,9 +442,9 @@
 }
 
 /**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
  * <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
  * </p>
  *
  * @return the position of the caret
@@ -457,7 +462,7 @@
 }
 
 /**
- * Gets the number of characters.
+ * Returns the number of characters.
  *
  * @return number of characters in the widget
  *
@@ -475,7 +480,7 @@
 }
 
 /**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
  * <p>
  * The double click flag enables or disables the
  * default action of the text widget when the user
@@ -496,7 +501,7 @@
 }
 
 /**
- * Gets the echo character.
+ * Returns the echo character.
  * <p>
  * The echo character is the character that is
  * displayed when the user enters text or the
@@ -509,6 +514,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 #setEchoChar
  */
 public char getEchoChar () {
 	checkWidget();
@@ -516,7 +523,7 @@
 }
 
 /**
- * Gets the editable state.
+ * Returns the editable state.
  *
  * @return whether or not the reciever is editable
  * 
@@ -533,7 +540,7 @@
 }
 
 /**
- * Gets the number of lines.
+ * Returns the number of lines.
  *
  * @return the number of lines in the widget
  *
@@ -551,7 +558,7 @@
 }
 
 /**
- * Gets the line delimiter.
+ * Returns the line delimiter.
  *
  * @return a string that is the line delimiter
  *
@@ -559,6 +566,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 #DELIMITER
  */
 public String getLineDelimiter () {
 	checkWidget();
@@ -566,7 +575,7 @@
 }
 
 /**
- * Gets the height of a line.
+ * Returns the height of a line.
  *
  * @return the height of a row of text
  *
@@ -609,7 +618,8 @@
 }
 
 /**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  *
  * @return the orientation style
  * 
@@ -626,14 +636,17 @@
 }
 
 /**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
  * <p>
- * Indexing is zero based.  The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based.  The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
  * </p>
- * 
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -656,7 +669,7 @@
 }
 
 /**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
  *
  * @return the number of selected characters.
  *
@@ -672,7 +685,7 @@
 }
 
 /**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
  *
  * @return the selected text
  * 
@@ -693,7 +706,7 @@
 }
 
 /**
- * Gets the number of tabs.
+ * Returns the number of tabs.
  * <p>
  * Tab stop spacing is specified in terms of the
  * space (' ') character.  The width of a single
@@ -725,7 +738,7 @@
 }
 
 /**
- * Gets a range of text.  Returns an empty string if the
+ * Returns 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
@@ -759,9 +772,10 @@
 }
 
 /**
- * Gets the widget text.
+ * Returns the widget text.
  * <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
  * </p>
  *
  * @return the widget text
@@ -797,6 +811,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 #LIMIT
  */
 public int getTextLimit () {
 	checkWidget();
@@ -828,7 +844,7 @@
 }
 
 /**
- * Gets the top pixel.
+ * Returns the top pixel.
  * <p>
  * The top pixel is the pixel position of the line
  * that is currently at the top of the widget.  On
@@ -868,6 +884,9 @@
  *
  * @param string the string
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1147,8 +1166,9 @@
  * the echo character to '\0' clears the echo
  * character and redraws the original text.
  * If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
  * </p>
  *
  * @param echo the new echo character
@@ -1184,6 +1204,9 @@
  * The double click flag enables or disables the
  * default action of the text widget when the user
  * double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
  * </p>
  * 
  * @param doubleClick the new double click flag
@@ -1225,6 +1248,9 @@
  * Sets the orientation of the receiver, which must be one
  * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
  * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
  *
  * @param orientation new orientation style
  * 
@@ -1279,7 +1305,10 @@
 }
 
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1311,7 +1340,8 @@
 }
 
 /**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
  * <p>
  * Indexing is zero based.  The range of
  * a selection is from 0..N where N is
@@ -1413,6 +1443,8 @@
  * creating a read-only text widget.
  * </p><p>
  * To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
  * </p>
  *
  * @param limit new text limit
@@ -1424,6 +1456,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 #LIMIT
  */
 public void setTextLimit (int limit) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
index 2c14640..ff66efc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
@@ -96,6 +96,7 @@
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -473,7 +474,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(Object)
  */
 public Object getData () {
 	checkWidget();
@@ -502,7 +503,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #setData
+ * @see #setData(String, Object)
  */
 public Object getData (String key) {
 	checkWidget();
@@ -529,7 +530,6 @@
  *
  * @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 Display getDisplay () {
@@ -940,6 +940,8 @@
  *    <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
  * </ul>
+ * 
+ * @see #getData()
  */
 public void setData (Object data) {
 	checkWidget();
@@ -972,7 +974,7 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
- * @see #getData
+ * @see #getData(String)
  */
 public void setData (String key, Object value) {
 	checkWidget();