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 2cccef0..59065b8 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
@@ -60,6 +60,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
  * 
  * @param device the device on which to allocate the path
  * 
@@ -97,6 +100,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
  * 
  * @param device the device on which to allocate the path
  * @param path the path to make a copy
@@ -146,12 +152,15 @@
 }
 
 /**
- * Constructs a new Path with the specifed PathData.
+ * Constructs a new Path with the specified PathData.
  * <p>
  * This operation requires the operating system's advanced
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
  * 
  * @param device the device on which to allocate the path
  * @param data the data for the path
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 9b1d49c..d3f7052 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
@@ -58,6 +58,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
  * 
  * @param device the device on which to allocate the pattern
  * @param image the image that the pattern will draw
@@ -97,6 +100,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
  * 
  * @param device the device on which to allocate the pattern
  * @param x1 the x coordinate of the starting corner of the gradient
@@ -132,6 +138,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
  * 
  * @param device the device on which to allocate the pattern
  * @param x1 the x coordinate of the starting corner of the gradient
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 11b3711..1900f3f 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
@@ -54,6 +54,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the transform when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the Transform
  * 
@@ -81,6 +84,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the transform when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the Transform
  * @param elements an array of floats that describe the transformation matrix
@@ -110,6 +116,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the transform when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the Transform
  * @param m11 the first element of the first row of the matrix
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
index dc79e6d..387bcb9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
@@ -17,7 +17,7 @@
  * Instances of this class manage the operating system resources that
  * implement SWT's RGB color model. To create a color you can either
  * specify the individual color components as integers in the range 
- * 0 to 255 or provide an instance of an <code>RGB</code>. 
+ * 0 to 255 or provide an instance of an <code>RGB</code> or <code>RGBA</code>. 
  * <p>
  * Application code must explicitly invoke the <code>Color.dispose()</code> 
  * method to release the operating system resources managed by each instance
@@ -25,6 +25,7 @@
  * </p>
  *
  * @see RGB
+ * @see RGBA
  * @see Device#getSystemColor
  * @see <a href="http://www.eclipse.org/swt/snippets/#color">Color and RGB snippets</a>
  * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: PaintExample</a>
@@ -95,7 +96,7 @@
  * @param red the amount of red in the color
  * @param green the amount of green in the color
  * @param blue the amount of blue in the color
- * @param alpha the amount of alpha in the color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the amount of alpha in the color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -142,7 +143,7 @@
 
 /**	 
  * Constructs a new instance of this class given a device and an
- * <code>RGBA</code> describing the desired red, green, blue & alpah values.
+ * <code>RGBA</code> describing the desired red, green, blue & alpha values.
  * On limited color devices, the color instance created by this call
  * may not have the same RGBA values as the ones specified by the
  * argument. The RGBA values on the returned instance will be the color
@@ -152,7 +153,7 @@
  * </p>
  *
  * @param device the device on which to allocate the color
- * @param rgba the RGBA values of the desired color
+ * @param rgba the RGBA values of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -184,7 +185,7 @@
  *
  * @param device the device on which to allocate the color
  * @param rgb the RGB values of the desired color
- * @param alpha the alpha value of the desired color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the alpha value of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -231,13 +232,14 @@
 }
 
 /**
- * Returns the amount of alpha in the color, from 0 to 255.
+ * Returns the amount of alpha in the color, from 0 (transparent) to 255 (opaque).
  *
  * @return the alpha component of the color
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * @since 3.104
  */
 public int getAlpha() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
index 2991f9b..c3cfc20 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
@@ -146,6 +146,7 @@
  * @see SWT#CURSOR_IBEAM
  * @see SWT#CURSOR_NO
  * @see SWT#CURSOR_HAND
