After Javadoc Bash for 3.4RC4

14 files changed, 315 insertions, 217 deletions

diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java
index 10347e5a00..f83e407e2b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/PrintDialog.java
@@ -23,6 +23,10 @@ import org.eclipse.swt.internal.carbon.OS;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -212,11 +216,11 @@ public PrinterData open() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -231,11 +235,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -250,7 +254,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -264,7 +268,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -278,7 +282,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -292,7 +296,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
index 318ea4984d..30fc8cbc9c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
@@ -34,6 +34,8 @@ import org.eclipse.swt.internal.carbon.*;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	PrinterData data;
@@ -204,28 +206,32 @@ public Printer(PrinterData data) {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -552,7 +558,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -573,8 +581,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/PrintDialog.java
index 756b1a2d7a..67c038e77a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/PrintDialog.java
@@ -23,6 +23,10 @@ import org.eclipse.swt.internal.cocoa.*;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -217,11 +221,11 @@ public PrinterData open() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -236,11 +240,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -255,7 +259,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -269,7 +273,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -283,7 +287,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -297,7 +301,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/Printer.java
index aa508f6bda..b49a536d51 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/cocoa/org/eclipse/swt/printing/Printer.java
@@ -33,6 +33,8 @@ import org.eclipse.swt.internal.cocoa.*;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	PrinterData data;
@@ -151,28 +153,32 @@ public Printer(PrinterData data) {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -487,7 +493,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -509,8 +517,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/PrintDialog.java
index 6421544e6a..9cc12f73a1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/PrintDialog.java
@@ -23,6 +23,10 @@ import org.eclipse.swt.widgets.*;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -113,11 +117,11 @@ public PrinterData getPrinterData() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -132,11 +136,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -151,7 +155,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -165,7 +169,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -179,7 +183,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -193,7 +197,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/Printer.java
index d66daead29..bff64fd295 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/emulated/org/eclipse/swt/printing/Printer.java
@@ -33,6 +33,8 @@ import org.eclipse.swt.graphics.*;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	PrinterData data;
@@ -253,7 +255,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -272,8 +276,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
@@ -290,28 +296,32 @@ public Rectangle getClientArea() {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java
index 88c9ae67c5..8908117447 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/PrintDialog.java
@@ -25,6 +25,10 @@ import org.eclipse.swt.widgets.*;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -150,11 +154,11 @@ protected void checkSubclass() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -169,11 +173,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -188,7 +192,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -202,7 +206,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -216,7 +220,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -230,7 +234,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java
index f1c83b4dd5..9bc3f90813 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/gtk/org/eclipse/swt/printing/Printer.java
@@ -37,6 +37,8 @@ import org.eclipse.swt.internal.cairo.Cairo;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	static PrinterData [] printerList;
@@ -603,7 +605,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -625,8 +629,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
@@ -646,28 +652,32 @@ public Rectangle getClientArea() {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java
index e58e1ae9d0..c6efd264cf 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/PrintDialog.java
@@ -23,6 +23,10 @@ import org.eclipse.swt.widgets.*;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -126,11 +130,11 @@ public PrinterData open() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -144,11 +148,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -162,7 +166,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -175,7 +179,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -188,7 +192,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -201,7 +205,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
index be692fe143..c6c5d29153 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
@@ -35,6 +35,8 @@ import org.eclipse.swt.internal.motif.*;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	PrinterData data;
@@ -557,7 +559,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -580,8 +584,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
@@ -600,28 +606,32 @@ public Rectangle getClientArea() {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java
index e58e1ae9d0..c6efd264cf 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/PrintDialog.java
@@ -23,6 +23,10 @@ import org.eclipse.swt.widgets.*;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -126,11 +130,11 @@ public PrinterData open() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -144,11 +148,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -162,7 +166,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -175,7 +179,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -188,7 +192,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -201,7 +205,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java
index db82d8ee96..42e33e8b58 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/photon/org/eclipse/swt/printing/Printer.java
@@ -33,6 +33,8 @@ import org.eclipse.swt.graphics.*;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	PrinterData data;
@@ -236,7 +238,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -254,8 +258,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
@@ -271,28 +277,32 @@ public Rectangle getClientArea() {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/PrintDialog.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/PrintDialog.java
index e58e1ae9d0..c6efd264cf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/PrintDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/PrintDialog.java
@@ -23,6 +23,10 @@ import org.eclipse.swt.widgets.*;
  * IMPORTANT: This class is intended to be subclassed <em>only</em>
  * within the SWT implementation.
  * </p>
+ *
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public class PrintDialog extends Dialog {
 	PrinterData printerData;
@@ -126,11 +130,11 @@ public PrinterData open() {
  * before pressing OK in the dialog. This will be one
  * of the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -144,11 +148,11 @@ public int getScope() {
  * setting when the dialog is opened. This can have one of
  * the following values:
  * <dl>
- * <dt><code>ALL_PAGES</code></dt>
+ * <dt><code>PrinterData.ALL_PAGES</code></dt>
  * <dd>Print all pages in the current document</dd>
- * <dt><code>PAGE_RANGE</code></dt>
+ * <dt><code>PrinterData.PAGE_RANGE</code></dt>
  * <dd>Print the range of pages specified by startPage and endPage</dd>
- * <dt><code>SELECTION</code></dt>
+ * <dt><code>PrinterData.SELECTION</code></dt>
  * <dd>Print the current selection</dd>
  * </dl>
  *
@@ -162,7 +166,7 @@ public void setScope(int scope) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the start page setting that the user selected
@@ -175,7 +179,7 @@ public int getStartPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param startPage the startPage setting when the dialog is opened
@@ -188,7 +192,7 @@ public void setStartPage(int startPage) {
  * before pressing OK in the dialog.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  *
  * @return the end page setting that the user selected
@@ -201,7 +205,7 @@ public int getEndPage() {
  * is opened.
  * <p>
  * This value can be from 1 to the maximum number of pages for the platform.
- * Note that it is only valid if the scope is <code>PAGE_RANGE</code>.
+ * Note that it is only valid if the scope is <code>PrinterData.PAGE_RANGE</code>.
  * </p>
  * 
  * @param endPage the end page setting when the dialog is opened
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/Printer.java
index db82d8ee96..42e33e8b58 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/wpf/org/eclipse/swt/printing/Printer.java
@@ -33,6 +33,8 @@ import org.eclipse.swt.graphics.*;
  *
  * @see PrinterData
  * @see PrintDialog
+ * @see <a href="http://www.eclipse.org/swt/snippets/#printing">Printing snippets</a>
+ * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  */
 public final class Printer extends Device {
 	PrinterData data;
@@ -236,7 +238,9 @@ public Point getDPI() {
 
 /**
  * Returns a rectangle describing the receiver's size and location.
- * For a printer, this is the size of a physical page, in pixels.
+ * <p>
+ * For a printer, this is the size of the physical page, in pixels.
+ * </p>
  *
  * @return the bounding rectangle
  *
@@ -254,8 +258,10 @@ public Rectangle getBounds() {
 /**
  * Returns a rectangle which describes the area of the
  * receiver which is capable of displaying data.
+ * <p>
  * For a printer, this is the size of the printable area
- * of a page, in pixels.
+ * of the page, in pixels.
+ * </p>
  * 
  * @return the client area
  *
@@ -271,28 +277,32 @@ public Rectangle getClientArea() {
 }
 
 /**
- * Given a desired <em>client area</em> for the receiver
- * (as described by the arguments), returns the bounding
- * rectangle which would be required to produce that client
- * area.
+ * Given a <em>client area</em> (as described by the arguments),
+ * returns a rectangle, relative to the client area's coordinates,
+ * that is the client area expanded by the printer's trim (or minimum margins).
  * <p>
- * In other words, it returns a rectangle such that, if the
- * receiver's bounds were set to that rectangle, the area
- * of the receiver which is capable of displaying data
- * (that is, not covered by the "trimmings") would be the
- * rectangle described by the arguments (relative to the
- * receiver's parent).
- * </p><p>
- * Note that there is no setBounds for a printer. This method
- * is usually used by passing in the client area (the 'printable
- * area') of the printer. It can also be useful to pass in 0, 0, 0, 0.
+ * Most printers have a minimum margin on each edge of the paper where the
+ * printer device is unable to print.  This margin is known as the "trim."
+ * This method can be used to calculate the printer's minimum margins
+ * by passing in a client area of 0, 0, 0, 0 and then using the resulting
+ * x and y coordinates (which will be <= 0) to determine the minimum margins
+ * for the top and left edges of the paper, and the resulting width and height
+ * (offset by the resulting x and y) to determine the minimum margins for the
+ * bottom and right edges of the paper, as follows:
+ * <ul>
+ * 		<li>The left trim width is -x pixels</li>
+ * 		<li>The top trim height is -y pixels</li>
+ * 		<li>The right trim width is (x + width) pixels</li>
+ * 		<li>The bottom trim height is (y + height) pixels</li>
+ * </ul>
  * </p>
  * 
- * @param x the desired x coordinate of the client area
- * @param y the desired y coordinate of the client area
- * @param width the desired width of the client area
- * @param height the desired height of the client area
- * @return the required bounds to produce the given client area
+ * @param x the x coordinate of the client area
+ * @param y the y coordinate of the client area
+ * @param width the width of the client area
+ * @param height the height of the client area
+ * @return a rectangle, relative to the client area's coordinates, that is
+ * 		the client area expanded by the printer's trim (or minimum margins)
  *
  * @exception SWTException <ul>
  *    <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>