doc: bug 84911

4 files changed, 41 insertions, 16 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWT.java b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWT.java
index 6f5f8e6677..1479f56410 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWT.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/SWT.java
@@ -810,6 +810,7 @@ public class SWT {
 	 * orientation of their parent.  To override this behavior and
 	 * force an orientation for a child, explicitly set the orientation
 	 * of the child when that child is created.
+	 * <br>Note that this is a <em>HINT</em>.
 	 * </p>
 	 * <p><b>Used By:</b><ul>
 	 * <li><code>Control</code></li>
@@ -829,6 +830,7 @@ public class SWT {
 	 * orientation of their parent.  To override this behavior and
 	 * force an orientation for a child, explicitly set the orientation
 	 * of the child when that child is created.
+	 * <br>Note that this is a <em>HINT</em>.
 	 * </p>
 	 * <p><b>Used By:</b><ul>
 	 * <li><code>Control</code></li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/widgets/Dialog.java b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/widgets/Dialog.java
index 9e622b851b..72c431cc61 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/widgets/Dialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/widgets/Dialog.java
@@ -65,7 +65,11 @@ import org.eclipse.swt.*;
  * <dt><b>Events:</b></dt>
  * <dd>(none)</dd>
  * </dl>
- *
+ * <p>
+ * Note: Only one of the styles APPLICATION_MODAL, PRIMARY_MODAL, and SYSTEM_MODAL 
+ * may be specified.
+ * </p>
+ * 
  * @see Shell
  */
 
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/FileDialog.java
index e4e37b165f..c72390c363 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/FileDialog.java
@@ -84,7 +84,7 @@ public FileDialog (Shell parent, int style) {
 
 /**
  * Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path.
  * 
  * @return the relative path of the file
  */
@@ -113,10 +113,10 @@ public String [] getFilterExtensions () {
 }
 
 /**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
  *
- * @return the file name filter
+ * @return the list of filter names
  */
 public String [] getFilterNames () {
 	return filterNames;
@@ -369,6 +369,10 @@ public void setFileName (String string) {
  * Set the file extensions which the dialog will
  * use to filter the files it shows to the argument,
  * which may be null.
+ * <p>
+ * Each string is of the form "*.extension", where
+ * "*.*" matches all files.
+ * </p>
  *
  * @param extensions the file extension filter
  */
@@ -377,11 +381,11 @@ public void setFilterExtensions (String [] extensions) {
 }
 
 /**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
  *
- * @param names the file name filter
+ * @param names the list of filter names
  */
 public void setFilterNames (String [] names) {
 	filterNames = names;
@@ -391,7 +395,14 @@ public void setFilterNames (String [] names) {
  * Sets the directory path that the dialog will use
  * to the argument, which may be null. File names in this
  * path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
  *
  * @param string the directory path
  * 
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 4b294d3a3b..d53ce360de 100755
--- 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
@@ -1185,11 +1185,15 @@ public void setEnabled (boolean enabled) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that some platforms may not support relocation of
+ * popup menus in which case this will be ignored.
  * </p>
  *
  * @param x the new x coordinate for the receiver
@@ -1209,11 +1213,15 @@ public void setLocation (int x, int y) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
  * <p>
- * Note:  This is different from most widgets where the
+ * Note that this is different from most widgets where the
  * location of the widget is relative to the parent.
+ * </p><p>
+ * Note that some platforms may not support relocation of
+ * popup menus in which case this will be ignored.
  * </p>
  *
  * @param location the new location for the receiver