Bug 468439 - Do the annual javadoc bash for 4.5I20150527-2010

- javadoc changes.

Change-Id: I7407abcffd09e1e2e5f65aff39fdd4d6e4448ad6
Signed-off-by: Lakshmi Shanmugam <lshanmug@in.ibm.com>

44 files changed, 366 insertions, 40 deletions

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 2cccef0ac0..59065b81f8 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 @@ public class Path extends Resource {
  * 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 @@ public Path (Device device) {
  * 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 @@ public Path (Device device, Path path, float flatness) {
 }
 
 /**
- * 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 9b1d49c876..d3f7052c71 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 @@ public class Pattern extends Resource {
  * 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 @@ public Pattern(Device device, Image image) {
  * 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 @@ public Pattern(Device device, float x1, float y1, float x2, float y2, Color colo
  * 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 11b371121e..1900f3f971 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 @@ public class Transform extends Resource {
  * 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 @@ public Transform (Device device) {
  * 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 @@ public Transform(Device device, float[] elements) {
  * 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 dc79e6ddba..387bcb9e27 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 @@ import org.eclipse.swt.*;
  * 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 @@ import org.eclipse.swt.*;
  * </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 @@ public Color(Device device, int red, int green, int blue) {
  * @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 @@ public Color(Device device, RGB rgb) {
 
 /**	 
  * 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 @@ public Color(Device device, RGB rgb) {
  * </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 @@ public Color(Device device, RGBA rgba) {
  *
  * @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 @@ public boolean equals(Object object) {
 }
 
 /**
- * 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 2991f9b03d..c3cfc20de7 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 @@ Cursor(Device device) {
  * @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 @@ public Cursor(Device device, int style) {
  * @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 @@ void createNSCursor(int hotspotX, int hotspotY, byte[] buffer, int width, int he
  *    <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 45862474fd..20c7dd2333 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 @@ Font(Device device) {
  * @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 @@ public Font(Device device, FontData fd) {
  *    <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 @@ public Font(Device device, FontData[] fds) {
  * @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 55a5b53735..104b876083 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 @@ GC() {
  *    <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 @@ public GC(Drawable drawable) {
  *    <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 49114f8102..3f39395a0c 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 @@ Image(Device device) {
  * 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 @@ Image(Device device) {
  * @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 @@ public Image(Device device, int width, int height) {
  * <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 @@ public Image(Device device, int width, int height) {
  * @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 @@ public Image(Device device, Image srcImage, int flag) {
  * 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 @@ public Image(Device device, Image srcImage, int flag) {
  * @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 @@ public Image(Device device, Rectangle bounds) {
 /**
  * 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 @@ public Image(Device device, Rectangle bounds) {
  * @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 @@ public Image(Device device, ImageData data) {
  * 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 @@ public Image(Device device, ImageData data) {
  * @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 @@ public Image(Device device, ImageData source, ImageData mask) {
  *          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 @@ public Image(Device device, ImageData source, ImageData mask) {
  * @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 @@ public Image(Device device, InputStream stream) {
  * 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 @@ public Image(Device device, InputStream stream) {
  * @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 e1bb639f0f..43586e90a3 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 @@ public class Path extends Resource {
  * 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 @@ public Path (Device device) {
  * 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 @@ public Path (Device device, Path path, float flatness) {
 }
 
 /**
- * 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 3489ddd51e..04bb99b68a 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 @@ public class Pattern extends Resource {
  * 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 @@ public Pattern(Device device, Image image) {
  * 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 @@ public Pattern(Device device, float x1, float y1, float x2, float y2, Color colo
  * 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 15c0c39828..dbe3ff2bc4 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 @@ public final class Region extends Resource {
 
 /**
  * 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 @@ public Region() {
  *    <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 cc9dcc5beb..30e7dd3e29 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 @@ public class Transform extends Resource {
  * 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 @@ public Transform (Device device) {
  * 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 @@ public Transform(Device device, float[] elements) {
  * 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 acd4043671..c7d276b04d 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 @@ public void setSelection (boolean selected) {
  * 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 df6d3525d0..52bb7393c6 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 @@ public Combo (Composite parent, int style) {
 
 /**
  * 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 @@ public void add (String string) {
  * 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 @@ public void setSelection (Point selection) {
  * 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 aa28a44189..366da3de13 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 @@ boolean setTabItemFocus () {
 
 /**
  * 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 @@ boolean setTabItemFocus () {
  *    <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 @@ String tooltipText () {
  * 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 @@ public Point toControl (int x, int y) {
  * 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 @@ public Point toControl (Point point) {
  * 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 @@ public Point toDisplay (int x, int y) {
  * 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 02d519909b..fbfead221a 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 @@ void setSavedFocus (Control control) {
  * 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 02f2a8b812..4e5fe880cc 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 @@ void setOrientation () {
  * 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 eadd84059a..a48d22aae6 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 @@ public void setImage (Image image) {
  * '&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 33ab4ba9c8..e94fde4d69 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 @@ boolean acceptsFirstResponder (long /*int*/ id, long /*int*/ sel) {
 
 /**
  * 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 @@ public void add (String string) {
  * 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 27a45f938f..156f105fc2 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 @@ public void setImageIndent (int indent) {
 
 /**
  * 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 @@ public void setText (String [] strings) {
 
 /**
  * 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 7c5af673ab..226bdbd37c 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 @@ public void setTabs (int tabs) {
  * 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 608b1c4708..de0a34c5c2 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 @@ public void setSelection (boolean selected) {
  * 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 1186df77ec..880838fe67 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 @@ public void setItemCount (int count) {
 
 /**
  * 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 @@ public void setText (String [] strings) {
 
 /**
  * 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 2d6cfe62a5..fcebe632dd 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 @@ import org.eclipse.swt.*;
  * 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 @@ import org.eclipse.swt.*;
  * </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 @@ public Color(Device device, int red, int green, int blue) {
  * @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 @@ public Color(Device device, RGB rgb) {
 
 /**	 
  * 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 @@ public Color(Device device, RGB rgb) {
  * </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 @@ public Color(Device device, RGBA rgba) {
  *
  * @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 @@ public boolean equals(Object object) {
 }
 
 /**
- * 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 7dec05b741..b112419968 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 @@ Cursor (Device device) {
  * @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 @@ public Cursor(Device device, int style) {
  * @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 @@ public Cursor(Device device, ImageData source, ImageData mask, int hotspotX, int
  *    <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 001fcd8c55..e0c044977c 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 @@ Font(Device device) {
  * @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 @@ public Font(Device device, FontData fd) {
  * @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 @@ public Font(Device device, FontData[] fds) {
  * @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 6fe597f993..4675ea85f0 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 @@ GC() {
  *    <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 @@ public GC(Drawable drawable) {
  *    <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 e4c5450cc1..217b1adc55 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 @@ Image(Device device) {
  * 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 @@ Image(Device device) {
  * @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 @@ public Image(Device device, int width, int height) {
  * <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 @@ public Image(Device device, int width, int height) {
  * @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 @@ public Image(Device device, Image srcImage, int flag) {
  * 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 @@ public Image(Device device, Image srcImage, int flag) {
  * @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 @@ public Image(Device device, Rectangle bounds) {
 /**
  * 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 @@ public Image(Device device, Rectangle bounds) {
  * @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 @@ public Image(Device device, ImageData data) {
  * 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 @@ public Image(Device device, ImageData data) {
  * @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 @@ public Image(Device device, ImageData source, ImageData mask) {
  *          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 @@ public Image(Device device, ImageData source, ImageData mask) {
  * @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 @@ public Image(Device device, InputStream stream) {
  * 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 @@ public Image(Device device, InputStream stream) {
  * @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 2288eda509..52a582beb9 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 @@ public final class Region extends Resource {
 
 /**
  * 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 @@ public Region() {
  *    <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 77d42533a6..7fef8617d2 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 @@ public void setSelection (boolean selected) {
  * 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 7edd29d291..be06855b9b 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 @@ public Combo (Composite parent, int style) {
 
 /**
  * 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 @@ public void add (String string) {
  * 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 @@ public void setSelection (Point selection) {
  * 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 841443845f..8f5fe71daa 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 @@ public void setLayoutData (Object layoutData) {
  * 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 @@ public Point toControl (int x, int y) {
  * 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 @@ public Point toControl (Point point) {
  * 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 @@ public Point toDisplay (int x, int y) {
  * 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 @@ boolean setTabItemFocus (boolean next) {
 
 /**
  * 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 @@ boolean setTabItemFocus (boolean next) {
  *    <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 1d0e384ff1..c77e7aab37 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 @@ void setSavedFocus (Control control) {
  * 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 fec04abeb3..255119aea1 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 @@ public void setFileName (String string) {
  * 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 f0f59cdf1c..1e256003cc 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 @@ void setOrientation (boolean create) {
  * 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 3d05a182e4..c971970dab 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 @@ public void setImage (Image image) {
  * '&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 effeb89e1b..9a45a901cb 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 @@ public List (Composite parent, int style) {
 
 /**
  * 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 @@ public void add (String string) {
  * 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 d39fe4700a..c854070896 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 @@ public Menu getParentMenu () {
  * 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 56a6ad672d..60856c873d 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 @@ public void setModified (boolean modified) {
  * 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 22fd786153..63f4964c32 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 @@ public void setImageIndent (int indent) {
 
 /**
  * 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 @@ public void setText (String string) {
 
 /**
  * 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 3c05eb5d9a..ec609a2dfa 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 @@ void setTabStops (int tabs) {
  * 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 7ecf9cc2e5..e64ecc9819 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 @@ boolean setTabItemFocus (boolean next) {
  * 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 824f2f5ce0..41d75b4734 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 @@ public void setItemCount (int count) {
 
 /**
  * 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 @@ public void setText (String string) {
 
 /**
  * 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 d877a39d72..967f18cab2 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 @@ void destroyItem (MenuItem item) {
 	redraw ();
 }
 
+@Override
 void destroyWidget () {
 	MenuItem cascade = this.cascade;
 	long /*int*/ hMenu = handle, hCB = hwndCB;
@@ -913,6 +914,7 @@ int GetMenuItemCount (long /*int*/ handle) {
 	return OS.GetMenuItemCount (handle);
 }
 
+@Override
 String getNameText () {
 	String result = "";
 	MenuItem [] items = getItems ();
@@ -998,9 +1000,10 @@ public Menu getParentMenu () {
  * 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 @@ void redraw () {
 	}
 }
 
+@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 @@ void releaseChildren (boolean destroy) {
 	super.releaseChildren (destroy);
 }
 
+@Override
 void releaseParent () {
 	super.releaseParent ();
 	if ((style & SWT.BAR) != 0) {
@@ -1206,6 +1212,7 @@ void releaseParent () {
 	}
 }
 
+@Override
 void releaseWidget () {
 	super.releaseWidget ();
 	backgroundImage = null;
@@ -1271,6 +1278,7 @@ public void removeMenuListener (MenuListener listener) {
 	eventTable.unhook (SWT.Show, listener);
 }
 
+@Override
 void reskinChildren (int flags) {
 	MenuItem [] items = getItems ();
 	for (int i=0; i<items.length; i++) {