Bug 552065: add more javadoc to the abstract classes
- usually uses the first sentence of the javadoc of the actual method of
the widget
Change-Id: I96682e5b6d8b5c38ee0d72b8e86864d188af2dea
Signed-off-by: Marcus Hoepfner <marcus.hoepfner@sap.com>
diff --git a/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractCompositeFactory.java b/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractCompositeFactory.java
index d5542e0..b83a7bf 100644
--- a/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractCompositeFactory.java
+++ b/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractCompositeFactory.java
@@ -41,10 +41,13 @@
}
/**
- * Sets the layout.
+ * Sets the layout which is associated with the receiver to be the argument
+ * which may be null.
*
- * @param layout
+ * @param layout the receiver's layout or null
* @return this
+ *
+ * @see Composite#setLayout(Layout)
*/
public F layout(Layout layout) {
addProperty(control -> control.setLayout(layout));
diff --git a/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java b/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java
index 4c64a18..6f85790 100644
--- a/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java
+++ b/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java
@@ -46,10 +46,20 @@
}
/**
- * Sets the tool tip.
+ * Sets the receiver's tool tip text to the argument, which may be null
+ * indicating that the default tool tip for the control will be shown. For a
+ * control that has a default tool tip, such as the Tree control on Windows,
+ * setting the tool tip text to an empty string replaces the default, causing no
+ * tool tip text to be shown.
*
- * @param tooltipText
+ * The mnemonic indicator (character '&') is not displayed in a tool tip. To
+ * display a single '&' in the tool tip, the character '&' can be escaped by
+ * doubling it in the string.
+ *
+ * @param tooltipText the tool tip text
* @return this
+ *
+ * @see Control#setToolTipText(String)
*/
public F tooltip(String tooltipText) {
addProperty(c -> c.setToolTipText(tooltipText));
@@ -57,10 +67,14 @@
}
/**
- * Sets the enabled state.
+ * Enables the receiver if the argument is true, and disables it otherwise. A
+ * disabled control is typically not selectable from the user interface and
+ * draws with an inactive or "grayed" look.
*
- * @param enabled
+ * @param enabled the enabled state
* @return this
+ *
+ * @see Control#setEnabled(boolean)
*/
public F enabled(boolean enabled) {
addProperty(c -> c.setEnabled(enabled));
@@ -68,9 +82,10 @@
}
/**
- * Sets a {@link Supplier}, which should always create a new instance of the
- * layoutData in order to make this factory reusable, because each and every
- * control needs its own unique layoutData.
+ * Sets a {@link Supplier} for the creation of layout data associated with the
+ * receiver. The supplier should always create a new instance of the layoutData
+ * in order to make this factory reusable, because each and every control needs
+ * its own unique layoutData.
*
* <pre>
* GridDataFactory gridDataFactory = GridDataFactory.fillDefaults().grab(true, false);
@@ -84,8 +99,11 @@
* </pre>
*
* @param layoutDataSupplier {@link Supplier} creating a new layout data
- * instance
+ * instance on every call
* @return this
+ *
+ * @see Control#setLayoutData(Object)
+ * @see #layoutData(Object)
*/
public F supplyLayoutData(Supplier<?> layoutDataSupplier) {
addProperty(c -> c.setLayoutData(layoutDataSupplier.get()));
@@ -93,15 +111,24 @@
}
/**
- * Sets a layout object, which is used for the setLayout method of the control.
+ * Sets the layout data associated with the receiver to the argument.
+ *
+ * Sufficient for one time usage of this factory.
*
* <pre>
* GridData gd = new GridData(GridData.FILL_BOTH);
* ButtonFactory.newButton(SWT.PUSH).layoutData(gd);
* </pre>
*
- * @param layoutData
+ * <p>
+ * In case this factory should be reused several time consider the usage of
+ * {@link #supplyLayoutData(Supplier)}.
+ * </p>
+ *
+ * @param layoutData the layout data for the receiver.
* @return this
+ *
+ * @see Control#setLayoutData(Object)
*/
public F layoutData(Object layoutData) {
addProperty(c -> c.setLayoutData(layoutData));
@@ -109,11 +136,14 @@
}
/**
- * Sets the font.
+ * Sets the font that the receiver will use to paint textual information to the
+ * font specified by the argument, or to the default font for that kind of
+ * control if the argument is null.
*
- * @param font
- *
+ * @param font the font
* @return this
+ *
+ * @see Control#setFont(Font)
*/
public F font(Font font) {
addProperty(c -> c.setFont(font));
@@ -121,10 +151,13 @@
}
/**
- * Sets the foreground color.
+ * Sets the receiver's foreground color to the color specified by the argument,
+ * or to the default system color for the control if the argument is null.
*
- * @param color
+ * @param color the color
* @return this
+ *
+ * @see Control#setForeground(Color)
*/
public F foreground(Color color) {
addProperty(c -> c.setForeground(color));
@@ -132,10 +165,13 @@
}
/**
- * Sets the background color.
+ * Sets the receiver's background color to the color specified by the argument,
+ * or to the default system color for the control if the argument is null.
*
- * @param color
+ * @param color the color
* @return this
+ *
+ * @see Control#setBackground(Color)
*/
public F background(Color color) {
addProperty(c -> c.setBackground(color));
@@ -143,10 +179,13 @@
}
/**
- * Sets the orientation
+ * Sets the orientation of the receiver, which must be one of the constants
+ * SWT.LEFT_TO_RIGHT or SWT.RIGHT_TO_LEFT.
*
- * @param orientation
+ * @param orientation the orientation style
* @return this
+ *
+ * @see Control#setOrientation(int)
*/
public F orientation(int orientation) {
addProperty(t -> t.setOrientation(orientation));
diff --git a/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractItemFactory.java b/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractItemFactory.java
index c043b7c..53166d7 100644
--- a/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractItemFactory.java
+++ b/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractItemFactory.java
@@ -43,10 +43,13 @@
}
/**
- * Sets the image.
+ * Sets the receiver's image to the argument, which may be null indicating that
+ * no image should be displayed.
*
- * @param image
+ * @param image the image to display on the receiver
* @return this
+ *
+ * @see Item#setImage(Image)
*/
public F image(Image image) {
addProperty(i -> i.setImage(image));
@@ -54,10 +57,16 @@
}
/**
- * Sets the text.
+ * Sets the receiver's text.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used in the string, then
+ * the behavior is platform dependent.
+ * </p>
*
- * @param text
+ * @param text the text
* @return this
+ *
+ * @see Item#setText(String)
*/
public F text(String text) {
addProperty(i -> i.setText(text));
