Bug 408895 - Do the annual javadoc/copyright bash for 4.3v4331fI20130527-2000

14 files changed, 105 insertions, 45 deletions

diff --git a/bundles/org.eclipse.swt/.settings/.api_filters b/bundles/org.eclipse.swt/.settings/.api_filters
index f98994f33c..e2c548b2b2 100644
--- a/bundles/org.eclipse.swt/.settings/.api_filters
+++ b/bundles/org.eclipse.swt/.settings/.api_filters
@@ -1271,6 +1271,13 @@
                 <message_argument value="GCData()"/>
             </message_arguments>
         </filter>
+        <filter id="627060751">
+            <message_arguments>
+                <message_argument value="PAINTSTRUCT"/>
+                <message_argument value="GCData"/>
+                <message_argument value="ps"/>
+            </message_arguments>
+        </filter>
     </resource>
     <resource path="Eclipse SWT/win32/org/eclipse/swt/widgets/ColorDialog.java" type="org.eclipse.swt.widgets.ColorDialog">
         <filter comment="@since 3.8 is valid in the 3.100 stream" id="1141899266">
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GCData.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GCData.java
index bd1b8fcc48..5877579780 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GCData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GCData.java
@@ -24,15 +24,15 @@ import org.eclipse.swt.internal.cocoa.*;
  * platforms, and should never be called from application code.
  * </p>
  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
