Improve listing and data source Javadocs a bit

Change-Id: Ie3821df9bcb13af5f3955776a11d33fd2c16020e

4 files changed, 37 insertions, 23 deletions

diff --git a/client/src/main/java/com/vaadin/client/connectors/data/HasDataSource.java b/client/src/main/java/com/vaadin/client/connectors/data/HasDataSource.java
index 79a70a1fe9..f32dae4ac0 100644
--- a/client/src/main/java/com/vaadin/client/connectors/data/HasDataSource.java
+++ b/client/src/main/java/com/vaadin/client/connectors/data/HasDataSource.java
@@ -20,7 +20,11 @@ import com.vaadin.client.data.DataSource;
 import elemental.json.JsonObject;
 
 /**
- * Marker interface for Connectors that have a {@link DataSource}.
+ * A marker interface for connectors that have a data source.
+ * 
+ * @author Vaadin Ltd.
+ * @see DataSource
+ * @since 8.0
  */
 public interface HasDataSource {
 
@@ -28,14 +32,14 @@ public interface HasDataSource {
      * Sets the data source for this Connector.
      *
      * @param dataSource
-     *            new data source
+     *            the new data source, not null
      */
     void setDataSource(DataSource<JsonObject> dataSource);
 
     /**
      * Gets the current data source for this Connector.
      *
-     * @return data source
+     * @return the data source, not null
      */
     DataSource<JsonObject> getDataSource();
 }
diff --git a/server/src/main/java/com/vaadin/data/Listing.java b/server/src/main/java/com/vaadin/data/Listing.java
index 8d35a231de..aa410e9dc7 100644
--- a/server/src/main/java/com/vaadin/data/Listing.java
+++ b/server/src/main/java/com/vaadin/data/Listing.java
@@ -26,6 +26,7 @@ import com.vaadin.shared.data.selection.SelectionModel;
  * A generic interface for components that show a list of data.
  *
  * @author Vaadin Ltd.
+ * 
  * @param <T>
  *            the item data type
  * @param <SELECTIONMODEL>
@@ -62,7 +63,7 @@ public interface Listing<T, SELECTIONMODEL extends SelectionModel<T>>
      * Sets the collection of data items of this listing.
      *
      * @param items
-     *            the data items to display
+     *            the data items to display, not null
      *
      */
     default void setItems(Collection<T> items) {
@@ -75,7 +76,7 @@ public interface Listing<T, SELECTIONMODEL extends SelectionModel<T>>
      * @param items
      *            the data items to display
      */
-    default void setItems(T... items) {
+    default void setItems(@SuppressWarnings("unchecked") T... items) {
         setDataSource(DataSource.create(items));
     }
 
diff --git a/server/src/main/java/com/vaadin/server/data/DataSource.java b/server/src/main/java/com/vaadin/server/data/DataSource.java
index ea9c24acbb..a6147bbade 100644
--- a/server/src/main/java/com/vaadin/server/data/DataSource.java
+++ b/server/src/main/java/com/vaadin/server/data/DataSource.java
@@ -25,12 +25,15 @@ import java.util.stream.Stream;
  * Minimal DataSource API for communication between the DataProvider and a back
  * end service.
  *
- * @since
+ * @author Vaadin Ltd.
+ * 
  * @param <T>
  *            data type
  *
  * @see ListDataSource
  * @see BackEndDataSource
+ *
+ * @since
  */
 public interface DataSource<T>
         extends Function<Query, Stream<T>>, Serializable {
@@ -56,26 +59,30 @@ public interface DataSource<T>
      * This method creates a new {@link ListDataSource} from a given Collection.
      * The ListDataSource creates a protective List copy of all the contents in
      * the Collection.
-     *
-     * @param data
-     *            collection of data
-     * @return in-memory data source
+     * 
+     * @param <T>
+     *            the data item type
+     * @param items
+     *            the collection of data, not null
+     * @return a new list data source
      */
-    public static <T> ListDataSource<T> create(Collection<T> data) {
-        return new ListDataSource<>(data);
+    public static <T> ListDataSource<T> create(Collection<T> items) {
+        return new ListDataSource<>(items);
     }
 
     /**
      * This method creates a new {@link ListDataSource} from given objects.The
      * ListDataSource creates a protective List copy of all the contents in the
      * array.
-     *
-     * @param data
-     *            data objects
-     * @return in-memory data source
+     * 
+     * @param <T>
+     *            the data item type
+     * @param items
+     *            the data items
+     * @return a new list data source
      */
     @SafeVarargs
-    public static <T> ListDataSource<T> create(T... data) {
-        return new ListDataSource<>(Arrays.asList(data));
+    public static <T> ListDataSource<T> create(T... items) {
+        return new ListDataSource<>(Arrays.asList(items));
     }
-}
\ No newline at end of file
+}
diff --git a/server/src/main/java/com/vaadin/server/data/ListDataSource.java b/server/src/main/java/com/vaadin/server/data/ListDataSource.java
index 93add67ad4..f3ecc771ec 100644
--- a/server/src/main/java/com/vaadin/server/data/ListDataSource.java
+++ b/server/src/main/java/com/vaadin/server/data/ListDataSource.java
@@ -19,6 +19,7 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Comparator;
 import java.util.List;
+import java.util.Objects;
 import java.util.function.Function;
 import java.util.stream.Stream;
 
@@ -38,11 +39,12 @@ public class ListDataSource<T> implements DataSource<T> {
      * Constructs a new ListDataSource. This method makes a protective copy of
      * the contents of the Collection.
      *
-     * @param collection
-     *            initial data
+     * @param items
+     *            the initial data, not null
      */
-    public ListDataSource(Collection<T> collection) {
-        final List<T> backend = new ArrayList<>(collection);
+    public ListDataSource(Collection<T> items) {
+        Objects.requireNonNull(items, "items cannot be null");
+        final List<T> backend = new ArrayList<>(items);
         request = query -> backend.stream();
         size = backend.size();
     }