Update javadoc from win32

26 files changed, 307 insertions, 264 deletions

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 da95d873d2..99145ac815 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
@@ -462,7 +462,7 @@ void releaseWidget () {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
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 0053a6aa57..229cb084ab 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
@@ -45,8 +45,7 @@ import org.eclipse.swt.events.*;
  * <dd>DefaultSelection, Modify, Selection</dd>
  * </dl>
  * <p>
- * Note: Only one of the styles DROP_DOWN and SIMPLE 
- * may be specified.
+ * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified.
  * </p><p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
  * </p>
@@ -122,9 +121,6 @@ public Combo (Composite parent, int style) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li>
- * </ul>
  *
  * @see #add(String,int)
  */
@@ -154,9 +150,6 @@ public void add (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li>
- * </ul>
  *
  * @see #add(String)
  */
@@ -615,9 +608,6 @@ GdkColor getForegroundColor () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public String getItem (int index) {
 	checkWidget();
@@ -636,9 +626,6 @@ public String getItem (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getItemCount () {
 	checkWidget();
@@ -655,9 +642,6 @@ public int getItemCount () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getItemHeight () {
 	checkWidget();
@@ -679,9 +663,6 @@ public int getItemHeight () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public String [] getItems () {
 	checkWidget();
@@ -796,9 +777,6 @@ String getText (int start, int stop) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getTextHeight () {
 	checkWidget();
@@ -827,6 +805,10 @@ public int getTextLimit () {
 /**
  * Gets the number of items that are visible in the drop
  * down portion of the receiver's list.
+ * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
  *
  * @return the number of items that are visible
  *
@@ -1056,9 +1038,6 @@ void releaseHandle () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int index) {
 	checkWidget();
@@ -1099,9 +1078,6 @@ public void remove (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int start, int end) {
 	checkWidget();
@@ -1147,9 +1123,6 @@ public void remove (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (String string) {
 	checkWidget();
@@ -1160,7 +1133,8 @@ public void remove (String string) {
 }
 
 /**
- * Removes all of the items from the receiver's list.
+ * Removes all of the items from the receiver's list and clear the
+ * contents of receiver's text field.
  * <p>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1229,7 +1203,7 @@ public void removeSelectionListener (SelectionListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is verified.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1333,10 +1307,6 @@ void setForegroundColor (GdkColor color) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li>
- *    <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li>
- * </ul>
  */
 public void setItem (int index, String string) {
 	checkWidget();
@@ -1368,9 +1338,6 @@ public void setItem (int index, String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void setItems (String [] items) {
 	checkWidget();
@@ -1540,6 +1507,10 @@ public void setTextLimit (int limit) {
 /**
  * Sets the number of items that are visible in the drop
  * down portion of the receiver's list.
+ * <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
  *
  * @param count the new number of items to be visible
  *
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 e1bf1243b4..f76133fb8c 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
@@ -373,6 +373,7 @@ boolean forceFocus (int /*long*/ focusHandle) {
 
 /**
  * Returns an 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
  * to maintain its list of children, so modifying the array will
@@ -380,6 +381,9 @@ boolean forceFocus (int /*long*/ focusHandle) {
  * </p>
  *
  * @return an array of children
+ * 
+ * @see Control#moveAbove
+ * @see Control#moveBelow
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -995,7 +999,7 @@ public void setLayout (Layout layout) {
  * </ul>
  * 
  * @see #layout(boolean)
- * @see #layout(Control)
+ * @see #layout(Control[])
  *
  * @since 3.1
  */
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 691c136810..23ac1c78d9 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
@@ -753,7 +753,8 @@ public void setSize (int width, int height) {
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @see #moveBelow
+ * @see Control#moveBelow
+ * @see Composite#getChildren
  */
 public void moveAbove (Control control) {
 	checkWidget();
@@ -781,7 +782,8 @@ public void moveAbove (Control control) {
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @see #moveAbove
+ * @see Control#moveAbove
+ * @see Composite#getChildren
  */
 public void moveBelow (Control control) {
 	checkWidget();
@@ -1189,7 +1191,7 @@ public void addTraverseListener (TraverseListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is moved or resized.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1213,7 +1215,7 @@ public void removeControlListener (ControlListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control gains or loses focus.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1237,7 +1239,7 @@ public void removeFocusListener(FocusListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the help events are generated for the control.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1260,7 +1262,7 @@ public void removeHelpListener (HelpListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when keys are pressed and released on the system keyboard.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1284,7 +1286,7 @@ public void removeKeyListener(KeyListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when mouse buttons are pressed and released.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1309,7 +1311,7 @@ public void removeMouseListener (MouseListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the mouse moves.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1333,7 +1335,7 @@ public void removeMouseMoveListener(MouseMoveListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the mouse passes or hovers over controls.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1359,7 +1361,7 @@ public void removeMouseTrackListener(MouseTrackListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the receiver needs to be painted.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1383,7 +1385,7 @@ public void removePaintListener(PaintListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when traversal events occur.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -2197,9 +2199,10 @@ boolean isTabItem () {
 
 /**
  * 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
- * user interface and draws with an inactive or "grayed" look.
+ * ancestors up to and including the receiver's nearest ancestor
+ * shell are enabled.  Otherwise, <code>false</code> is returned.
+ * A disabled control is typically not selectable from the user
+ * interface and draws with an inactive or "grayed" look.
  *
  * @return the receiver's enabled state
  *
@@ -2240,8 +2243,8 @@ public boolean isFocusControl () {
 
 /**
  * Returns <code>true</code> if the receiver is visible and all
- * of the receiver's ancestors are visible and <code>false</code>
- * otherwise.
+ * ancestors up to and including the receiver's nearest ancestor
+ * shell are visible. Otherwise, <code>false</code> is returned.
  *
  * @return the receiver's visibility state
  *
@@ -2852,7 +2855,8 @@ boolean setRadioSelection (boolean value) {
  * can occur in the receiver until the flag is set to true.
  * Graphics operations that occurred while the flag was
  * <code>false</code> are lost. When the flag is set to <code>true</code>,
- * the entire widget is marked as needing to be redrawn.
+ * the entire widget is marked as needing to be redrawn.  Nested calls
+ * to this method are stacked.
  * <p>
  * Note: This operation is a hint and may not be supported on some
  * platforms or for some widgets.
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 dc00d55f9c..25975db0bf 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
@@ -566,7 +566,7 @@ public void setImage (Image image) {
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the array of images is null</li>
- *    <li>ERROR_INVALID_ARGUMENT - if one of the images has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if one of the images is null or 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/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
index 5e04c80033..b47655265c 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
@@ -422,9 +422,19 @@ public Display (DeviceData data) {
 /**
  * Adds the listener to the collection of listeners who will
  * be notifed when an event of the given type occurs anywhere
- * in this display. When the event does occur, the listener is
+ * in a widget. When the event does occur, the listener is
  * notified by sending it the <code>handleEvent()</code> message.
- *
+ * <p>
+ * Setting the type of an event to <code>SWT.None</code> from
+ * within the <code>handleEvent()</code> method can be used to
+ * change the event type and stop subsequent Java listeners
+ * from running. Because event filters run before other listeners,
+ * event filters can both block other listeners and set arbitrary
+ * fields within an event. For this reason, event filters are both
+ * powerful and dangerous. They should generally be avoided for
+ * performance, debugging and code maintenance reasons.
+ * </p>
+ * 
  * @param eventType the type of event to listen for
  * @param listener the listener which should be notified when the event occurs
  *
@@ -943,6 +953,10 @@ int /*long*/ eventProc (int /*long*/ event, int /*long*/ data) {
  * the instance of the <code>Widget</code> subclass which
  * represents it in the currently running application, if
  * such exists, or null if no matching widget can be found.
+ * <p>
+ * <b>IMPORTANT:</b> This method should not be called from
+ * application code. The arguments are platform-specific.
+ * </p>
  *
  * @param handle the handle for the widget
  * @return the SWT widget that the handle represents
@@ -957,6 +971,28 @@ public Widget findWidget (int /*long*/ handle) {
 	return getWidget (handle);
 }
 
+/**
+ * Given the operating system handle for a widget,
+ * and widget-specific id, returns the instance of
+ * the <code>Widget</code> subclass which represents
+ * the handle/id pair in the currently running application,
+ * if such exists, or null if no matching widget can be found.
+ * <p>
+ * <b>IMPORTANT:</b> This method should not be called from
+ * application code. The arguments are platform-specific.
+ * </p>
+ *
+ * @param handle the handle for the widget
+ * @param id the id for the subwidget (usually an item)
+ * @return the SWT widget that the handle/id pair represents
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.1
+ */
 public Widget findWidget (int /*long*/ handle, int id) {
 	return null;
 }
@@ -1180,8 +1216,8 @@ public Point [] getCursorSizes () {
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #setData
- * @see #disposeExec
+ * @see #setData(String, Object)
+ * @see #disposeExec(Runnable)
  */
 public Object getData (String key) {
 	checkDevice ();
@@ -1216,8 +1252,8 @@ public Object getData (String key) {
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #setData
- * @see #disposeExec
+ * @see #setData(Object)
+ * @see #disposeExec(Runnable)
  */
 public Object getData () {
 	checkDevice ();
@@ -1843,9 +1879,10 @@ public Font getSystemFont () {
 }
 
 /**
- * Returns the single instance of the system tray.
+ * Returns the single instance of the system tray or null
+ * when there is no system tray available for the platform.
  *
- * @return the receiver's user-interface thread
+ * @return the system tray or <code>null</code>
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -1995,12 +2032,12 @@ public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) {
  * @param data the platform specific GC data 
  * @return the platform specific GC handle
  * 
- * @exception SWTError <ul>
- *    <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li>
- * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li>
+ * </ul>
  */
 public int /*long*/ internal_new_GC (GCData data) {
 	if (isDisposed()) SWT.error(SWT.ERROR_DEVICE_DISPOSED);
@@ -2052,7 +2089,7 @@ boolean isValidThread () {
  * @return point with mapped coordinates 
  * 
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the point is null</li>
  *    <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> 
  * </ul>
  * @exception SWTException <ul>
@@ -2272,7 +2309,12 @@ int /*long*/ mouseHoverProc (int /*long*/ handle) {
  * and mouse events. The intent is to enable automated UI
  * testing by simulating the input from the user.  Most
  * SWT applications should never need to call this method.
- * 
+ * <p>
+ * Note that this operation can fail when the operating system
+ * fails to generate the event for any reason.  For example,
+ * this can happen when there is no such key or mouse button
+ * or when the system event queue is full.
+ * </p>
  * <p>
  * <b>Event Types:</b>
  * <p>KeyDown, KeyUp
@@ -2415,6 +2457,7 @@ void putGdkEvents () {
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li>
  * </ul>
  *
  * @see #sleep
@@ -2608,7 +2651,7 @@ void releaseDisplay () {
 /**
  * Removes the listener from the collection of listeners who will
  * be notifed when an event of the given type occurs anywhere in
- * this display.
+ * a widget.
  *
  * @param eventType the type of event to listen for
  * @param listener the listener which should no longer be notified when the event occurs
@@ -2842,8 +2885,8 @@ public void setCursorLocation (Point point) {
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #setData
- * @see #disposeExec
+ * @see #getData(String)
+ * @see #disposeExec(Runnable)
  */
 public void setData (String key, Object value) {
 	checkDevice ();
@@ -2921,8 +2964,8 @@ public void setData (String key, Object value) {
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  *
- * @see #getData
- * @see #disposeExec
+ * @see #getData()
+ * @see #disposeExec(Runnable)
  */
 public void setData (Object data) {
 	checkDevice ();
@@ -2949,6 +2992,7 @@ int setDirectionProc (int widget, int direction) {
  * @exception SWTException <ul>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li>
  * </ul>
  */
 public void setSynchronizer (Synchronizer synchronizer) {
@@ -3232,7 +3276,7 @@ static int untranslateKey (int key) {
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
- * @see Control#update
+ * @see Control#update()
  */
 public void update () {
 	checkDevice ();
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 615417ca5a..207b435663 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
@@ -16,6 +16,20 @@ import org.eclipse.swt.graphics.*;
 import org.eclipse.swt.events.*;
 
 /**
+ * Instances of this class represent a selectable
+ * user interface object that displays a text with 
+ * links.
+ * <p>
+ * <dl>
+ * <dt><b>Styles:</b></dt>
+ * <dt><b>Events:</b></dt>
+ * <dd>Selection</dd>
+ * </dl>
+ * <p>
+ * IMPORTANT: This class is <em>not</em> intended to be subclassed.
+ * </p>
+ * 
+ * @since 3.1
  */
 public class Link extends Control {
 	String text;
@@ -567,6 +581,15 @@ void setFontDescription (int /*long*/ font) {
 /**
  * Sets the receiver's text.
  * <p>
+ * The string can contain both regular text and hyperlinks.  A hyperlink
+ * 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.
+ * 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.
+ * </p>
  * 
  * @param string the new text
  *
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 97f7767736..4d409a2e11 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
@@ -84,9 +84,6 @@ public List (Composite parent, int style) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li>
- * </ul>
  *
  * @see #add(String,int)
  */
@@ -121,9 +118,6 @@ public void add (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li>
- * </ul>
  *
  * @see #add(String)
  */
@@ -386,9 +380,6 @@ GdkColor getForegroundColor () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public String getItem (int index) {
 	checkWidget();
@@ -417,9 +408,6 @@ public String getItem (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getItemCount () {
 	checkWidget();
@@ -436,9 +424,6 @@ public int getItemCount () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getItemHeight () {
 	checkWidget();
@@ -474,10 +459,6 @@ public int getItemHeight () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li>
- * </ul>
  */
 public String [] getItems () {
 	checkWidget();
@@ -515,10 +496,6 @@ public String [] getItems () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure while getting the selection</li>
- *    <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li>
- * </ul>
  */
 public String [] getSelection () {
 	checkWidget();
@@ -539,9 +516,6 @@ public String [] getSelection () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getSelectionCount () {
 	checkWidget();
@@ -562,9 +536,6 @@ public int getSelectionCount () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getSelectionIndex () {
 	checkWidget();
@@ -591,9 +562,6 @@ public int getSelectionIndex () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int [] getSelectionIndices () {
 	checkWidget();
@@ -771,10 +739,6 @@ public int indexOf (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li>
- *    <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li>
- * </ul>
  */
 public int indexOf (String string, int start) {
 	checkWidget();
@@ -838,9 +802,6 @@ void releaseWidget () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int index) {
 	checkWidget();
@@ -871,9 +832,6 @@ public void remove (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int start, int end) {
 	checkWidget();
@@ -908,9 +866,6 @@ public void remove (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (String string) {
 	checkWidget();
@@ -934,9 +889,6 @@ public void remove (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int [] indices) {
 	checkWidget();
@@ -1216,10 +1168,6 @@ void setForegroundColor (GdkColor color) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li>
- *    <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li>
- * </ul>
  */
 public void setItem (int index, String string) {
 	checkWidget();
@@ -1247,9 +1195,6 @@ public void setItem (int index, String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void setItems (String [] items) {
 	checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
index 8b30a8e73f..6d897bf8ab 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
@@ -721,7 +721,7 @@ void releaseWidget () {
  * Removes the listener from the collection of listeners who will
  * be notified when the menu events are generated for the control.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -754,7 +754,7 @@ void removeAccelerators (int /*long*/ accelGroup) {
  * Removes the listener from the collection of listeners who will
  * be notified when the help events are generated for the control.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
index 4f9279722c..29089d6325 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
@@ -510,7 +510,7 @@ void removeAccelerators (int /*long*/ accelGroup) {
  * Removes the listener from the collection of listeners who will
  * be notified when the arm events are generated for the control.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -534,7 +534,7 @@ public void removeArmListener (ArmListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the help events are generated for the control.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -558,7 +558,7 @@ public void removeHelpListener (HelpListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java
index 6be9f079e1..1bd9693324 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java
@@ -22,7 +22,7 @@ import org.eclipse.swt.events.*;
  * the parent control.
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>HORIZONTAL, VERTICAL</dd>
+ * <dd>HORIZONTAL, VERTICAL, SMOOTH</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection</dd>
  * </dl>
@@ -390,7 +390,7 @@ void releaseWidget () {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
index 7fd19d857a..c26b47ef8f 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 @@ public int getPageIncrement () {
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the <em>selection</em>, which is the receiver's position.
  *
  * @return the selection
  *
@@ -348,8 +348,8 @@ public void setPageIncrement (int value) {
 }
 
 /**
- * Sets the single <em>selection</em> that is the receiver's
- * value to the argument which must be greater than or equal
+ * Sets the <em>selection</em>, 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 11ae2aa765..b53daad0ad 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
@@ -101,7 +101,6 @@ ScrollBar (Scrollable parent, int style) {
  * 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.DRAG</code>.
  * <code>SWT.HOME</code>.
  * <code>SWT.END</code>.
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 148989475e..c6acc4856d 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
@@ -650,6 +650,21 @@ public Point getLocation () {
 	return new Point (x [0], y [0]);
 }
 
+/**
+ * Returns a point describing the minimum receiver's size. The
+ * x coordinate of the result is the minimum width of the receiver.
+ * The y coordinate of the result is the minimum height of the
+ * receiver.
+ *
+ * @return the receiver's size
+ *
+ * @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 Point getMinimumSize () {
 	checkWidget ();
 	int width = Math.max (1, minWidth + trimWidth ());
@@ -916,11 +931,11 @@ public void removeShellListener (ShellListener listener) {
 }
 
 /**
- * Moves the receiver to the top of the drawing order for
- * the display on which it was created (so that all other
- * shells on that display, which are not the receiver's
- * children will be drawn behind it) and asks the window
- * manager to make the shell active.
+ * If the receiver is visible, moves it to the top of the 
+ * drawing order for the display on which it was created 
+ * (so that all other shells on that display, which are not 
+ * the receiver's children will be drawn behind it) and asks 
+ * the window manager to make the shell active 
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1192,6 +1207,21 @@ public void setMinimized (boolean minimized) {
 	}
 }
 
+/**
+ * Sets the receiver's minimum size to the point 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.
+ *
+ * @param width the new minimum width for the receiver
+ * @param height the new minimum height for the receiver
+ *
+ * @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 setMinimumSize (int width, int height) {
 	checkWidget ();
 	GdkGeometry geometry = new GdkGeometry ();
@@ -1200,6 +1230,23 @@ public void setMinimumSize (int width, int height) {
 	OS.gtk_window_set_geometry_hints (shellHandle, 0, geometry, OS.GDK_HINT_MIN_SIZE);
 }
 
+/**
+ * Sets the receiver's minimum size to the point 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.
+ *
+ * @param size the new minimum size for the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the point 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 void setMinimumSize (Point size) {
 	checkWidget ();
 	if (size == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1417,11 +1464,11 @@ public void dispose () {
 }
 
 /**
- * Moves the receiver to the top of the drawing order for
- * the display on which it was created (so that all other
- * shells on that display, which are not the receiver's
- * children will be drawn behind it) and forces the window
- * manager to make the shell active.
+ * If the receiver is visible, moves it to the top of the 
+ * drawing order for the display on which it was created 
+ * (so that all other shells on that display, which are not 
+ * the receiver's children will be drawn behind it) and forces 
+ * the window manager to make the shell active.
  *
  * @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/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
index ae536f769d..b6d89f6b9a 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
@@ -272,7 +272,7 @@ public int getPageIncrement () {
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the <em>selection</em>, which is the receiver's value.
  *
  * @return the selection
  *
@@ -435,8 +435,8 @@ public void setPageIncrement (int value) {
 }
 
 /**
- * Sets the single <em>selection</em> that is the receiver's
- * value to the argument which must be greater than or equal
+ * Sets the <em>selection</em>, 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/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
index 91ba8c4b88..3c069d49fd 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
@@ -19,7 +19,8 @@ import org.eclipse.swt.events.*;
 
 /**
  * Instances of this class are selectable user interface
- * objects that allow the user to enter and modify number
+ * objects that allow the user to enter and modify numeric
+ * values.
  * <p>
  * <dl>
  * <dt><b>Styles:</b></dt>
@@ -30,6 +31,8 @@ import org.eclipse.swt.events.*;
  * <p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
  * </p>
+ * 
+ * @since 3.1
  */
 public class Spinner extends Composite {
 	static final int INNER_BORDER = 2;
@@ -370,9 +373,8 @@ public int getMinimum () {
 }
 
 /**
- * Returns the amount that the receiver's value will be
- * modified by when the page increment/decrement areas
- * are selected.
+ * Returns the amount that the receiver's position will be
+ * modified by when the page up/down keys are pressed.
  *
  * @return the page increment
  *
@@ -390,7 +392,7 @@ public int getPageIncrement () {
 }
 
 /**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the <em>selection</em>, which is the receiver's position.
  *
  * @return the selection 
  *
@@ -590,7 +592,7 @@ public void removeModifyListener (ModifyListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -658,11 +660,10 @@ void setForegroundColor (GdkColor color) {
 
 /**
  * Sets the amount that the receiver's value will be
- * modified by when the up/down (or right/left) arrows
- * are pressed to the argument, which must be at least 
- * one.
+ * modified by when the up/down arrows are pressed to
+ * the argument, which must be at least one.
  *
- * @param increment the new increment (must be greater than zero)
+ * @param value the new increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -724,12 +725,11 @@ public void setMinimum (int value) {
 }
 
 /**
- * Sets the amount that the receiver's value will be
- * modified by when the page increment/decrement areas
- * are selected to the argument, which must be at least
- * one.
+ * Sets the amount that the receiver's position will be
+ * modified by when the page up/down keys are pressed
+ * to the argument, which must be at least one.
  *
- * @param pageIncrement the page increment (must be greater than zero)
+ * @param value the page increment (must be greater than zero)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -745,9 +745,10 @@ public void setPageIncrement (int value) {
 }
 
 /**
- * Sets the single <em>selection</em> that is the receiver's
- * value to the argument which must be greater than or equal
- * to zero.
+ * Sets the <em>selection</em>, which is the receiver's
+ * position, to the argument. If the argument is not within
+ * the range specified by minimum and maximum, it will be
+ * adjusted to fall within this range.
  *
  * @param value the new selection (must be zero or greater)
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java
index bf1b2645bc..d4c79242b8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java
@@ -627,6 +627,9 @@ void setSelection (int index, boolean notify) {
  *
  * @param items the array of items
  *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the items array is null</li>
+ * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
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 578d4cdb37..666a8c2e7c 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
@@ -20,7 +20,7 @@ import org.eclipse.swt.events.*;
 /** 
  * Instances of this class implement a selectable user interface
  * object that displays a list of images and strings and issue
- * notificiation when selected.
+ * notification when selected.
  * <p>
  * The item children that may be added to instances of this class
  * must be of type <code>TableItem</code>.
@@ -218,7 +218,7 @@ public Point computeSize (int wHint, int hHint, boolean changed) {
 
 /**
  * Clears the item at the given zero-relative index in the receiver.
- * The text, icon and other attribues of the item are set to the default
+ * The text, icon and other attributes of the item are set to the default
  * value.  If the table was created with the SWT.VIRTUAL style, these
  * attributes are requested again as needed.
  *
@@ -265,7 +265,7 @@ public void clear (int index) {
  * </ul>
  * 
  * @see SWT#VIRTUAL
- * @see SWT.SetData
+ * @see SWT#SetData
  * 
  * @since 3.0
  */
@@ -303,7 +303,7 @@ public void clear (int start, int end) {
  * </ul>
  * 
  * @see SWT#VIRTUAL
- * @see SWT.SetData
+ * @see SWT#SetData
  * 
  * @since 3.0
  */
@@ -334,7 +334,7 @@ public void clear (int [] indices) {
  * </ul>
  * 
  * @see SWT#VIRTUAL
- * @see SWT.SetData
+ * @see SWT#SetData
  * 
  * @since 3.0
  */
@@ -865,7 +865,7 @@ public TableColumn getColumn (int index) {
  * Returns the number of columns contained in the receiver.
  * If no <code>TableColumn</code>s were created by the programmer,
  * this value is zero, despite the fact that visually, one column
- * of items is may be visible. This occurs when the programmer uses
+ * of items may be visible. This occurs when the programmer uses
  * the table like a list, adding items but never creating a column.
  *
  * @return the number of columns
@@ -874,9 +874,6 @@ public TableColumn getColumn (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public int getColumnCount () {
 	checkWidget();
@@ -902,7 +899,7 @@ int /*long*/[] getColumnTypes (int columnCount) {
 	return types;
 }
 
- /**
+/**
  * Returns an array of zero-relative integers that map
  * the creation order of the receiver's items to the
  * order in which they are currently being displayed.
@@ -923,6 +920,11 @@ int /*long*/[] getColumnTypes (int columnCount) {
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see Table#setColumnOrder(int[])
+ * @see TableColumn#getMoveable()
+ * @see TableColumn#setMoveable(boolean)
+ * @see SWT#Move
+ * 
  * @since 3.1
  */
 public int [] getColumnOrder () {
@@ -1734,9 +1736,6 @@ void releaseWidget () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int index) {
 	checkWidget();
@@ -1775,9 +1774,6 @@ public void remove (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int start, int end) {
 	checkWidget();
@@ -1817,9 +1813,6 @@ public void remove (int start, int end) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- * @exception SWTError <ul>
- *    <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li>
- * </ul>
  */
 public void remove (int [] indices) {
 	checkWidget();
@@ -2134,7 +2127,7 @@ boolean setCellData(int /*long*/ tree_model, int /*long*/ iter) {
  * in terms of the zero-relative ordering of when the items
  * were added.
  *
- * @param itemOrder the new order to display the items
+ * @param order the new order to display the items
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2144,7 +2137,12 @@ boolean setCellData(int /*long*/ tree_model, int /*long*/ iter) {
  *    <li>ERROR_NULL_ARGUMENT - if the item order is null</li>
  *    <li>ERROR_INVALID_ARGUMENT - if the item order is not the same length as the number of items</li>
  * </ul>
- *
+ * 
+ * @see Table#getColumnOrder()
+ * @see TableColumn#getMoveable()
+ * @see TableColumn#setMoveable(boolean)
+ * @see SWT#Move
+ * 
  * @since 3.1
  */
 public void setColumnOrder (int [] order) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java
index 156b9d5c39..2557c5c56c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java
@@ -231,6 +231,8 @@ public int getAlignment () {
  * 
  * @see Table#getColumnOrder()
  * @see Table#setColumnOrder(int[])
+ * @see TableColumn#setMoveable(boolean)
+ * @see SWT#Move
  * 
  * @since 3.1
  */
@@ -400,7 +402,7 @@ void releaseWidget () {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is moved or resized.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -425,7 +427,7 @@ public void removeControlListener (ControlListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -492,8 +494,10 @@ public void setImage (Image image) {
 
 /**
  * Sets the resizable attribute.  A column that is
- * not resizable cannot be dragged by the user but
- * may be resized by the programmer.
+ * resizable can be resized by the user dragging the
+ * edge of the header.  A column that is not resizable 
+ * cannot be dragged by the user but may be resized 
+ * by the programmer.
  *
  * @param resizable the resize attribute
  *
@@ -523,6 +527,8 @@ public void setResizable (boolean resizable) {
  * 
  * @see Table#setColumnOrder(int[])
  * @see Table#getColumnOrder()
+ * @see TableColumn#getMoveable()
+ * @see SWT#Move
  * 
  * @since 3.1
  */
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 2170b57342..79ad3f5dce 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
@@ -540,9 +540,6 @@ public String getText () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li>
- * </ul>
  */
 public String getText (int index) {
 	checkWidget ();
@@ -913,7 +910,7 @@ public void setImage (Image image) {
 }
 
 /**
- * Sets the image for multiple columns in the Table. 
+ * Sets the image for multiple columns in the table. 
  * 
  * @param images the array of new images
  *
@@ -944,6 +941,8 @@ public void setImage (Image [] images) {
  *    <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>
+ * 
+ * @deprecated this functionality is not supported on most platforms
  */
 public void setImageIndent (int indent) {
 	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 a8b0ec7627..d1bd0ea31f 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
@@ -1212,7 +1212,7 @@ public void removeModifyListener (ModifyListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -1237,7 +1237,7 @@ public void removeSelectionListener(SelectionListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is verified.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
index 75dc108e4a..2f2768a6b9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
@@ -637,7 +637,7 @@ void releaseWidget () {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -936,7 +936,7 @@ public void setToolTipText (String string) {
 }
 
 /**
- * Sets the width of the receiver.
+ * Sets the width of the receiver, for <code>SEPARATOR</code> ToolItems.
  *
  * @param width the new width
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java
index f394df210b..12af331fe2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java
@@ -730,7 +730,7 @@ public boolean open () {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is moved or resized.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -755,7 +755,7 @@ public void removeControlListener (ControlListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when keys are pressed and released on the system keyboard.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
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 095176d07c..d00c1ebcd8 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
@@ -30,7 +30,7 @@ import org.eclipse.swt.events.*;
  * </p><p>
  * <dl>
  * <dt><b>Styles:</b></dt>
- * <dd>SINGLE, MULTI, CHECK</dd>
+ * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION</dd>
  * <dt><b>Events:</b></dt>
  * <dd>Selection, DefaultSelection, Collapse, Expand</dd>
  * </dl>
@@ -677,10 +677,10 @@ GdkColor getBackgroundColor () {
 /**
  * Returns the column at the given, zero-relative index in the
  * receiver. Throws an exception if the index is out of range.
- * If no <code>TableColumn</code>s were created by the programmer,
+ * If no <code>TreeColumn</code>s were created by the programmer,
  * this method will throw <code>ERROR_INVALID_RANGE</code> despite
- * the fact that a single column of data may be visible in the table.
- * This occurs when the programmer uses the table like a list, adding
+ * the fact that a single column of data may be visible in the tree.
+ * This occurs when the programmer uses the tree like a list, adding
  * items but never creating a column.
  *
  * @param index the index of the column to return
@@ -693,7 +693,7 @@ GdkColor getBackgroundColor () {
  *    <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 TreeColumn getColumn (int index) {
@@ -704,10 +704,10 @@ public TreeColumn getColumn (int index) {
 
 /**
  * Returns the number of columns contained in the receiver.
- * If no <code>TableColumn</code>s were created by the programmer,
+ * If no <code>TreeColumn</code>s were created by the programmer,
  * this value is zero, despite the fact that visually, one column
- * of items is may be visible. This occurs when the programmer uses
- * the table like a list, adding items but never creating a column.
+ * of items may be visible. This occurs when the programmer uses
+ * the tree like a list, adding items but never creating a column.
  *
  * @return the number of columns
  *
@@ -715,10 +715,7 @@ public TreeColumn getColumn (int index) {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li>
- * </ul>
- *
+ * 
  * @since 3.1
  */
 public int getColumnCount () {
@@ -747,11 +744,11 @@ int /*long*/[] getColumnTypes (int columnCount) {
 }
 
 /**
- * Returns an array of <code>TableColumn</code>s which are the
- * columns in the receiver. If no <code>TableColumn</code>s were
+ * Returns an array of <code>TreeColumn</code>s which are the
+ * columns in the receiver. If no <code>TreeColumn</code>s were
  * created by the programmer, the array is empty, despite the fact
  * that visually, one column of items may be visible. This occurs
- * when the programmer uses the table like a list, adding items but
+ * when the programmer uses the tree like a list, adding items but
  * never creating a column.
  * <p>
  * Note: This is not the actual structure used by the receiver
@@ -765,7 +762,7 @@ int /*long*/[] getColumnTypes (int columnCount) {
  *    <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 TreeColumn [] getColumns () {
@@ -804,7 +801,7 @@ GdkColor getForegroundColor () {
  *    <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 getGridLineWidth () {
@@ -822,7 +819,7 @@ public int getGridLineWidth () {
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
- * @since 3.1
+ * @since 3.1 
  */
 public int getHeaderHeight () {
 	checkWidget ();
@@ -853,7 +850,7 @@ public int getHeaderHeight () {
  *    <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 boolean getHeaderVisible () {
@@ -1027,7 +1024,7 @@ TreeItem [] getItems (int /*long*/ parent) {
  *    <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 boolean getLinesVisible() {
@@ -1734,8 +1731,8 @@ void setForegroundColor (GdkColor color) {
  *    <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>
- *
- * @since3.1
+ * 
+ * @since 3.1
  */
 public void setHeaderVisible (boolean show) {
 	checkWidget ();
@@ -1757,7 +1754,7 @@ public void setHeaderVisible (boolean show) {
  *    <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 setLinesVisible (boolean show) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java
index 3e5591cad1..907718e239 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java
@@ -18,7 +18,7 @@ import org.eclipse.swt.graphics.*;
 import org.eclipse.swt.events.*;
 
 /**
- * Instances of this class represent a column in a table widget.
+ * Instances of this class represent a column in a tree widget.
  *  <dl>
  * <dt><b>Styles:</b></dt>
  * <dd>LEFT, RIGHT, CENTER</dd>
@@ -30,6 +30,8 @@ import org.eclipse.swt.events.*;
  * </p><p>
  * IMPORTANT: This class is <em>not</em> intended to be subclassed.
  * </p>
+ * 
+ * @since 3.1
  */
 public class TreeColumn extends Item {
 	int /*long*/ labelHandle, imageHandle, buttonHandle;
@@ -39,7 +41,7 @@ public class TreeColumn extends Item {
 
 /**
  * Constructs a new instance of this class given its parent
- * (which must be a <code>Table</code>) and a style value
+ * (which must be a <code>Tree</code>) and a style value
  * describing its behavior and appearance. The item is added
  * to the end of the items maintained by its parent.
  * <p>
@@ -77,7 +79,7 @@ public TreeColumn (Tree parent, int style) {
 
 /**
  * Constructs a new instance of this class given its parent
- * (which must be a <code>Table</code>), a style value
+ * (which must be a <code>Tree</code>), a style value
  * describing its behavior and appearance, and the index
  * at which to place it in the items maintained by its parent.
  * <p>
@@ -216,7 +218,7 @@ public int getAlignment () {
 }
 
 /**
- * Returns the receiver's parent, which must be a <code>Table</code>.
+ * Returns the receiver's parent, which must be a <code>Tree</code>.
  *
  * @return the receiver's parent
  *
@@ -376,7 +378,7 @@ void releaseWidget () {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is moved or resized.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
@@ -401,7 +403,7 @@ public void removeControlListener (ControlListener listener) {
  * Removes the listener from the collection of listeners who will
  * be notified when the control is selected.
  *
- * @param listener the listener which should be notified
+ * @param listener the listener which should no longer be notified
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the listener is null</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
index 6a42bfa392..e1e604b6c8 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
@@ -198,7 +198,7 @@ protected void checkSubclass () {
  * Returns the receiver's background color.
  *
  * @return the background color
- *
+ * 
  * @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>
@@ -247,7 +247,7 @@ public Color getBackground (int index) {
 
 /**
  * Returns a rectangle describing the receiver's size and location
- * relative to its parent at a column in the table.
+ * relative to its parent at a column in the tree.
  *
  * @param index the index that specifies the column
  * @return the receiver's bounding column rectangle
@@ -256,7 +256,7 @@ public Color getBackground (int index) {
  *    <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 Rectangle getBounds (int index) {
@@ -395,9 +395,10 @@ public Rectangle getBounds () {
 /**
  * Returns <code>true</code> if the receiver is checked,
  * and false otherwise.  When the parent does not have
- * the <code>CHECK</code> style, return false.
+ * the <code>CHECK style, return false.
+ * <p>
  *
- * @return the checked state of the checkbox
+ * @return the checked state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -530,10 +531,10 @@ public Color getForeground (int index) {
 /**
  * Returns <code>true</code> if the receiver is grayed,
  * and false otherwise. When the parent does not have
- * the <code>CHECK</code> style, return false.
+ * the <code>CHECK style, return false.
  * <p>
  *
- * @return the grayed state of the checkbox
+ * @return the grayed state
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -566,8 +567,8 @@ public Image getImage () {
  *    <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>
- *
- * @since3.1
+ * 
+ * @since 3.1
  */
 public Image getImage (int index) {
 	checkWidget ();
@@ -589,7 +590,7 @@ public Image getImage (int index) {
 /**
  * Returns a rectangle describing the size and location
  * relative to its parent of an image at a column in the
- * tree.
+ * table.
  *
  * @param index the index that specifies the column
  * @return the receiver's bounding image rectangle
@@ -598,7 +599,7 @@ public Image getImage (int index) {
  *    <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 Rectangle getImageBounds (int index) {
@@ -764,10 +765,7 @@ public String getText () {
  *    <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>
- * @exception SWTError <ul>
- *    <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li>
- * </ul>
- *
+ * 
  * @since 3.1
  */
 public String getText (int index) {
@@ -808,7 +806,7 @@ void releaseWidget () {
  * if the argument is null.
  *
  * @param color the new color (or null)
- *
+ * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
@@ -1023,6 +1021,8 @@ public void setFont (int index, Font font) {
  *
  * @param color the new color (or null)
  *
+ * @since 2.0
+ * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>
@@ -1127,7 +1127,7 @@ public void setGrayed (boolean grayed) {
  *    <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 setImage (int index, Image image) {
@@ -1158,7 +1158,7 @@ public void setImage (Image image) {
 }
 
 /**
- * Sets the image for multiple columns in the Tree. 
+ * Sets the image for multiple columns in the tree. 
  * 
  * @param images the array of new images
  *
@@ -1170,7 +1170,7 @@ public void setImage (Image image) {
  *    <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 setImage (Image [] images) {
@@ -1194,7 +1194,7 @@ public void setImage (Image [] images) {
  *    <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 setText (int index, String string) {
@@ -1216,7 +1216,7 @@ public void setText (String string) {
 }
 
 /**
- * Sets the text for multiple columns in the table. 
+ * Sets the text for multiple columns in the tree. 
  * 
  * @param strings the array of new strings
  *
@@ -1227,8 +1227,8 @@ public void setText (String string) {
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
- *
- * @since3.1
+ * 
+ * @since 3.1
  */
 public void setText (String [] strings) {
 	checkWidget ();