Bug 314492 - Do the annual copyright/javadoc bashAFTER_JAVADOC_BASH_FOR_36RC3

8 files changed, 275 insertions, 19 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
index f696a8cec8..b102d6f774 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
@@ -443,7 +443,7 @@ void init(PathData data) {
  * <p>
  * This method gets the dispose state for the Path.
  * When a Path has been disposed, it is an error to
- * invoke any other method using the Path.
+ * invoke any other method (except {@link #dispose()}) using the Path.
  *
  * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
index 44eb166b21..738287d944 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
@@ -172,7 +172,7 @@ void destroy() {
  * <p>
  * This method gets the dispose state for the Pattern.
  * When a Pattern has been disposed, it is an error to
- * invoke any other method using the Pattern.
+ * invoke any other method (except {@link #dispose()}) using the Pattern.
  *
  * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
index ea89969116..79f89ac4ef 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
@@ -199,7 +199,7 @@ public void invert() {
  * <p>
  * This method gets the dispose state for the Transform.
  * When a Transform has been disposed, it is an error to
- * invoke any other method using the Transform.
+ * invoke any other method (except {@link #dispose()}) using the Transform.
  *
  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
  */
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java
index 329a02df7a..56a5e0a549 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java
@@ -108,13 +108,26 @@ public int getItemCount () {
 	return itemCount;
 }
 
+/**
+ * Returns the <code>TaskItem</code> for the given <code>Shell</code> or the <code>TaskItem</code> 
+ * for the application if the <code>Shell</code> parameter is <code>null</code>.
+ * If the requested item is not supported by the platform it returns <code>null</code>.
+ * 
+ * @param shell the shell for which the task item is requested, or null to request the application item
+ * @return the task item for the given shell or the application
+ *
+ * @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>
+ */
 public TaskItem getItem (Shell shell) {
 	checkWidget ();
 	return null;
 }
 
 /**
- * Returns an array of <code>TaskBarItem</code>s which are the items
+ * Returns an array of <code>TaskItem</code>s which are the items
  * in the receiver. 
  * <p>
  * Note: This is not the actual structure used by the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java
index 92fabc18d2..4c76d8805c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java
@@ -15,7 +15,7 @@ import org.eclipse.swt.*;
 import org.eclipse.swt.graphics.*;
 
 /**
- * Instances of this class represent a taskbar item.
+ * Instances of this class represent a task item.
  * 
  * <dl>
  * <dt><b>Styles:</b></dt>
@@ -84,16 +84,49 @@ void destroyWidget () {
 	releaseHandle ();
 }
 
+/**
+ * Returns the receiver's pop up menu if it has one, or null
+ * if it does not.
+ *
+ * @return the receiver's menu
+ *
+ * @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>
+ */
 public Menu getMenu () {
 	checkWidget ();
 	return menu;
 } 
 
+/**
+ * Returns the receiver's overlay image if it has one, or null
+ * if it does not.
+ *
+ * @return the receiver's overlay image
+ *
+ * @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>
+ */
 public Image getOverlayImage () {
 	checkWidget();
 	return overlayImage;
 }
 
+/**
+ * Returns the receiver's overlay text, which will be an empty
+ * string if it has never been set.
+ *
+ * @return the receiver's overlay text
+ *
+ * @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>
+ */
 public String getOverlayText () {
 	checkWidget();
 	return overlayText;
@@ -115,11 +148,31 @@ public TaskBar getParent () {
 	return parent;
 }
 
+/**
+ * Returns the receiver's progress.
+ *
+ * @return the receiver's progress
+ *
+ * @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>
+ */
 public int getProgress () {
 	checkWidget ();
 	return progress;
 }
 
+/**
+ * Returns the receiver's progress state.
+ *
+ * @return the receiver's progress state
+ *
+ * @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>
+ */
 public int getProgressState () {
 	checkWidget ();
 	return progressState;
@@ -136,6 +189,37 @@ void releaseWidget () {
 	overlayText = null;
 }
 
+/**
+ * Sets the receiver's pop up menu to the argument. The way the menu is
+ * shown is platform specific.
+ * 
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return the NULL.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * set this feature on the <code>TaskItem</code> for application.<br>
+ * On Windows, this feature will only work on RCP applications.</p>
+ *
+ * <p>
+ * The menu should be fully created before this method is called.
+ * Dynamic changes to the menu after the method is called will not be reflected
+ * in the native menu.</p> 
+ *
+ * @param menu the new pop up menu
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_MENU_NOT_POP_UP - the menu is not a pop up menu</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the menu has been disposed</li> 
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public void setMenu (Menu menu) {
 	checkWidget ();
 	if (menu != null) {
@@ -148,12 +232,26 @@ public void setMenu (Menu menu) {
 }
 
 /**
- * Sets the receiver's overlay image.
+ * Sets the receiver's overlay image, which may be null
+ * indicating that no image should be displayed. The bounds
+ * for the overlay image is determined by the platform and in 
+ * general it should be a small image.
  *
- * @param overlayImage the new overlay image
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return the NULL.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param overlayImage the new overlay image (may be null)
  *
  * @exception IllegalArgumentException <ul>
- *    <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ *    <li>ERROR_INVALID_ARGUMENT - if the overlayImage has been disposed</li> 
  * </ul>
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -166,18 +264,104 @@ public void setOverlayImage (Image overlayImage) {
 	this.overlayImage = overlayImage;
 }
 
+/**
+ * Sets the receiver's overlay text. The space available to display the
+ * overlay text is platform dependent and in general it should be no longer
+ * than a few characters.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return an empty string.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param overlayText the new overlay text
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the overlayText is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ *    <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
 public void setOverlayText (String overlayText) {
 	checkWidget ();
 	if (overlayText == null) error (SWT.ERROR_NULL_ARGUMENT);
 	this.overlayText = overlayText;
 }
 
+/**
+ * Sets the receiver's progress state, the state can be one of
+ * the following:
+ * <p><ul>
+ * <li>{@link SWT#DEFAULT}</li>
+ * <li>{@link SWT#NORMAL}</li>
+ * <li>{@link SWT#PAUSED}</li>
+ * <li>{@link SWT#ERROR}</li>
+ * <li>{@link SWT#INDETERMINATE}</li>
+ * </ul></p>
+ * 
+ * The percentage of progress shown by the states <code>SWT#NORMAL</code>, <code>SWT#PAUSED</code>, 
+ * <code>SWT#ERROR</code> is set with <code>setProgress()</code>. <br>
+ * The state <code>SWT#DEFAULT</code> indicates that no progress should be shown.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return <code>SWT#DEFAULT</code>.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param progressState the new progress state 
+ *
+ * @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 {@link #setProgress(int)}
+ */
 public void setProgressState (int progressState) {
 	checkWidget ();
 	if (this.progressState == progressState) return;
 	this.progressState = progressState;
 }
 
+/**
+ * Sets the receiver's progress, the progress represents a percentage and
+ * should be in range from 0 to 100. The progress is only shown when the progress
+ * state is different than <code>SWT#DEFAULT</code>.
+ *
+ * <p>
+ * This feature might not be available for the receiver on all
+ * platforms. The application code can check if it is supported
+ * by calling the respective get method. When the feature is not
+ * available, the get method will always return zero.</p>
+ *
+ * <p>
+ * For better cross platform support, the application code should
+ * first try to set this feature on the <code>TaskItem</code> for the 
+ * main shell then on the <code>TaskItem</code> for the application.</p>
+ *
+ * @param progress the new progress
+ *
+ * @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 {@link #setProgressState(int)}
+ */
 public void setProgress (int progress) {
 	checkWidget ();
 	progress = Math.max(0, Math.min(progress, PROGRESS_MAX));
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java
index 06f73fc22a..a0f8fbcea6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java
@@ -1157,6 +1157,17 @@ public int[] getSegments() {
 	return segments;
 }
 
+/**
+ * Returns the segments characters of the receiver.
+ *
+ * @return the segments characters
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @since 3.6
+ */
 public char[] getSegmentsChars () {
 	checkLayout();
 	return segmentsChars;
@@ -1261,6 +1272,17 @@ public int getWidth () {
 	return wrapWidth;
 }
 
+/**
+* Returns the receiver's wrap indent.
+*
+* @return the receiver's wrap indent
+* 
+* @exception SWTException <ul>
+*    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+* </ul>
+* 
+* @since 3.6
+*/
 public int getWrapIndent () {
 	checkLayout();
 	return wrapIndent;
@@ -1272,7 +1294,7 @@ public int getWrapIndent () {
  * <p>
  * This method gets the dispose state for the text layout.
  * When a text layout has been disposed, it is an error to
- * invoke any other method using the text layout.
+ * invoke any other method (except {@link #dispose()}) using the text layout.
  * </p>
  *
  * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise
@@ -1484,7 +1506,7 @@ public void setFont (Font font) {
 }
 
 /**
- * Sets the indent of the receiver. This indent it applied of the first line of 
+ * Sets the indent of the receiver. This indent is applied to the first line of 
  * each paragraph.  
  *
  * @param indent new indent
@@ -1493,6 +1515,8 @@ public void setFont (Font font) {
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
  * 
+ * @see #setWrapIndent(int)
+ * 
  * @since 3.2
  */
 public void setIndent (int indent) {
@@ -1564,7 +1588,7 @@ public void setSpacing (int spacing) {
 
 /**
  * Sets the offsets of the receiver's text segments. Text segments are used to
- * override the default behaviour of the bidirectional algorithm.
+ * override the default behavior of the bidirectional algorithm.
  * Bidirectional reordering can happen within a text segment but not 
  * between two adjacent segments.
  * <p>
@@ -1573,12 +1597,18 @@ public void setSpacing (int spacing) {
  * always be zero and the last one should always be equals to length of
  * the text.
  * </p>
+ * <p>
+ * When segments characters are set, the segments are the offsets where
+ * the characters are inserted in the text.
+ * <p> 
  * 
  * @param segments the text segments offset
  * 
  * @exception SWTException <ul>
  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
  * </ul>
+ * 
+ * @see #setSegmentsChars(char[])
  */
 public void setSegments(int[] segments) {
 	checkLayout();
@@ -1596,6 +1626,23 @@ public void setSegments(int[] segments) {
 	this.segments = segments;
 }
 
+/**
+ * Sets the characters to be used in the segments boundaries. The segments 
+ * are set by calling <code>setSegments(int[])</code>. The application can
+ * use this API to insert Unicode Control Characters in the text to control
+ * the display of the text and bidi reordering. The characters are not 
+ * accessible by any other API in <code>TextLayout</code>.
+ * 
+ * @param segmentsChars the segments characters 
+ *
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setSegments(int[])
+ * 
+ * @since 3.6
+ */
 public void setSegmentsChars(char[] segmentsChars) {
 	checkLayout();
 	if (this.segmentsChars == null && segmentsChars == null) return;
@@ -1776,6 +1823,20 @@ public void setWidth (int width) {
 	this.wrapWidth = width;
 }
 
+/**
+ * Sets the wrap indent of the receiver. This indent is applied to all lines
+ * in the paragraph except the first line.  
+ *
+ * @param wrapIndent new wrap indent
+ * 
+ * @exception SWTException <ul>
+ *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * 
+ * @see #setIndent(int)
+ * 
+ * @since 3.6
+ */
 public void setWrapIndent (int wrapIndent) {
 	checkLayout();
 	if (wrapIndent < 0) return;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
index fc37502654..abdf2bccaa 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
@@ -428,10 +428,10 @@ public Color getBackground (int columnIndex) {
 	return cellBackgrounds [columnIndex];
 }
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
index 6d2a6705e7..966b66986e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
@@ -843,10 +843,10 @@ public Color getBackground (int columnIndex) {
 	return cellBackgrounds [columnIndex];
 }
 /**
- * Returns a rectangle describing the receiver's size and location
- * relative to its parent.
+ * Returns a rectangle describing the size and location of the receiver's
+ * text relative to its parent.
  *
- * @return the receiver's bounding rectangle
+ * @return the bounding rectangle of the receiver's text
  *
  * @exception SWTException <ul>
  *    <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2495,8 +2495,6 @@ public void setFont (int columnIndex, Font font) {
  *
  * @param color the new color (or null)
  *
- * @since 2.0
- * 
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> 
  * </ul>