+ * @see #dispose()
  */
 public Cursor(Device device, int style) {
 	super(device);
@@ -241,6 +242,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Cursor(Device device, ImageData source, ImageData mask, int hotspotX, int hotspotY) {
 	super(device);
@@ -341,6 +344,8 @@
  *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
  * </ul>
  * 
+ * @see #dispose()
+ * 
  * @since 3.0
  */
 public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
index 4586247..20c7dd2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
@@ -90,6 +90,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Font(Device device, FontData fd) {
 	super(device);
@@ -125,6 +127,8 @@
  *    <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
  * </ul>
  * 
+ * @see #dispose()
+ * 
  * @since 2.1
  */
 public Font(Device device, FontData[] fds) {
@@ -166,6 +170,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a font could not be created from the given arguments</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Font(Device device, String name, int height, int style) {
 	super(device);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
index 55a5b53..104b876 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
@@ -129,6 +129,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for GC creation</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
  * </ul>
+ * @see #dispose()
  */
 public GC(Drawable drawable) {
 	this(drawable, 0);
@@ -158,7 +159,9 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for GC creation</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
  * </ul>
- *  
+ * 
+ * @see #dispose()
+ * 
  * @since 2.1.2
  */
 public GC(Drawable drawable, int style) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
index 49114f8..3f39395 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
@@ -161,6 +161,9 @@
  * and depth). For example, Windows 95, 98, and ME do not allow
  * images larger than 16M.
  * </p>
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the image
  * @param width the width of the new image
@@ -173,6 +176,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, int width, int height) {
 	super(device);
@@ -198,6 +203,9 @@
  * <dt><b>{@link SWT#IMAGE_GRAY}</b></dt>
  * <dd>the result is a copy of srcImage which has a <em>gray scale</em> look</dd>
  * </dl>
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the image
  * @param srcImage the image to use as the source
@@ -216,6 +224,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, Image srcImage, int flag) {
 	super(device);
@@ -355,6 +365,9 @@
  * and depth). For example, Windows 95, 98, and ME do not allow
  * images larger than 16M.
  * </p>
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the image
  * @param bounds a rectangle specifying the image's width and height (must not be null)
@@ -367,6 +380,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, Rectangle bounds) {
 	super(device);
@@ -384,6 +399,9 @@
 /**
  * Constructs an instance of this class from the given
  * <code>ImageData</code>.
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the image
  * @param data the image data to create the image from (must not be null)
@@ -398,6 +416,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, ImageData data) {
 	super(device);
@@ -422,6 +442,9 @@
  * the source image should contain black wherever the icon is to be
  * transparent.
  * </p>
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the icon
  * @param source the color data for the icon
@@ -435,6 +458,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, ImageData source, ImageData mask) {
 	super(device);
@@ -486,6 +511,9 @@
  *          return image;
  *     }
  * </pre>
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the image
  * @param stream the input stream to load the image from
@@ -503,6 +531,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, InputStream stream) {
 	super(device);
@@ -525,6 +555,9 @@
  * This constructor is provided for convenience when loading
  * a single image only. If the specified file contains
  * multiple images, only the first one will be used.
+ * <p>
+ * You must dispose the image when it is no longer required. 
+ * </p>
  *
  * @param device the device on which to create the image
  * @param filename the name of the file to load the image from
@@ -542,6 +575,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, String filename) {
 	super(device);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
index e1bb639..43586e9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
@@ -59,6 +59,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the path when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the path
  * 
@@ -100,6 +103,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the path when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the path
  * @param path the path to make a copy
@@ -145,12 +151,15 @@
 }
 
 /**
- * Constructs a new Path with the specifed PathData.
+ * Constructs a new Path with the specified PathData.
  * <p>
  * This operation requires the operating system's advanced
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the path when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the path
  * @param data the data for the path
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
index 3489ddd..04bb99b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
@@ -48,6 +48,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the pattern
  * @param image the image that the pattern will draw
@@ -90,6 +93,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the pattern
  * @param x1 the x coordinate of the starting corner of the gradient
@@ -125,6 +131,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the pattern
  * @param x1 the x coordinate of the starting corner of the gradient
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
index 15c0c39..dbe3ff2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
@@ -45,10 +45,15 @@
 
 /**
  * Constructs a new empty region.
+ * <p>
+ * You must dispose the region when it is no longer required. 
+ * </p>
  * 
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Region() {
 	this(null);
@@ -69,7 +74,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
  * </ul>
  *
- * @see #dispose
+ * @see #dispose()
  * 
  * @since 3.0
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
index cc9dcc5..30e7dd3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
@@ -53,6 +53,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the transform when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the Transform
  * 
@@ -80,6 +83,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the transform when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the Transform
  * @param elements an array of floats that describe the transformation matrix
@@ -109,6 +115,9 @@
  * graphics subsystem which may not be available on some
  * platforms.
  * </p>
+ * <p>
+ * You must dispose the transform when it is no longer required. 
+ * </p>
  * 
  * @param device the device on which to allocate the Transform
  * @param m11 the first element of the first row of the matrix
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java
index acd4043..c7d276b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java
@@ -886,6 +886,9 @@
  * on Windows (starting with XP), GTK+ and OSX.  On other platforms,
  * a Button that has an image and text set into it will display the
  * image or text that was set most recently.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java
index df6d352..52bb739 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java
@@ -117,7 +117,10 @@
 
 /**
  * Adds the argument to the end of the receiver's list.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param string the new item
  *
  * @exception IllegalArgumentException <ul>
@@ -157,6 +160,9 @@
  * Note: To add an item at the end of the list, use the
  * result of calling <code>getItemCount()</code> as the
  * index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new item
@@ -1748,6 +1754,9 @@
  * setting the text to a string containing line breaks or
  * other special characters will probably cause it to 
  * display incorrectly.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new text
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
index aa28a44..366da3d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
@@ -4151,8 +4151,11 @@
 
 /**
  * Sets the base text direction (a.k.a. "paragraph direction") of the receiver,
- * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code> or
- * <code>SWT.RIGHT_TO_LEFT</code>.
+ * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code>,
+ * <code>SWT.RIGHT_TO_LEFT</code>, or a bitwise disjunction 
+ * <code>SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT</code>. The latter stands for an
+ * "auto" direction, which implies that a control containing text derives the
+ * direction from the directionality of the first strong bidi character.
  * <p>
  * <code>setOrientation</code> would override this value with the text direction
  * that is consistent with the new orientation.
@@ -4169,6 +4172,8 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  * 
+ * @see SWT#LEFT_TO_RIGHT
+ * @see SWT#RIGHT_TO_LEFT
  * @see SWT#FLIP_TEXT_DIRECTION
  * 
  * @since 3.102
@@ -4410,6 +4415,10 @@
  * argument, which is specified in display relative coordinates,
  * to coordinates relative to the receiver.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ * 
  * @param x the x coordinate to be translated
  * @param y the y coordinate to be translated
  * @return the translated coordinates
@@ -4431,6 +4440,10 @@
  * argument, which is specified in display relative coordinates,
  * to coordinates relative to the receiver.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ * 
  * @param point the point to be translated (must not be null)
  * @return the translated coordinates
  *
@@ -4453,6 +4466,10 @@
  * argument, which is specified in coordinates relative to
  * the receiver, to display relative coordinates.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ * 
  * @param x the x coordinate to be translated
  * @param y the y coordinate to be translated
  * @return the translated coordinates
@@ -4474,6 +4491,10 @@
  * argument, which is specified in coordinates relative to
  * the receiver, to display relative coordinates.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ * 
  * @param point the point to be translated (must not be null)
  * @return the translated coordinates
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java
index 02d5199..fbfead2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java
@@ -639,6 +639,10 @@
  * 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 must not be null. 
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  *
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java
index 02f2a8b..4e5fe88 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java
@@ -247,6 +247,9 @@
  * platform specific manner.  The mnemonic indicator character
  * '&amp;' can be escaped by doubling it in the string, causing
  * a single '&amp;' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java
index eadd840..a48d22a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java
@@ -503,6 +503,10 @@
  * '&amp;' can be escaped by doubling it in the string, causing
  * a single '&amp;' to be displayed.
  * </p>
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * 
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java
index 33ab4ba..e94fde4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java
@@ -102,7 +102,10 @@
 
 /**
  * Adds the argument to the end of the receiver's list.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param string the new item
  *
  * @exception IllegalArgumentException <ul>
@@ -135,6 +138,9 @@
  * Note: To add an item at the end of the list, use the
  * result of calling <code>getItemCount()</code> as the
  * index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new item
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
index 27a45f9..156f105 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
@@ -1012,7 +1012,10 @@
 
 /**
  * Sets the text for multiple columns in the table. 
- * 
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param strings the array of new strings
  *
  * @exception IllegalArgumentException <ul>
@@ -1034,7 +1037,10 @@
 
 /**
  * Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param index the column index
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java
index 7c5af67..226bdbd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java
@@ -2108,7 +2108,10 @@
  * Sets the contents of the receiver to the given string. If the receiver has style
  * SINGLE and the argument contains multiple lines of text, the result of this
  * operation is undefined and may vary from platform to platform.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
index 608b1c4..de0a34c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
@@ -1107,6 +1107,9 @@
  * manner.  The mnemonic indicator character '&amp;' can be
  * escaped by doubling it in the string, causing a single
  * '&amp;' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  * 
  * @param string the new text
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
index 1186df7..880838f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
@@ -1417,7 +1417,10 @@
 
 /**
  * Sets the text for multiple columns in the tree. 
- * 
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param strings the array of new strings
  *
  * @exception IllegalArgumentException <ul>
@@ -1441,7 +1444,10 @@
 
 /**
  * Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param index the column index
  * @param string the new text
  *
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 2d6cfe6..fcebe63 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
@@ -18,7 +18,7 @@
  * Instances of this class manage the operating system resources that
  * implement SWT's RGB color model. To create a color you can either
  * specify the individual color components as integers in the range
- * 0 to 255 or provide an instance of an <code>RGB</code>.
+ * 0 to 255 or provide an instance of an <code>RGB</code> or <code>RGBA</code>. 
  * <p>
  * Application code must explicitly invoke the <code>Color.dispose()</code>
  * method to release the operating system resources managed by each instance
@@ -26,6 +26,7 @@
  * </p>
  *
  * @see RGB
+ * @see RGBA
  * @see Device#getSystemColor
  * @see <a href="http://www.eclipse.org/swt/snippets/#color">Color and RGB snippets</a>
  * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: PaintExample</a>
@@ -97,7 +98,7 @@
  * @param red the amount of red in the color
  * @param green the amount of green in the color
  * @param blue the amount of blue in the color
- * @param alpha the amount of alpha in the color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the amount of alpha in the color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -144,7 +145,7 @@
 
 /**	 
  * Constructs a new instance of this class given a device and an
- * <code>RGBA</code> describing the desired red, green, blue & alpah values.
+ * <code>RGBA</code> describing the desired red, green, blue & alpha values.
  * On limited color devices, the color instance created by this call
  * may not have the same RGBA values as the ones specified by the
  * argument. The RGBA values on the returned instance will be the color
@@ -154,7 +155,7 @@
  * </p>
  *
  * @param device the device on which to allocate the color
- * @param rgba the RGBA values of the desired color
+ * @param rgba the RGBA values of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -186,7 +187,7 @@
  *
  * @param device the device on which to allocate the color
  * @param rgb the RGB values of the desired color
- * @param alpha the alpha value of the desired color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the alpha value of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -243,13 +244,14 @@
 }
 
 /**
- * Returns the amount of alpha in the color, from 0 to 255.
+ * Returns the amount of alpha in the color, from 0 (transparent) to 255 (opaque).
  *
  * @return the alpha component of the color
  *
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * @since 3.104
  */
 public int getAlpha() {
 	if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 7dec05b..b112419 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
@@ -130,6 +130,7 @@
  * @see SWT#CURSOR_IBEAM
  * @see SWT#CURSOR_NO
  * @see SWT#CURSOR_HAND
+ * @see #dispose()
  */
 public Cursor(Device device, int style) {
 	super(device);
@@ -203,6 +204,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Cursor(Device device, ImageData source, ImageData mask, int hotspotX, int hotspotY) {
 	super(device);
@@ -285,6 +288,8 @@
  *    <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
  * </ul>
  *
+ * @see #dispose()
+ *
  * @since 3.0
  */
 public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
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 001fcd8..e0c0449 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
@@ -67,6 +67,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Font(Device device, FontData fd) {
 	super(device);
@@ -95,7 +97,9 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
  * </ul>
- *
+ * 
+ * @see #dispose()
+ * 
  * @since 2.1
  */
 public Font(Device device, FontData[] fds) {
@@ -131,6 +135,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES - if a font could not be created from the given arguments</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Font(Device device, String name, int height, int style) {
 	super(device);
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 6fe597f..4675ea8 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
@@ -120,6 +120,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for GC creation</li>
  *    <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
  * </ul>
+ * @see #dispose()
  */
 public GC(Drawable drawable) {
 	this(drawable, 0);
@@ -150,6 +151,8 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
  * </ul>
  *
+ * @see #dispose()
+ *
  * @since 2.1.2
  */
 public GC(Drawable drawable, int style) {
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 e4c5450..217b1ad 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
@@ -197,6 +197,9 @@
  * and depth). For example, Windows 95, 98, and ME do not allow
  * images larger than 16M.
  * </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the image
  * @param width the width of the new image
@@ -209,6 +212,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ * 
+ * @see #dispose()
  */
 public Image(Device device, int width, int height) {
 	super(device);
@@ -228,6 +233,9 @@
  * <dt><b>{@link SWT#IMAGE_GRAY}</b></dt>
  * <dd>the result is a copy of srcImage which has a <em>gray scale</em> look</dd>
  * </dl>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the image
  * @param srcImage the image to use as the source
@@ -246,6 +254,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Image(Device device, Image srcImage, int flag) {
 	super(device);
@@ -511,6 +521,9 @@
  * and depth). For example, Windows 95, 98, and ME do not allow
  * images larger than 16M.
  * </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the image
  * @param bounds a rectangle specifying the image's width and height (must not be null)
@@ -523,6 +536,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Image(Device device, Rectangle bounds) {
 	super(device);
@@ -534,6 +549,9 @@
 /**
  * Constructs an instance of this class from the given
  * <code>ImageData</code>.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the image
  * @param data the image data to create the image from (must not be null)
@@ -548,6 +566,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Image(Device device, ImageData data) {
 	super(device);
@@ -566,6 +586,9 @@
  * the source image should contain black wherever the icon is to be
  * transparent.
  * </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the icon
  * @param source the color data for the icon
@@ -579,6 +602,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Image(Device device, ImageData source, ImageData mask) {
 	super(device);
@@ -625,6 +650,9 @@
  *          return image;
  *     }
  * </pre>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the image
  * @param stream the input stream to load the image from
@@ -642,6 +670,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Image(Device device, InputStream stream) {
 	super(device);
@@ -658,6 +688,9 @@
  * This constructor is provided for convenience when loading
  * a single image only. If the specified file contains
  * multiple images, only the first one will be used.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
  *
  * @param device the device on which to create the image
  * @param filename the name of the file to load the image from
@@ -675,6 +708,8 @@
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Image(Device device, String filename) {
 	super(device);
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 2288eda..52a582b 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
@@ -45,10 +45,15 @@
 
 /**
  * Constructs a new empty region.
- *
+ * <p>
+ * You must dispose the region when it is no longer required.
+ * </p>
+ * 
  * @exception SWTError <ul>
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
  * </ul>
+ *
+ * @see #dispose()
  */
 public Region() {
 	this(null);
@@ -69,7 +74,7 @@
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
  * </ul>
  *
- * @see #dispose
+ * @see #dispose()
  *
  * @since 3.0
  */
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 77d4253..7fef861 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
@@ -1092,6 +1092,9 @@
  * on Windows (starting with XP), GTK+ and OSX.  On other platforms,
  * a Button that has an image and text set into it will display the
  * image or text that was set most recently.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  * @param string the new text
  *
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 7edd29d..be06855 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
@@ -116,7 +116,10 @@
 
 /**
  * Adds the argument to the end of the receiver's list.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param string the new item
  *
  * @exception IllegalArgumentException <ul>
@@ -142,6 +145,9 @@
  * Note: To add an item at the end of the list, use the
  * result of calling <code>getItemCount()</code> as the
  * index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new item
@@ -2152,6 +2158,9 @@
  * setting the text to a string containing line breaks or
  * other special characters will probably cause it to
  * display incorrectly.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new text
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 8414438..8f5fe71 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
@@ -1383,6 +1383,10 @@
  * argument, which is specified in display relative coordinates,
  * to coordinates relative to the receiver.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
  * @param x the x coordinate to be translated
  * @param y the y coordinate to be translated
  * @return the translated coordinates
@@ -1410,6 +1414,10 @@
  * argument, which is specified in display relative coordinates,
  * to coordinates relative to the receiver.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
  * @param point the point to be translated (must not be null)
  * @return the translated coordinates
  *
@@ -1432,6 +1440,10 @@
  * argument, which is specified in coordinates relative to
  * the receiver, to display relative coordinates.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
  * @param x the x coordinate to be translated
  * @param y the y coordinate to be translated
  * @return the translated coordinates
@@ -1459,6 +1471,10 @@
  * argument, which is specified in coordinates relative to
  * the receiver, to display relative coordinates.
  * <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
  * @param point the point to be translated (must not be null)
  * @return the translated coordinates
  *
@@ -4751,8 +4767,11 @@
 
 /**
  * Sets the base text direction (a.k.a. "paragraph direction") of the receiver,
- * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code> or
- * <code>SWT.RIGHT_TO_LEFT</code>.
+ * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code>,
+ * <code>SWT.RIGHT_TO_LEFT</code>, or a bitwise disjunction 
+ * <code>SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT</code>. The latter stands for an
+ * "auto" direction, which implies that a control containing text derives the
+ * direction from the directionality of the first strong bidi character.
  * <p>
  * <code>setOrientation</code> would override this value with the text direction
  * that is consistent with the new orientation.
@@ -4769,6 +4788,8 @@
  *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
  * </ul>
  *
+ * @see SWT#LEFT_TO_RIGHT
+ * @see SWT#RIGHT_TO_LEFT
  * @see SWT#FLIP_TEXT_DIRECTION
  *
  * @since 3.102
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 1d0e384..c77e7aa 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
@@ -725,6 +725,10 @@
  * 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 must not be null.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  *
  * @param string the new text
  *
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 fec04ab..255119a 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
@@ -563,6 +563,14 @@
  * For filters with multiple extensions, use semicolon as
  * a separator, e.g. "*.jpg;*.png".
  * </p>
+ * <p>
+ * Note: On Mac, setting the file extension filter affects how
+ * app bundles are treated by the dialog. When a filter extension
+ * having the app extension (.app) is selected, bundles are treated
+ * as files. For all other extension filters, bundles are treated
+ * as directories. When no filter extension is set, bundles are
+ * treated as files.
+ * </p>
  *
  * @param extensions the file extension filter
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
index f0f59cd..1e25600 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
@@ -334,6 +334,9 @@
  * platform specific manner.  The mnemonic indicator character
  * '&amp;' can be escaped by doubling it in the string, causing
  * a single '&amp;' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  * @param string the new text
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java
index 3d05a18..c971970 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java
@@ -612,7 +612,11 @@
  * '&amp;' can be escaped by doubling it in the string, causing
  * a single '&amp;' to be displayed.
  * </p>
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
+ * 
  * @param string the new text
  *
  * @exception IllegalArgumentException <ul>
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 effeb89..9a45a90 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
@@ -79,6 +79,10 @@
 
 /**
  * Adds the argument to the end of the receiver's list.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  *
  * @param string the new item
  *
@@ -110,6 +114,9 @@
  * Note: To add an item at the end of the list, use the
  * result of calling <code>getItemCount()</code> as the
  * index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new item
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 d39fe47..c854070 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
@@ -599,9 +599,10 @@
  * Returns the receiver's shell. For all controls other than
  * shells, this simply returns the control's nearest ancestor
  * shell. Shells return themselves, even if they are children
- * of other shells.
+ * of other shells. Returns null if receiver or its ancestor 
+ * is the application menubar.
  *
- * @return the receiver's shell
+ * @return the receiver's shell or null
  *
  * @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/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
index 56a6ad6..60856c8 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
@@ -2141,6 +2141,11 @@
  * default shape of the shell is restored.  The shell
  * must be created with the style SWT.NO_TRIM in order
  * to specify a region.
+ * <p>
+ * NOTE: This method also sets the size of the shell. Clients should
+ * not call {@link #setSize} or {@link #setBounds} on this shell.
+ * Furthermore, the passed region should not be modified any more.
+ * </p>
  *
  * @param region the region that defines the shape of the shell (or null)
  *
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 22fd786..63f4964 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
@@ -1145,7 +1145,10 @@
 
 /**
  * Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param index the column index
  * @param string the new text
  *
@@ -1177,7 +1180,10 @@
 
 /**
  * Sets the text for multiple columns in the table.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param strings the array of new strings
  *
  * @exception IllegalArgumentException <ul>
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 3c05eb5..ec609a2 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
@@ -2463,6 +2463,10 @@
  * Sets the contents of the receiver to the given string. If the receiver has style
  * SINGLE and the argument contains multiple lines of text, the result of this
  * operation is undefined and may vary from platform to platform.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  *
  * @param string the new text
  *
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 7ecf9cc..e64ecc9 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
@@ -1110,6 +1110,9 @@
  * manner.  The mnemonic indicator character '&amp;' can be
  * escaped by doubling it in the string, causing a single
  * '&amp;' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
  * </p>
  *
  * @param string the new text
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 824f2f5..41d75b4 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
@@ -1513,7 +1513,10 @@
 
 /**
  * Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param index the column index
  * @param string the new text
  *
@@ -1547,7 +1550,10 @@
 
 /**
  * Sets the text for multiple columns in the tree.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
  * @param strings the array of new strings
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java
index d877a39..967f18c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java
@@ -610,6 +610,7 @@
 	redraw ();
 }
 
+@Override
 void destroyWidget () {
 	MenuItem cascade = this.cascade;
 	long /*int*/ hMenu = handle, hCB = hwndCB;
@@ -913,6 +914,7 @@
 	return OS.GetMenuItemCount (handle);
 }
 
+@Override
 String getNameText () {
 	String result = "";
 	MenuItem [] items = getItems ();
@@ -998,9 +1000,10 @@
  * Returns the receiver's shell. For all controls other than
  * shells, this simply returns the control's nearest ancestor
  * shell. Shells return themselves, even if they are children
- * of other shells.
+ * of other shells. Returns null if receiver or its ancestor 
+ * is the application menubar.
  *
- * @return the receiver's shell
+ * @return the receiver's shell or null
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1171,12 +1174,14 @@
 	}
 }
 
+@Override
 void releaseHandle () {
 	super.releaseHandle ();
 	handle = hwndCB = 0;
 	cascade = null;
 }
 
+@Override
 void releaseChildren (boolean destroy) {
 	MenuItem [] items = getItems ();
 	for (int i=0; i<items.length; i++) {
@@ -1192,6 +1197,7 @@
 	super.releaseChildren (destroy);
 }
 
+@Override
 void releaseParent () {
 	super.releaseParent ();
 	if ((style & SWT.BAR) != 0) {
@@ -1206,6 +1212,7 @@
 	}
 }
 
+@Override
 void releaseWidget () {
 	super.releaseWidget ();
 	backgroundImage = null;
@@ -1271,6 +1278,7 @@
 	eventTable.unhook (SWT.Show, listener);
 }
 
+@Override
 void reskinChildren (int flags) {
 	MenuItem [] items = getItems ();
 	for (int i=0; i<items.length; i++) {