- * @noinstantiate This class is not intended to be instantiated by clients.
+ * @noreference This class is not intended to be referenced by clients
  */
 public final class GCData {
 	public Device device;
 	public int style, state = -1;
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
-	public double /*float*/ [] foreground, background;
+
+	public double[] /*float*/ [] foreground;
+
+	public double[] background;
 	public Pattern foregroundPattern;
 	public Pattern backgroundPattern;
 	public Font font;
@@ -54,17 +54,11 @@ public final class GCData {
 	public NSLayoutManager layoutManager;
 	public NSTextContainer textContainer;
 	public NSColor fg, bg;
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
 	public double /*float*/ drawXOffset, drawYOffset;
 	public NSRect paintRect;
 	public NSBezierPath path;
 	public NSAffineTransform transform, inverseTransform;
 	public NSBezierPath clipPath, visiblePath;
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
 	public long /*int*/ visibleRgn;
 	public NSView view;
 	public NSSize size;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java
index 707e765b30..004dc6c342 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java
@@ -99,7 +99,6 @@ void sendFocusEvent(int type) {
  * </ul>
  *
  * @see SWT
- * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
 public Canvas (Composite parent, int style) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java
index f9c3e8e9a0..2c1e7f9acd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java
@@ -421,7 +421,7 @@ void fixTabList (Control control) {
  * will be one of the following constants defined in class
  * <code>SWT</code>:
  * <code>INHERIT_NONE</code>, <code>INHERIT_DEFAULT</code>,
- * <code>INHERTIT_FORCE</code>.
+ * <code>INHERIT_FORCE</code>.
  *
  * @return the background mode
  *
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 d27ffa40f2..79066812ed 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
@@ -23,7 +23,7 @@ import org.eclipse.swt.internal.cocoa.*;
  * <dl>
  * <dt><b>Styles:</b>
  * <dd>BORDER</dd>
- * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
+ * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT, FLIP_TEXT_DIRECTION</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
  *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
@@ -1932,6 +1932,19 @@ public Point getSize () {
 	return new Point((int)rect.width, (int)rect.height);
 }
 
+/**
+ * Returns the text direction of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
+ *
+ * @return the text direction style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @since 3.102
+ */
 public int getTextDirection() {
 	checkWidget ();
 	/* return the widget orientation */
@@ -4120,6 +4133,30 @@ boolean setTabItemFocus () {
 	return forceFocus ();
 }
 
+/**
+ * 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>.
+ * <p>
+ * <code>setOrientation</code> would override this value with the text direction
+ * that is consistent with the new orientation.
+ * </p>
+ * <p>
+ * <b>Warning</b>: This API is currently only implemented on Windows.
+ * It doesn't set the base text direction on GTK and Cocoa.
+ * </p>
+ *
+ * @param textDirection the base text direction style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see SWT#FLIP_TEXT_DIRECTION
+ * 
+ * @since 3.102
+ */
 public void setTextDirection(int textDirection) {
 	checkWidget ();
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java
index c8b8c7c72d..0420a43bf7 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java
@@ -1155,6 +1155,8 @@ public Widget findWidget (long /*int*/ handle, long /*int*/ id) {
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @noreference This method is not intended to be referenced by clients.
+ * 
  * @since 3.3
  */
 public Widget findWidget (Widget widget, long /*int*/ id) {
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 91476701e2..a0999ea173 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
@@ -193,17 +193,15 @@ public void addModifyListener (ModifyListener listener) {
 /**
  * Adds a segment listener.
  * <p>
- * A <code>SegmentEvent</code> is sent whenever text content is being modified. The user can 
- * customize appearance of text by indicating certain characters to be inserted
+ * A <code>SegmentEvent</code> is sent whenever text content is being modified or
+ * a segment listener is added or removed. You can 
+ * customize the appearance of text by indicating certain characters to be inserted
  * at certain text offsets. This may be used for bidi purposes, e.g. when
  * adjacent segments of right-to-left text should not be reordered relative to
  * each other. 
- * E.g., Multiple Java string literals in a right-to-left language
+ * E.g., multiple Java string literals in a right-to-left language
  * should generally remain in logical order to each other, that is, the
  * way they are stored.
- * <br>
- * After SegmentListener is added, user may call <code>setText(String)</code>
- * for segments to take effect.
  * </p>
  * <p>
  * <b>Warning</b>: This API is currently only implemented on Windows and GTK.
@@ -1502,10 +1500,6 @@ public void removeModifyListener (ModifyListener listener) {
 /**
  * Removes the listener from the collection of listeners who will
  * be notified when the receiver's text is modified.
- * <p>
- * After SegmentListener is removed, user may call <code>setText(String)</code>
- * for segments to take effect.
- * </p>
  *
  * @param listener the listener which should no longer be notified
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Tree.java
index a25d32e0e5..8e541d2ccb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Tree.java
@@ -2988,7 +2988,7 @@ void setShouldScrollClipView (long /*int*/ id, long /*int*/ sel, boolean shouldS
 /**
  * Sets the receiver's selection to the given item.
  * The current selection is cleared before the new item is selected,
- * and if necessary, the receiver is scrolled to make the new selection visible.
+ * and if necessary the receiver is scrolled to make the new selection visible.
  * <p>
  * If the item is not in the receiver, then it is ignored.
  * </p>
@@ -3015,7 +3015,7 @@ public void setSelection (TreeItem item) {
 /**
  * Sets the receiver's selection to be the given array of items.
  * The current selection is cleared before the new items are selected,
- * and if necessary, the receiver is scrolled to make the new selection visible.
+ * and if necessary the receiver is scrolled to make the new selection visible.
  * <p>
  * Items that are not in the receiver are ignored.
  * If the receiver is single-select and multiple items are specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GCData.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GCData.java
index ce25efeaa7..89f3041560 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GCData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GCData.java
@@ -24,15 +24,15 @@ import org.eclipse.swt.*;
  * platforms, and should never be called from application code.
  * </p>
  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
- * @noinstantiate This class is not intended to be instantiated by clients.
+ * @noreference This class is not intended to be referenced by clients
  */
 public final class GCData {
 	public Device device;
 	public int style, state = -1;
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
-	public GdkColor foreground, background;
+
+	public GdkColor foreground;
+
+	public GdkColor background;
 	public Font font;
 	public Pattern foregroundPattern;
 	public Pattern backgroundPattern;
@@ -48,9 +48,6 @@ public final class GCData {
 	public int interpolation = SWT.DEFAULT;
 	public Image image;
 
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
 	public long /*int*/ clipRgn, context, layout, damageRgn, drawable, cairo;
 	public double cairoXoffset, cairoYoffset;
 	public boolean disposeCairo;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
index 014d4d72b7..d7fe3d2e65 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
@@ -68,7 +68,6 @@ Canvas () {}
  * </ul>
  *
  * @see SWT
- * @see Widget#checkSubclass
  * @see Widget#getStyle
  */
 public Canvas (Composite parent, int style) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
index fb70ae8257..23d6790df8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
@@ -553,7 +553,7 @@ boolean forceFocus (long /*int*/ focusHandle) {
  * will be one of the following constants defined in class
  * <code>SWT</code>:
  * <code>INHERIT_NONE</code>, <code>INHERIT_DEFAULT</code>,
- * <code>INHERTIT_FORCE</code>.
+ * <code>INHERIT_FORCE</code>.
  *
  * @return the background mode
  *
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 12219c962e..0bd3b6e410 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
@@ -25,7 +25,7 @@ import org.eclipse.swt.internal.gtk.*;
  * <dl>
  * <dt><b>Styles:</b>
  * <dd>BORDER</dd>
- * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd>
+ * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT, FLIP_TEXT_DIRECTION</dd>
  * <dt><b>Events:</b>
  * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter,
  *     MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move,
@@ -268,6 +268,19 @@ public int getOrientation () {
 	return style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT);
 }
 
+/**
+ * Returns the text direction of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
+ *
+ * @return the text direction style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @since 3.102
+ */
 public int getTextDirection() {
 	checkWidget ();
 	/* return the widget orientation */
@@ -4623,6 +4636,30 @@ boolean setTabItemFocus (boolean next) {
 	return forceFocus ();
 }
 
+/**
+ * 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>.
+ * <p>
+ * <code>setOrientation</code> would override this value with the text direction
+ * that is consistent with the new orientation.
+ * </p>
+ * <p>
+ * <b>Warning</b>: This API is currently only implemented on Windows.
+ * It doesn't set the base text direction on GTK and Cocoa.
+ * </p>
+ *
+ * @param textDirection the base text direction style
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ * 
+ * @see SWT#FLIP_TEXT_DIRECTION
+ * 
+ * @since 3.102
+ */
 public void setTextDirection(int textDirection) {
 	checkWidget ();
 }
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
index 38276c8bd2..f7c4856be3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
@@ -3165,7 +3165,7 @@ void setScrollWidth (long /*int*/ column, TreeItem item) {
 /**
  * Sets the receiver's selection to the given item.
  * The current selection is cleared before the new item is selected,
- * and if necessary, the receiver is scrolled to make the new selection visible.
+ * and if necessary the receiver is scrolled to make the new selection visible.
  * <p>
  * If the item is not in the receiver, then it is ignored.
  * </p>
@@ -3192,7 +3192,7 @@ public void setSelection (TreeItem item) {
 /**
  * Sets the receiver's selection to be the given array of items.
  * The current selection is cleared before the new items are selected,
- * and if necessary, the receiver is scrolled to make the new selection visible.
+ * and if necessary the receiver is scrolled to make the new selection visible.
  * <p>
  * Items that are not in the receiver are ignored.
  * If the receiver is single-select and multiple items are specified,
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GCData.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GCData.java
index 1e955bae0d..deb926a6a1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GCData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/GCData.java
@@ -45,14 +45,8 @@ public final class GCData {
 	public int alpha = 0xFF;
 
 	public Image image;
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
 	public PAINTSTRUCT ps;
 	public int layout = -1;
-	/**
-	 * @noreference This field is not intended to be referenced by clients.
-	 */
 	public long /*int*/ hPen, hOldPen, hBrush, hOldBrush, hNullBitmap,
 		hwnd, gdipGraphics, gdipPen, gdipBrush, gdipFgBrush, gdipBgBrush,
 		gdipFont, hGDIFont;