Add JavaDoc to the AutoSuggest related interfaces and templates
Also some adjustments the JavaDoc of AutoSuggset and DataSource
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ArrayDataProvider.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ArrayDataProvider.java
index 8e44d25..913a12e 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ArrayDataProvider.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ArrayDataProvider.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2013 EclipseSource and others.
+ * Copyright (c) 2013, 2014 EclipseSource and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -14,10 +14,20 @@
import java.util.List;
+/**
+ * This class provides a simple implementation of the default {@link DataProvider} interface
+ * based on a String array.
+ */
public class ArrayDataProvider implements DataProvider {
private final List<String> elements;
+
+ /**
+ * Constructs a new instance of this class given an array of strings.
+ *
+ * @param elements an array of suggestions texts for a {@DataSource}
+ **/
public ArrayDataProvider( String... elements ) {
this.elements = Arrays.asList( elements );
}
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java
index 95a6af1..f596863 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2013 EclipseSource and others.
+ * Copyright (c) 2013, 2014 EclipseSource and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java
index c7ff577..b59b48d 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2013 EclipseSource and others.
+ * Copyright (c) 2013, 2014 EclipseSource and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
@@ -10,7 +10,14 @@
******************************************************************************/
package org.eclipse.rap.addons.autosuggest;
-
+/**
+ * An implementation of this interface can be attached to a DataSource to provide multiple strings
+ * per suggestion. The first string of each suggestion will be the one to be inserted as text.
+ *
+ * <p>
+ * It is recommended to use this interface in junction with a {@link ColumnTemplate}.
+ * </p>
+ */
public interface ColumnDataProvider extends DataProvider {
String[] getTexts( Object element );
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java
index b26cdff..a929f59 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java
@@ -10,11 +10,25 @@
******************************************************************************/
package org.eclipse.rap.addons.autosuggest;
-
+/**
+ * Instances of this class can be used to configure a {@link DataSource} to format the suggestions
+ * provided by a {@link ColumnDataProvider} as a table.
+ *
+ * <p>
+ * If used, the first string of a suggestion will not be displayed in the list, while the
+ * remaining strings will be placed in their natural order into each column defined by this
+ * template.
+ * </p>
+ */
public class ColumnTemplate {
private final int[] widths;
+ /**
+ * Constructs a new instance of this class given any number of integers.
+ *
+ * @param widths the width of all columns in pixels
+ */
public ColumnTemplate( int... widths ) {
this.widths = widths;
}
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java
index 5f41e64..dc64ef7 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java
@@ -10,11 +10,25 @@
******************************************************************************/
package org.eclipse.rap.addons.autosuggest;
-
+/**
+ * This is the default interface to be implemented to attach data to a {@link DataSource}
+ *
+ * @see DataSource#setDataProvider(DataProvider)
+ */
public interface DataProvider {
+ /**
+ * Provides the raw suggestions data
+ *
+ * @return an iterable object containing all suggestions in any arbitrary format
+ */
Iterable<?> getSuggestions();
+ /**
+ * Provides a single suggestion text for a raw suggestion
+ *
+ * @return a string to be suggested as text input
+ */
String getValue( Object element );
}
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java
index 16cbd35..5f4c1e5 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java
@@ -56,11 +56,11 @@
}
/**
- * Sets the <code>DataProvider</code> instance to be used to collect the suggestions data. The
- * data is collected by <code>DataProvider</code> only once.
+ * Sets the <code>DataProvider</code> to be used to collect the suggestions data. The
+ * data is collected from <code>DataProvider</code> only once.
*
* The type of DataProvider set also determines which <code>Template</code> types can be used
- * with the same <code>DataSource</code> instance. (e.g. a {@link ColumnDataProvider} can be
+ * with the same <code>DataSource</code> instance. (i.e. a {@link ColumnDataProvider} can be
* used with a {@link ColumnTemplate}.) It also changes how the format of the suggestion
* given to a filterScript.
*
@@ -89,7 +89,7 @@
*}</pre>
* <p>
* The default script is not case-sensitive and can handle suggestions provided by
- * {@link DataProvider} and {@link ColumnDataProvider}. In case of
+ * {@link DataProvider} and {@link ColumnDataProvider} interfaces. In case of
* <code>ColumnDataProvider</code> only the first column is queried.
* </p>
*
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java
index 3056d3d..54171c1 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java
@@ -10,9 +10,15 @@
******************************************************************************/
package org.eclipse.rap.addons.autosuggest;
-
+/**
+ * A listener interface to be used with
+ * {@link AutoSuggest#addSelectionListener(SuggestionSelectedListener) AutoSuggest}.
+ */
public interface SuggestionSelectedListener {
+ /**
+ * Sent when the user selects a suggestion
+ */
void suggestionSelected();
}
