Author: rwhitcomb Date: Wed Nov 4 01:30:04 2015 New Revision: 1712454 URL: http://svn.apache.org/viewvc?rev=1712454&view=rev Log: PIVOT-976: More Javadoc fixes for the warnings from Java 8.
Continuing on down the list, basically. Almost all of these are @param descriptions, although some are @return. Also continued a little bit using the Utils.checkNull method in some places in the components that were update. This is a bit off-track for Javadoc, but there is no separate JIRA for these changes, so .... Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java Wed Nov 4 01:30:04 2015 @@ -20,6 +20,7 @@ import java.awt.Color; import org.apache.pivot.json.JSON; import org.apache.pivot.util.ListenerList; +import org.apache.pivot.util.Utils; /** * Component that allows the user to select a color. @@ -32,14 +33,17 @@ public class ColorChooser extends Contai /** * Converts a context value to a color. * - * @param value + * @param value The value returned from the bound object. + * @return The value converted to a {@link Color}. */ public Color toColor(Object value); /** * Converts a color to a context value. * - * @param color + * @param color The color value selected in this component. + * @return The color value converted to a format suitable for + * persistence in the bound object. */ public Object valueOf(Color color); } @@ -103,7 +107,7 @@ public class ColorChooser extends Contai } /** - * Gets the currently selected color, or <tt>null</tt> if no color is + * @return The currently selected color, or <tt>null</tt> if no color is * selected. */ public Color getSelectedColor() { @@ -133,15 +137,13 @@ public class ColorChooser extends Contai * selection. */ public void setSelectedColor(String selectedColor) { - if (selectedColor == null) { - throw new IllegalArgumentException("selectedColor is null."); - } + Utils.checkNull(selectedColor, "selectedColor"); setSelectedColor(Color.decode(selectedColor)); } /** - * Gets the data binding key that is set on this color chooser. + * @return The data binding key that is set on this color chooser. */ public String getSelectedColorKey() { return selectedColorKey; @@ -149,6 +151,8 @@ public class ColorChooser extends Contai /** * Sets this color chooser's data binding key. + * + * @param selectedColorKey The binding key for the selected color. */ public void setSelectedColorKey(String selectedColorKey) { String previousSelectedColorKey = this.selectedColorKey; @@ -164,9 +168,7 @@ public class ColorChooser extends Contai } public void setSelectedColorBindType(BindType selectedColorBindType) { - if (selectedColorBindType == null) { - throw new IllegalArgumentException(); - } + Utils.checkNull(selectedColorBindType, "selectedColorBindType"); BindType previousSelectedColorBindType = this.selectedColorBindType; @@ -240,14 +242,14 @@ public class ColorChooser extends Contai } /** - * Returns the color chooser selection listener list. + * @return The color chooser selection listener list. */ public ListenerList<ColorChooserSelectionListener> getColorChooserSelectionListeners() { return colorChooserSelectionListeners; } /** - * Returns the color chooser binding listener list. + * @return The color chooser binding listener list. */ public ListenerList<ColorChooserBindingListener> getColorChooserBindingListeners() { return colorChooserBindingListeners; Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java Wed Nov 4 01:30:04 2015 @@ -20,6 +20,7 @@ import java.awt.Color; import org.apache.pivot.json.JSON; import org.apache.pivot.util.ListenerList; +import org.apache.pivot.util.Utils; import org.apache.pivot.wtk.content.ListButtonColorItemRenderer; /** @@ -118,7 +119,7 @@ public class ColorChooserButton extends } /** - * @return the popup window associated with this components skin + * @return The popup window associated with this component's skin. */ public Window getListPopup() { return ((ColorChooserButton.Skin) getSkin()).getColorChooserPopup(); @@ -134,8 +135,6 @@ public class ColorChooserButton extends } /** - * Returns the currently selected color. - * * @return The currently selected color, or <tt>null</tt> if nothing is * selected. */ @@ -163,17 +162,16 @@ public class ColorChooserButton extends * Sets the selected color. * * @param selectedColor A string representing a color. + * @throws IllegalArgumentException if the string is {@code null}. */ public final void setSelectedColor(String selectedColor) { - if (selectedColor == null) { - throw new IllegalArgumentException("selectedColor is null."); - } + Utils.checkNull(selectedColor, "selectedColor"); setSelectedColor(Color.decode(selectedColor)); } /** - * Gets the data binding key that is set on this color chooser button. + * @return The data binding key that is set on this color chooser button. */ public String getSelectedColorKey() { return selectedColorKey; @@ -181,6 +179,8 @@ public class ColorChooserButton extends /** * Sets this color chooser button's data binding key. + * + * @param selectedColorKey The binding key for the selected color. */ public void setSelectedColorKey(String selectedColorKey) { String previousSelectedColorKey = this.selectedColorKey; @@ -197,9 +197,7 @@ public class ColorChooserButton extends } public void setSelectedColorBindType(BindType selectedColorBindType) { - if (selectedColorBindType == null) { - throw new IllegalArgumentException(); - } + Utils.checkNull(selectedColorBindType, "selectedColorBindType"); BindType previousSelectedColorBindType = this.selectedColorBindType; @@ -273,14 +271,14 @@ public class ColorChooserButton extends } /** - * Returns the color chooser button selection listener list. + * @return The color chooser button selection listener list. */ public ListenerList<ColorChooserButtonSelectionListener> getColorChooserButtonSelectionListeners() { return colorChooserButtonSelectionListeners; } /** - * Returns the color chooser button binding listener list. + * @return The color chooser button binding listener list. */ public ListenerList<ColorChooserButtonBindingListener> getColorChooserButtonBindingListeners() { return colorChooserButtonBindingListeners; Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java Wed Nov 4 01:30:04 2015 @@ -23,9 +23,9 @@ public interface DragSource { /** * Called by the framework to initiate a drag operation. * - * @param component - * @param x - * @param y + * @param component The component to drag from. + * @param x The X-position of the mouse at the beginning of the drag. + * @param y The Y-position of the mouse. * @return <tt>true</tt> to accept the drag; <tt>false</tt> to reject it. */ public boolean beginDrag(Component component, int x, int y); @@ -33,8 +33,8 @@ public interface DragSource { /** * Called by the framework to terminate a drag operation. * - * @param component - * @param dropAction + * @param component The drag component. + * @param dropAction Which operation to perform at the end of the drag. */ public void endDrag(Component component, DropAction dropAction); @@ -47,7 +47,7 @@ public interface DragSource { public boolean isNative(); /** - * Returns the drag content. + * @return The drag content. */ public LocalManifest getContent(); Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java Wed Nov 4 01:30:04 2015 @@ -23,6 +23,7 @@ import org.apache.pivot.collections.Arra import org.apache.pivot.collections.Sequence; import org.apache.pivot.util.ImmutableIterator; import org.apache.pivot.util.ListenerList; +import org.apache.pivot.util.Utils; /** * Container that arranges components in a two-dimensional grid, where every @@ -67,9 +68,7 @@ public class GridPane extends Container @Override public void insert(Component component, int index) { - if (component == null) { - throw new IllegalArgumentException("Component is null."); - } + Utils.checkNull(component, "component"); if (component.getParent() != null) { throw new IllegalArgumentException("Component already has a parent."); @@ -88,9 +87,7 @@ public class GridPane extends Container Component previousComponent = cells.get(index); if (component != previousComponent) { - if (component == null) { - throw new IllegalArgumentException("Component is null."); - } + Utils.checkNull(component, "Component"); if (component.getParent() != null) { throw new IllegalArgumentException("Component already has a parent."); @@ -188,12 +185,10 @@ public class GridPane extends Container @Override public void insert(Row row, int index) { - if (row == null) { - throw new IllegalArgumentException("row is null."); - } + Utils.checkNull(row, "Row"); if (row.getGridPane() != null) { - throw new IllegalArgumentException("row is already in use by another grid pane."); + throw new IllegalArgumentException("Row is already in use by another grid pane."); } rows.insert(row, index); @@ -336,7 +331,7 @@ public class GridPane extends Container /** * Creates a new grid pane with the specified column count. * - * @param columnCount + * @param columnCount Number of columns for this grid. */ public GridPane(int columnCount) { if (columnCount < 0) { @@ -359,7 +354,7 @@ public class GridPane extends Container } /** - * Returns the number of columns in the grid pane. + * @return The number of columns in the grid pane. */ public int getColumnCount() { return columnCount; @@ -368,7 +363,7 @@ public class GridPane extends Container /** * Sets the number of columns in the grid pane. * - * @param columnCount + * @param columnCount The new number of columns in the grid. */ public void setColumnCount(int columnCount) { int previousColumnCount = this.columnCount; @@ -380,9 +375,7 @@ public class GridPane extends Container } /** - * Returns the grid pane row sequence. - * - * @return The grid pane row sequence + * @return The grid pane row sequence. */ public RowSequence getRows() { return rowSequence; @@ -404,6 +397,7 @@ public class GridPane extends Container * Returns the bounds of a given row. * * @param row The row index. + * @return The bounds for the given row. */ public Bounds getRowBounds(int row) { GridPane.Skin gridPaneSkin = (GridPane.Skin) getSkin(); @@ -426,6 +420,7 @@ public class GridPane extends Container * Returns the bounds of a given column. * * @param column The column index. + * @return The bounds of the given column. */ public Bounds getColumnBounds(int column) { GridPane.Skin gridPaneSkin = (GridPane.Skin) getSkin(); @@ -435,10 +430,10 @@ public class GridPane extends Container /** * Gets the component at the specified cell in this grid pane. * - * @param rowIndex The row index of the cell - * @param columnIndex The column index of the cell + * @param rowIndex The row index of the cell. + * @param columnIndex The column index of the cell. * @return The component in the specified cell, or <tt>null</tt> if the cell - * is empty + * is empty. */ public Component getCellComponent(int rowIndex, int columnIndex) { Row row = rows.get(rowIndex); @@ -456,9 +451,9 @@ public class GridPane extends Container * Overrides the base method to check whether or not a cell component is * being removed, and fires the appropriate event in that case. * - * @param index The index at which components were removed - * @param count The number of components removed - * @return The sequence of components that were removed + * @param index The index at which components were removed. + * @param count The number of components removed. + * @return The sequence of components that were removed. */ @Override public Sequence<Component> remove(int index, int count) { @@ -477,7 +472,7 @@ public class GridPane extends Container } /** - * Returns the grid pane listener list. + * @return The grid pane listener list. */ public ListenerList<GridPaneListener> getGridPaneListeners() { return gridPaneListeners; Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java Wed Nov 4 01:30:04 2015 @@ -141,6 +141,7 @@ public class HyperlinkButton extends Lin /** * Access the {@link URI} which is the target of this hyperlink. + * @return The target for this hyperlink. */ public URI getUri() { return action == null ? null : action.getUri(); Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java Wed Nov 4 01:30:04 2015 @@ -24,6 +24,7 @@ import org.apache.pivot.collections.Arra import org.apache.pivot.collections.HashMap; import org.apache.pivot.json.JSON; import org.apache.pivot.util.ListenerList; +import org.apache.pivot.util.Utils; import org.apache.pivot.util.concurrent.Task; import org.apache.pivot.util.concurrent.TaskListener; import org.apache.pivot.wtk.media.Image; @@ -45,7 +46,7 @@ public class ImageView extends Component } /** - * Returns the load type supported by this mapping. + * @return The load type supported by this mapping. */ public Type getType(); @@ -53,7 +54,8 @@ public class ImageView extends Component * Converts a value from the bind context to an image representation * during a {@link Component#load(Object)} operation. * - * @param value + * @param value The value returned from the bound object. + * @return The image converted from the bound value. */ public Image toImage(Object value); @@ -61,7 +63,8 @@ public class ImageView extends Component * Converts a value from the bind context to an image location during a * {@link Component#load(Object)} operation. * - * @param value + * @param value The value returned from the bound object. + * @return The value converted to an image URL. */ public URL toImageURL(Object value); @@ -69,15 +72,22 @@ public class ImageView extends Component * Converts a value from the bind context to an image resource name * during a {@link Component#load(Object)} operation. * - * @param value + * @param value The value returned from the bound object. + * @return The value converted to an image name. */ public String toImageName(Object value); /** - * Converts a text string to a value to be stored in the bind context + * Converts an image to a value to be stored in the bind context * during a {@link Component#store(Object)} operation. + * <p> Note: if the bind type is {@link Type#URL} or {@link Type#NAME} then + * this will likely entail also persisting the image itself + * somewhere else and returning the name/location of the stored + * image. * - * @param image + * @param image The image currently stored in the image view. + * @return The image converted to a value suitable for persistence + * in the bound object. */ public Object valueOf(Image image); } @@ -188,9 +198,7 @@ public class ImageView extends Component * @param imageURL The location of the image to set. */ public final void setImage(final URL imageURL) { - if (imageURL == null) { - throw new IllegalArgumentException("imageURL is null."); - } + Utils.checkNull(imageURL, "imageURL"); Image imageLocal = (Image) ApplicationContext.getResourceCache().get(imageURL); @@ -253,9 +261,7 @@ public class ImageView extends Component * @see #setImage(URL) */ public final void setImage(String imageName) { - if (imageName == null) { - throw new IllegalArgumentException("imageName is null."); - } + Utils.checkNull(imageName, "imageName"); ClassLoader classLoader = Thread.currentThread().getContextClassLoader(); URL url = classLoader.getResource(imageName.substring(1)); @@ -317,9 +323,7 @@ public class ImageView extends Component } public void setImageBindType(BindType imageBindType) { - if (imageBindType == null) { - throw new IllegalArgumentException(); - } + Utils.checkNull(imageBindType, "imageBindType"); BindType previousImageBindType = this.imageBindType; @@ -400,14 +404,14 @@ public class ImageView extends Component } /** - * Returns the image view listener list. + * @return The image view listener list. */ public ListenerList<ImageViewListener> getImageViewListeners() { return imageViewListeners; } /** - * Returns the image view binding listener list. + * @return The image view binding listener list. */ public ListenerList<ImageViewBindingListener> getImageViewBindingListeners() { return imageViewBindingListeners; Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java Wed Nov 4 01:30:04 2015 @@ -44,24 +44,24 @@ public interface ImageViewBindingListene /** * Called when an image view's image key has changed. * - * @param imageView - * @param previousImageKey + * @param imageView The image view whose binding has changed. + * @param previousImageKey The previous binding key for the image. */ public void imageKeyChanged(ImageView imageView, String previousImageKey); /** * Called when a image views's image bind type has changed. * - * @param imageView - * @param previousImageBindType + * @param imageView The image view whose binding has changed. + * @param previousImageBindType The previous bind type for the image. */ public void imageBindTypeChanged(ImageView imageView, BindType previousImageBindType); /** - * Called when an image view's text bind mapping has changed. + * Called when an image view's bind mapping has changed. * - * @param imageView - * @param previousImageBindMapping + * @param imageView The image view whose binding has changed. + * @param previousImageBindMapping The previous bind mapping for the image. */ public void imageBindMappingChanged(ImageView imageView, ImageView.ImageBindMapping previousImageBindMapping); Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java Wed Nov 4 01:30:04 2015 @@ -40,15 +40,15 @@ public interface ImageViewListener { /** * Called when an image view's image has changed. * - * @param imageView - * @param previousImage + * @param imageView The image view whose image has changed. + * @param previousImage The previous image associated with this image view. */ public void imageChanged(ImageView imageView, Image previousImage); /** * Called when an image view's asynchronous flag has changed. * - * @param imageView + * @param imageView The image view whose asynchronous flag has changed. */ public void asynchronousChanged(ImageView imageView); } Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java Wed Nov 4 01:30:04 2015 @@ -20,6 +20,7 @@ import java.awt.event.InputEvent; import java.awt.event.KeyEvent; import java.lang.reflect.Field; import java.util.Locale; +import org.apache.pivot.util.Utils; /** * Class representing the system keyboard. @@ -116,9 +117,7 @@ public final class Keyboard { } public static KeyStroke decode(String value) { - if (value == null) { - throw new IllegalArgumentException("value is null."); - } + Utils.checkNull(value, "value"); int keyCode = KeyCode.UNDEFINED; int modifiersLocal = 0x00; @@ -261,7 +260,7 @@ public final class Keyboard { private static int modifiers = 0; /** - * Returns a bitfield representing the keyboard modifiers that are currently + * @return A bitfield representing the keyboard modifiers that are currently * pressed. */ public static int getModifiers() { @@ -275,7 +274,7 @@ public final class Keyboard { /** * Tests the pressed state of a modifier. * - * @param modifier + * @param modifier The modifier to test. * @return <tt>true</tt> if the modifier is pressed; <tt>false</tt>, * otherwise. */ Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java Wed Nov 4 01:30:04 2015 @@ -18,6 +18,7 @@ package org.apache.pivot.wtk; import org.apache.pivot.json.JSON; import org.apache.pivot.util.ListenerList; +import org.apache.pivot.util.Utils; /** * Component that displays a string of text. @@ -31,7 +32,8 @@ public class Label extends Component { * Converts a value from the bind context to a text representation * during a {@link Component#load(Object)} operation. * - * @param value + * @param value The bound value from the component. + * @return The value converted to a {@link String} suitable for the label text. */ public String toString(Object value); @@ -39,7 +41,9 @@ public class Label extends Component { * Converts a text string to a value to be stored in the bind context * during a {@link Component#store(Object)} operation. * - * @param text + * @param text The label text to be converted. + * @return The text value converted to a value suitable for persistence + * in the bound object. */ public Object valueOf(String text); } @@ -108,9 +112,7 @@ public class Label extends Component { } /** - * Returns the label's text. - * - * @return The text. + * @return The label's text. */ public String getText() { return text; @@ -119,12 +121,12 @@ public class Label extends Component { /** * Set the text of the Label. * - * @param text The text to set, must be not null. + * @param text The text to set, must be not {@code null}. + * @throws IllegalArgumentException if the text is {@code null} or if + * the text length exceeds the allowed maximum. */ public void setText(String text) { - if (text == null) { - throw new IllegalArgumentException(); - } + Utils.checkNull(text, "text"); if (text.length() > maximumLength) { throw new IllegalArgumentException("Text length is greater than maximum length."); @@ -142,7 +144,7 @@ public class Label extends Component { * null (to avoid the setText throw an IllegalArgumentException). This is * useful to be called by code. * - * @param text The text to set + * @param text The text to set (if {@code null} will set an empty string {@code ""}). * @see #setText */ public void setTextOrEmpty(String text) { @@ -159,8 +161,6 @@ public class Label extends Component { } /** - * Returns the maximum length of the label text. - * * @return The maximum length of the label text. */ public int getMaximumLength() { @@ -171,6 +171,7 @@ public class Label extends Component { * Sets the maximum length of the label text. * * @param maximumLength The maximum length of the label text. + * @throws IllegalArgumentException if the length given is negative. */ public void setMaximumLength(int maximumLength) { if (maximumLength < 0) { @@ -210,9 +211,7 @@ public class Label extends Component { } public void setTextBindType(BindType textBindType) { - if (textBindType == null) { - throw new IllegalArgumentException(); - } + Utils.checkNull(textBindType, "textBindType"); BindType previousTextBindType = this.textBindType; Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java Wed Nov 4 01:30:04 2015 @@ -44,24 +44,24 @@ public interface LabelBindingListener { /** * Called when a label's text key has changed. * - * @param label - * @param previousTextKey + * @param label The label whose binding has changed. + * @param previousTextKey The previous binding key for the label text. */ public void textKeyChanged(Label label, String previousTextKey); /** * Called when a label's text bind type has changed. * - * @param label - * @param previousTextBindType + * @param label The label whose binding has changed. + * @param previousTextBindType The previous bind type for the label text. */ public void textBindTypeChanged(Label label, BindType previousTextBindType); /** * Called when a label's text bind mapping has changed. * - * @param label - * @param previousTextBindMapping + * @param label The label whose binding has changed. + * @param previousTextBindMapping The previous bind mapping for the label text. */ public void textBindMappingChanged(Label label, Label.TextBindMapping previousTextBindMapping); } Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java Wed Nov 4 01:30:04 2015 @@ -39,16 +39,16 @@ public interface LabelListener { /** * Called when a label's text has changed. * - * @param label - * @param previousText + * @param label The label that has changed. + * @param previousText The previous text associated with the label. */ public void textChanged(Label label, String previousText); /** * Called when a label text maximum length has changed. * - * @param label - * @param previousMaximumLength + * @param label The label that has changed. + * @param previousMaximumLength The previous maximum text length for the label. */ public void maximumLengthChanged(Label label, int previousMaximumLength); Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java Wed Nov 4 01:30:04 2015 @@ -30,6 +30,7 @@ import org.apache.pivot.json.JSONSeriali import org.apache.pivot.serialization.SerializationException; import org.apache.pivot.util.Filter; import org.apache.pivot.util.ListenerList; +import org.apache.pivot.util.Utils; import org.apache.pivot.wtk.ListView.ListDataBindMapping; import org.apache.pivot.wtk.content.ListButtonDataRenderer; import org.apache.pivot.wtk.content.ListViewItemRenderer; @@ -301,7 +302,7 @@ public class ListButton extends Button { /** * Creates a list button with the given button data and an empty list. * - * @param buttonData + * @param buttonData The button data (that is text and/or icon) for the list button. */ public ListButton(Object buttonData) { this(buttonData, new ArrayList<>()); @@ -310,7 +311,7 @@ public class ListButton extends Button { /** * Creates a list button with no button data and the given list data. * - * @param listData + * @param listData The initial list data for the list button. */ public ListButton(List<?> listData) { this(null, listData); @@ -379,9 +380,7 @@ public class ListButton extends Button { */ @SuppressWarnings("unchecked") public void setListData(List<?> listData) { - if (listData == null) { - throw new IllegalArgumentException("listData is null."); - } + Utils.checkNull(listData, "listData"); List<?> previousListData = this.listData; @@ -413,11 +412,11 @@ public class ListButton extends Button { * * @param listData The list data to be presented by the list button as a * JSON array. + * @throws IllegalArgumentException if the data string is {@code null} or + * cannot be propertly parsed into a list. */ public final void setListData(String listData) { - if (listData == null) { - throw new IllegalArgumentException("listData is null."); - } + Utils.checkNull(listData, "listData"); try { setListData(JSONSerializer.parseList(listData)); @@ -431,11 +430,11 @@ public class ListButton extends Button { * * @param listData A URL referring to a JSON file containing the data to be * presented by the list button. + * @throws IllegalArgumentException if the URL is {@code null} or + * the URL data stream cannot be propertly parsed into a list. */ public void setListData(URL listData) { - if (listData == null) { - throw new IllegalArgumentException("listData is null."); - } + Utils.checkNull(listData, "listData"); JSONSerializer jsonSerializer = new JSONSerializer(); @@ -474,7 +473,7 @@ public class ListButton extends Button { } /** - * Returns the list button's repeatable flag. + * @return The list button's repeatable flag. */ public boolean isRepeatable() { return repeatable; @@ -483,7 +482,8 @@ public class ListButton extends Button { /** * Sets the list button's repeatable flag. * - * @param repeatable + * @param repeatable Whether this list button's action is repeatable + * (that is, the action can be triggered even if the selection is unchanged). */ public void setRepeatable(boolean repeatable) { if (this.repeatable != repeatable) { @@ -581,7 +581,7 @@ public class ListButton extends Button { } /** - * Returns the list size. + * @return The list size. */ public int getListSize() { return listSize; @@ -591,7 +591,8 @@ public class ListButton extends Button { * Sets the list size. If the number of items in the list exceeds this * value, the list will scroll. * - * @param listSize + * @param listSize The number of visible items in the list. + * @throws IllegalArgumentException if the specified size is negative. */ public void setListSize(int listSize) { if (listSize < -1) { @@ -787,28 +788,28 @@ public class ListButton extends Button { } /** - * Returns the list button listener list. + * @return The list button listener list. */ public ListenerList<ListButtonListener> getListButtonListeners() { return listButtonListeners; } /** - * Returns the list button item listener list. + * @return The list button item listener list. */ public ListenerList<ListButtonItemListener> getListButtonItemListeners() { return listButtonItemListeners; } /** - * Returns the list button selection listener list. + * @return The list button selection listener list. */ public ListenerList<ListButtonSelectionListener> getListButtonSelectionListeners() { return listButtonSelectionListeners; } /** - * Returns the list button binding listener list. + * @return The list button binding listener list. */ public ListenerList<ListButtonBindingListener> getListButtonBindingListeners() { return listButtonBindingListeners; Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java Wed Nov 4 01:30:04 2015 @@ -61,24 +61,24 @@ public interface ListButtonBindingListen /** * Called when a list button's list data key has changed. * - * @param listButton - * @param previousListDataKey + * @param listButton The list button that has changed. + * @param previousListDataKey The previous binding key for the list data. */ public void listDataKeyChanged(ListButton listButton, String previousListDataKey); /** * Called when a list button's list data bind type has changed. * - * @param listButton - * @param previousListDataBindType + * @param listButton The list button that has changed. + * @param previousListDataBindType The previous bind type for the list data. */ public void listDataBindTypeChanged(ListButton listButton, BindType previousListDataBindType); /** * Called when a list button's list data bind mapping has changed. * - * @param listButton - * @param previousListDataBindMapping + * @param listButton The list button that has changed. + * @param previousListDataBindMapping The previous bind mapping for the list data. */ public void listDataBindMappingChanged(ListButton listButton, ListView.ListDataBindMapping previousListDataBindMapping); @@ -86,16 +86,16 @@ public interface ListButtonBindingListen /** * Called when a list button's selected item key has changed. * - * @param listButton - * @param previousSelectedItemKey + * @param listButton The list button that has changed. + * @param previousSelectedItemKey The previous binding key for the button's selected item. */ public void selectedItemKeyChanged(ListButton listButton, String previousSelectedItemKey); /** * Called when a list button's selected item bind type has changed. * - * @param listButton - * @param previousSelectedItemBindType + * @param listButton The list button that has changed. + * @param previousSelectedItemBindType The previous bind type for the selected item. */ public void selectedItemBindTypeChanged(ListButton listButton, BindType previousSelectedItemBindType); @@ -103,8 +103,8 @@ public interface ListButtonBindingListen /** * Called when a list button's selected item bind mapping has changed. * - * @param listButton - * @param previousSelectedItemBindMapping + * @param listButton The list button that has changed. + * @param previousSelectedItemBindMapping The previous bind mapping for the button's selected item. */ public void selectedItemBindMappingChanged(ListButton listButton, ListView.ItemBindMapping previousSelectedItemBindMapping); Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java Wed Nov 4 01:30:04 2015 @@ -53,39 +53,39 @@ public interface ListButtonItemListener /** * Called when an item is inserted into a list button's list data. * - * @param listButton - * @param index + * @param listButton The list button that has changed. + * @param index The index where the new data was inserted. */ public void itemInserted(ListButton listButton, int index); /** * Called when items are removed from a list button's list data. * - * @param listButton - * @param index - * @param count + * @param listButton The list button that has changed. + * @param index The starting index of the removed data items. + * @param count The number of items removed. */ public void itemsRemoved(ListButton listButton, int index, int count); /** * Called when an item is updated within a list button's list data. * - * @param listButton - * @param index + * @param listButton The list button whose data has changed. + * @param index The index into the data list of the updated item. */ public void itemUpdated(ListButton listButton, int index); /** * Called when a list button's list data has been cleared. * - * @param listButton + * @param listButton The list button whose data was cleared. */ public void itemsCleared(ListButton listButton); /** * Called when a list button's list data is sorted. * - * @param listButton + * @param listButton The list button whose data has been sorted. */ public void itemsSorted(ListButton listButton); } Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java Wed Nov 4 01:30:04 2015 @@ -58,16 +58,16 @@ public interface ListButtonListener { /** * Called when a list button's list data has changed. * - * @param listButton - * @param previousListData + * @param listButton The list button that has changed. + * @param previousListData The previous list data. */ public void listDataChanged(ListButton listButton, List<?> previousListData); /** * Called when a list button's item renderer has changed. * - * @param listButton - * @param previousItemRenderer + * @param listButton The list button that was changed. + * @param previousItemRenderer The previous renderer for the button's items. */ public void itemRendererChanged(ListButton listButton, ListView.ItemRenderer previousItemRenderer); @@ -75,15 +75,15 @@ public interface ListButtonListener { /** * Called when a list button's repeatable flag has changed. * - * @param listButton + * @param listButton The list button that has changed. */ public void repeatableChanged(ListButton listButton); /** * Called when a list button's disabled item filter has changed. * - * @param listButton - * @param previousDisabledItemFilter + * @param listButton The list button that has changed. + * @param previousDisabledItemFilter The previous disabled item filter for the list button. */ public void disabledItemFilterChanged(ListButton listButton, Filter<?> previousDisabledItemFilter); @@ -91,8 +91,8 @@ public interface ListButtonListener { /** * Called when a list button's list size has changed. * - * @param listButton - * @param previousListSize + * @param listButton The list button that has changed. + * @param previousListSize The previous value of the visible list size. */ public void listSizeChanged(ListButton listButton, int previousListSize); }