84681

9 files changed, 47 insertions, 21 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTError.java b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTError.java
index f760142d79..04abc96bcb 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTError.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTError.java
@@ -64,7 +64,8 @@ public SWTError () {
 /**
  * Constructs a new instance of this class with its 
  * stack trace and message filled in. The error code is
- * set to an unspecified value.
+ * set to an unspecified value.  Specifying <code>null</code>
+ * as the message is equivalent to specifying an empty string.
  *
  * @param message the detail message for the exception
  */
@@ -85,7 +86,9 @@ public SWTError (int code) {
 /**
  * Constructs a new instance of this class with its 
  * stack trace, error code and message filled in.
- *
+ * Specifying <code>null</code> as the message is
+ * equivalent to specifying an empty string.
+ * 
  * @param code the SWT error code
  * @param message the detail message for the exception
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTException.java b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTException.java
index a8d88d5f5a..f6e4948c02 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTException.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWTException.java
@@ -55,7 +55,8 @@ public SWTException () {
 /**
  * Constructs a new instance of this class with its 
  * stack trace and message filled in. The error code is
- * set to an unspecified value.
+ * set to an unspecified value.  Specifying <code>null</code>
+ * as the message is equivalent to specifying an empty string.
  *
  * @param message the detail message for the exception
  */
@@ -76,6 +77,8 @@ public SWTException (int code) {
 /**
  * Constructs a new instance of this class with its 
  * stack trace, error code and message filled in.
+ * Specifying <code>null</code> as the message is
+ * equivalent to specifying an empty string.
  *
  * @param code the SWT error code
  * @param message the detail message for the exception
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/graphics/ImageData.java b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/graphics/ImageData.java
index 5030c9ea4f..d7cbfaa8f9 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/graphics/ImageData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/graphics/ImageData.java
@@ -1064,7 +1064,9 @@ public ImageData getTransparencyMask() {
 }
 
 /**
- * Returns the image transparency type.
+ * Returns the image transparency type, which will be one of
+ * <code>SWT.TRANSPARENCY_NONE</code>, <code>SWT.TRANSPARENCY_MASK</code>,
+ * <code>SWT.TRANSPARENCY_PIXEL</code> or <code>SWT.TRANSPARENCY_ALPHA</code>.
  *
  * @return the receiver's transparency type
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/FontData.java
index 77004168b4..e6509d4faa 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/FontData.java
@@ -556,7 +556,8 @@ public void setName(String name) {
 /**
  * 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/win32/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GC.java
index 4269132e7d..75803a7683 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GC.java
@@ -3600,9 +3600,11 @@ public void setClipping (Path path) {
 /**
  * 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>
@@ -3620,9 +3622,11 @@ public void setClipping (Rectangle rect) {
 /**
  * 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>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Button.java
index bfa2068c04..1369c2c320 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Button.java
@@ -641,9 +641,9 @@ boolean setFixedFocus () {
 
 /**
  * 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/win32/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java
index 8c3d202558..e4650627da 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java
@@ -2997,7 +2997,8 @@ int widgetStyle () {
  * @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>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java
index 6e859fd089..369b275330 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Display.java
@@ -557,7 +557,8 @@ int asciiKey (int key) {
  * 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
@@ -565,7 +566,7 @@ int asciiKey (int key) {
  * 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>
@@ -838,7 +839,8 @@ void destroyDisplay () {
 /**
  * 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.
  * 
@@ -1000,7 +1002,9 @@ int foregroundIdleProc (int code, int wParam, int lParam) {
 /**
  * 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
@@ -3276,9 +3280,10 @@ public void setData (Object data) {
 /**
  * On platforms which support it, sets the application name
  * to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * 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 */
@@ -3379,7 +3384,8 @@ public boolean sleep () {
  * 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.
+ * 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
@@ -3387,7 +3393,7 @@ public boolean sleep () {
  * 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_FAILED_EXEC - if an exception occured when executing the runnable</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Text.java
index 9db15d6107..2a24dd4855 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Text.java
@@ -823,7 +823,8 @@ int getTabWidth (int tabs) {
 /**
  * Gets 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
@@ -955,6 +956,9 @@ public int getTopPixel () {
  *
  * @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>
@@ -1582,6 +1586,8 @@ public void setText (String string) {
  * 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