Bug 558316 - [Javadoc] Fix warnings in platform.ui databinding

Fix syntax warnings aka missing description on @param, etc. Only Javadoc
changes. Fix many remaining errors and warnings from platform Javadoc
build with -Xdoclint:reference,html,syntax.

Change-Id: I47db51418dd81d0cf9300cdb858e9c91e67ee801
Signed-off-by: Paul Pazderski <paul-eclipse@ppazderski.de>

43 files changed, 184 insertions, 186 deletions

diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/AbstractObservable.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/AbstractObservable.java
index 079ec52e52a..10a9c29d5bd 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/AbstractObservable.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/AbstractObservable.java
@@ -26,7 +26,7 @@ public abstract class AbstractObservable extends ChangeManager implements IObser
 	private boolean disposed = false;
 
 	/**
-	 * @param realm
+	 * @param realm the realm to use; not <code>null</code>
 	 */
 	public AbstractObservable(Realm realm) {
 		super(realm);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeManager.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeManager.java
index 9b2aac540a4..299ce261a5a 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeManager.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeManager.java
@@ -34,8 +34,7 @@ import org.eclipse.core.runtime.ListenerList;
 	private final Realm realm;
 
 	/**
-	 * @param realm
-	 *
+	 * @param realm the realm to use; not <code>null</code>
 	 */
 	/* package */ChangeManager(Realm realm) {
 		Assert.isNotNull(realm, "Realm cannot be null"); //$NON-NLS-1$
@@ -43,8 +42,8 @@ import org.eclipse.core.runtime.ListenerList;
 	}
 
 	/**
-	 * @param listenerType
-	 * @param listener
+	 * @param listenerType arbitrary object to identify a type of the listener
+	 * @param listener     the listener to add; not <code>null</code>
 	 */
 	@SuppressWarnings("unchecked")
 	protected void addListener(Object listenerType,
@@ -75,8 +74,8 @@ import org.eclipse.core.runtime.ListenerList;
 	}
 
 	/**
-	 * @param listenerType
-	 * @param listener
+	 * @param listenerType arbitrary object to identify a type of the listener
+	 * @param listener     the listener to remove; not <code>null</code>
 	 */
 	protected void removeListener(Object listenerType,
 			IObservablesListener listener) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeSupport.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeSupport.java
index add618a1ba4..1a4c072f2bd 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeSupport.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ChangeSupport.java
@@ -22,7 +22,7 @@ package org.eclipse.core.databinding.observable;
 public abstract class ChangeSupport extends ChangeManager {
 
 	/**
-	 * @param realm
+	 * @param realm the realm
 	 */
 	public ChangeSupport(Realm realm) {
 		super(realm);
@@ -58,35 +58,35 @@ public abstract class ChangeSupport extends ChangeManager {
 	protected abstract void lastListenerRemoved();
 
 	/**
-	 * @param listener
+	 * @param listener the listener to add; not <code>null</code>
 	 */
 	public void addChangeListener(IChangeListener listener) {
 		addListener(ChangeEvent.TYPE, listener);
 	}
 
 	/**
-	 * @param listener
+	 * @param listener the listener to remove; not <code>null</code>
 	 */
 	public void removeChangeListener(IChangeListener listener) {
 		removeListener(ChangeEvent.TYPE, listener);
 	}
 
 	/**
-	 * @param listener
+	 * @param listener the listener to add; not <code>null</code>
 	 */
 	public void addStaleListener(IStaleListener listener) {
 		addListener(StaleEvent.TYPE, listener);
 	}
 
 	/**
-	 * @param listener
+	 * @param listener the listener to remove; not <code>null</code>
 	 */
 	public void removeStaleListener(IStaleListener listener) {
 		removeListener(StaleEvent.TYPE, listener);
 	}
 
 	/**
-	 * @param listener
+	 * @param listener the listener to add; not <code>null</code>
 	 * @since 1.2
 	 */
 	public void addDisposeListener(IDisposeListener listener) {
@@ -94,7 +94,7 @@ public abstract class ChangeSupport extends ChangeManager {
 	}
 
 	/**
-	 * @param listener
+	 * @param listener the listener to remove; not <code>null</code>
 	 * @since 1.2
 	 */
 	public void removeDisposeListener(IDisposeListener listener) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/DecoratingObservableCollection.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/DecoratingObservableCollection.java
index 45eb31114fb..78e7f24a5a7 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/DecoratingObservableCollection.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/DecoratingObservableCollection.java
@@ -29,8 +29,9 @@ public class DecoratingObservableCollection<E> extends DecoratingObservable impl
 	private IObservableCollection<E> decorated;
 
 	/**
-	 * @param decorated
-	 * @param disposeDecoratedOnDispose
+	 * @param decorated                 the observable being decorated.
+	 * @param disposeDecoratedOnDispose whether the decorated observable should be
+	 *                                  disposed when the decorator is disposed
 	 */
 	public DecoratingObservableCollection(IObservableCollection<E> decorated,
 			boolean disposeDecoratedOnDispose) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Diffs.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Diffs.java
index d66cf4b0576..f2863d67599 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Diffs.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Diffs.java
@@ -560,10 +560,9 @@ public class Diffs {
 	/**
 	 * Creates a diff between two values
 	 *
-	 * @param <T>
-	 *            the value type
-	 * @param oldValue
-	 * @param newValue
+	 * @param <T>      the value type
+	 * @param oldValue the old value
+	 * @param newValue the new value
 	 * @return a value diff
 	 */
 	public static <T> ValueDiff<T> createValueDiff(final T oldValue, final T newValue) {
@@ -584,8 +583,8 @@ public class Diffs {
 	/**
 	 * @param <E>
 	 *            the set element type
-	 * @param additions
-	 * @param removals
+	 * @param additions the added elements
+	 * @param removals the removed elements
 	 * @return a set diff
 	 */
 	public static <E> SetDiff<E> createSetDiff(Set<? extends E> additions, Set<? extends E> removals) {
@@ -610,7 +609,7 @@ public class Diffs {
 	/**
 	 * @param <E>
 	 *            the list element type
-	 * @param difference
+	 * @param difference the entry to describe the added or removed element
 	 * @return a list diff with one differing entry
 	 */
 	public static <E> ListDiff<E> createListDiff(ListDiffEntry<E> difference) {
@@ -620,8 +619,8 @@ public class Diffs {
 	/**
 	 * @param <E>
 	 *            the list element type
-	 * @param difference1
-	 * @param difference2
+	 * @param difference1 the first entry to describe the added or removed element
+	 * @param difference2 the second entry to describe the added or removed element
 	 * @return a list diff with two differing entries
 	 */
 	public static <E> ListDiff<E> createListDiff(ListDiffEntry<E> difference1,
@@ -642,7 +641,7 @@ public class Diffs {
 	 *
 	 * @param <E>
 	 *            the list element type
-	 * @param differences
+	 * @param differences a list of entries describing additions and/or removals from a list
 	 * @return a list diff with the given entries
 	 */
 	@SafeVarargs
@@ -661,7 +660,7 @@ public class Diffs {
 	 *
 	 * @param <E>
 	 *            the list element type
-	 * @param differences
+	 * @param differences a list of entries describing additions and/or removals from a list
 	 * @return a list diff with the given entries
 	 * @since 1.6
 	 */
@@ -676,11 +675,11 @@ public class Diffs {
 	}
 
 	/**
-	 * @param <E>
-	 *            the list element type
-	 * @param position
-	 * @param isAddition
-	 * @param element
+	 * @param <E>        the list element type
+	 * @param position   position where list is changed
+	 * @param isAddition <code>true</code> if element is added or <code>false</code>
+	 *                   if removed
+	 * @param element    the added or removed element
 	 * @return a list diff entry
 	 */
 	public static <E> ListDiffEntry<E> createListDiffEntry(final int position,
@@ -707,12 +706,10 @@ public class Diffs {
 	/**
 	 * Creates a MapDiff representing the addition of a single added key
 	 *
-	 * @param <K>
-	 *            the type of keys maintained by this map
-	 * @param <V>
-	 *            the type of mapped values
-	 * @param addedKey
-	 * @param newValue
+	 * @param <K>      the type of keys maintained by this map
+	 * @param <V>      the type of mapped values
+	 * @param addedKey key added to map
+	 * @param newValue value of the added key
 	 * @return a map diff
 	 */
 	public static <K, V> MapDiff<K, V> createMapDiffSingleAdd(final K addedKey,
@@ -747,13 +744,11 @@ public class Diffs {
 	}
 
 	/**
-	 * @param <K>
-	 *            the type of keys maintained by this map
-	 * @param <V>
-	 *            the type of mapped values
-	 * @param existingKey
-	 * @param oldValue
-	 * @param newValue
+	 * @param <K>         the type of keys maintained by this map
+	 * @param <V>         the type of mapped values
+	 * @param existingKey key of the changed element
+	 * @param oldValue    old value for key
+	 * @param newValue    new value for key
 	 * @return a map diff
 	 */
 	public static <K, V> MapDiff<K, V> createMapDiffSingleChange(
@@ -788,12 +783,10 @@ public class Diffs {
 	}
 
 	/**
-	 * @param <K>
-	 *            the type of keys maintained by this map
-	 * @param <V>
-	 *            the type of mapped values
-	 * @param removedKey
-	 * @param oldValue
+	 * @param <K>        the type of keys maintained by this map
+	 * @param <V>        the type of mapped values
+	 * @param removedKey key removed from map
+	 * @param oldValue   value of the removed key
 	 * @return a map diff
 	 */
 	public static <K, V> MapDiff<K, V> createMapDiffSingleRemove(
@@ -828,11 +821,9 @@ public class Diffs {
 	}
 
 	/**
-	 * @param <K>
-	 *            the type of keys maintained by this map
-	 * @param <V>
-	 *            the type of mapped values
-	 * @param copyOfOldMap
+	 * @param <K>          the type of keys maintained by this map
+	 * @param <V>          the type of mapped values
+	 * @param copyOfOldMap map content before removal
 	 * @return a map diff
 	 */
 	public static <K, V> MapDiff<K, V> createMapDiffRemoveAll(
@@ -867,15 +858,13 @@ public class Diffs {
 	}
 
 	/**
-	 * @param <K>
-	 *            the type of keys maintained by this map
-	 * @param <V>
-	 *            the type of mapped values
-	 * @param addedKeys
-	 * @param removedKeys
-	 * @param changedKeys
-	 * @param oldValues
-	 * @param newValues
+	 * @param <K>         the type of keys maintained by this map
+	 * @param <V>         the type of mapped values
+	 * @param addedKeys   the keys added to map
+	 * @param removedKeys the keys removed from map
+	 * @param changedKeys the keys with changed values
+	 * @param oldValues   map of removed key values and old values of changed keys
+	 * @param newValues   map of added key values and new values of changed keys
 	 * @return a map diff
 	 */
 	public static <K, V> MapDiff<K, V> createMapDiff(Set<? extends K> addedKeys, Set<? extends K> removedKeys,
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IChangeListener.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IChangeListener.java
index 9cd182b39c0..5fd08134ac8 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IChangeListener.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IChangeListener.java
@@ -39,7 +39,7 @@ public interface IChangeListener extends IObservablesListener {
 	 * must only be used locally in this method because it may be reused for
 	 * other change notifications.
 	 *
-	 * @param event
+	 * @param event the change event
 	 */
 	public void handleChange(ChangeEvent event);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IDisposeListener.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IDisposeListener.java
index aa4b97e237c..0e7de30446b 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IDisposeListener.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IDisposeListener.java
@@ -27,7 +27,7 @@ public interface IDisposeListener extends IObservablesListener {
 	 * given event object must only be used locally in this method because it
 	 * may be reused for other dispose notifications.
 	 *
-	 * @param event
+	 * @param event the dispose event
 	 */
 	public void handleDispose(DisposeEvent event);
 }
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IObservable.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IObservable.java
index 33d657c9303..fe938095fb5 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IObservable.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IObservable.java
@@ -53,28 +53,28 @@ public interface IObservable {
 	/**
 	 * Adds the given change listener to the list of change listeners. Change
 	 * listeners are notified about changes of the state of this observable in a
-	 * generic way, without specifying the change that happened. To get the
-	 * changed state, a change listener needs to query for the current state of
-	 * this observable.
+	 * generic way, without specifying the change that happened. To get the changed
+	 * state, a change listener needs to query for the current state of this
+	 * observable.
 	 *
-	 * @param listener
+	 * @param listener the listener to add; not <code>null</code>
 	 */
 	public void addChangeListener(IChangeListener listener);
 
 	/**
-	 * Removes the given change listener from the list of change listeners. Has
-	 * no effect if the given listener is not registered as a change listener.
+	 * Removes the given change listener from the list of change listeners. Has no
+	 * effect if the given listener is not registered as a change listener.
 	 *
-	 * @param listener
+	 * @param listener the listener to remove; not <code>null</code>
 	 */
 	public void removeChangeListener(IChangeListener listener);
 
 	/**
-	 * Adds the given stale listener to the list of stale listeners. Stale
-	 * listeners are notified when an observable object becomes stale, not when
-	 * is becomes non-stale.
+	 * Adds the given stale listener to the list of stale listeners. Stale listeners
+	 * are notified when an observable object becomes stale, not when is becomes
+	 * non-stale.
 	 *
-	 * @param listener
+	 * @param listener the listener to add; not <code>null</code>
 	 *
 	 * @see #isStale()
 	 */
@@ -84,7 +84,7 @@ public interface IObservable {
 	 * Removes the given stale listener from the list of stale listeners. Has no
 	 * effect if the given listener is not registered as a stale listener.
 	 *
-	 * @param listener
+	 * @param listener the listener to remove; not <code>null</code>
 	 */
 	public void removeStaleListener(IStaleListener listener);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IStaleListener.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IStaleListener.java
index c741249e1f2..abf361a1ef5 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IStaleListener.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IStaleListener.java
@@ -28,7 +28,7 @@ public interface IStaleListener extends IObservablesListener {
 	 * event object must only be used locally in this method because it may be
 	 * reused for other change notifications.
 	 *
-	 * @param staleEvent
+	 * @param staleEvent the stale event
 	 */
 	public void handleStale(StaleEvent staleEvent);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableEvent.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableEvent.java
index 3df81443c5a..533406990bc 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableEvent.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableEvent.java
@@ -29,7 +29,7 @@ public abstract class ObservableEvent extends EventObject {
 	/**
 	 * Creates a new observable event.
 	 *
-	 * @param source
+	 * @param source source of this event
 	 */
 	public ObservableEvent(IObservable source) {
 		super(source);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableTracker.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableTracker.java
index 9941642916f..01971335ed5 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableTracker.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/ObservableTracker.java
@@ -206,9 +206,10 @@ public class ObservableTracker {
 	/**
 	 * Runs the given runnable without tracking dependencies.
 	 *
-	 * @param runnable
+	 * @param runnable the runnable to execute
 	 *
 	 * @since 1.1
+	 * @see #setIgnore(boolean)
 	 */
 	public static void runAndIgnore(Runnable runnable) {
 		setIgnore(true);
@@ -241,7 +242,7 @@ public class ObservableTracker {
 	 * on automatic updates from the object without explicitly attaching a
 	 * listener.
 	 *
-	 * @param observable
+	 * @param observable the observable whose getter was called
 	 */
 	public static void getterCalled(IObservable observable) {
 		if (observable.isDisposed())
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Observables.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Observables.java
index 082cd9542d0..276a899c549 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Observables.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Observables.java
@@ -147,6 +147,7 @@ public class Observables {
 	 * Returns an observable value with the given constant value.
 	 *
 	 * @param <T>
+	 *            the value type
 	 *
 	 * @param realm
 	 *            the observable's realm
@@ -182,6 +183,7 @@ public class Observables {
 	 * Returns an observable value with the given constant value.
 	 *
 	 * @param <T>
+	 *            the value type
 	 *
 	 * @param value
 	 *            the observable's constant value
@@ -218,6 +220,7 @@ public class Observables {
 	 * set.
 	 *
 	 * @param <E>
+	 *            the element type
 	 *
 	 * @param set
 	 *            the set to wrap in an unmodifiable set
@@ -427,6 +430,7 @@ public class Observables {
 	 * given set.
 	 *
 	 * @param <E>
+	 *            the element type
 	 *
 	 * @param realm
 	 *            the realm of the returned set
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Realm.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Realm.java
index 38d55b6f394..1989ddee9a8 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Realm.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Realm.java
@@ -129,7 +129,7 @@ public abstract class Realm {
 	 * logged and not re-thrown. If the runnable implements {@link ISafeRunnable},
 	 * the exception is passed to its <code>handleException</code> method.
 	 *
-	 * @param runnable
+	 * @param runnable {@link Runnable} to execute
 	 */
 	protected static void safeRun(final Runnable runnable) {
 		ISafeRunnable safeRunnable;
@@ -166,7 +166,7 @@ public abstract class Realm {
 	 * running it. Otherwise, the exception will be logged.
 	 * </p>
 	 *
-	 * @param runnable
+	 * @param runnable {@link Runnable} to execute
 	 */
 	public void exec(Runnable runnable) {
 		if (isCurrent()) {
@@ -190,7 +190,7 @@ public abstract class Realm {
 	 * Subclasses should use {@link #safeRun(Runnable)} to run the runnable.
 	 * </p>
 	 *
-	 * @param runnable
+	 * @param runnable {@link Runnable} to execute
 	 */
 	public void asyncExec(Runnable runnable) {
 		synchronized (workQueue) {
@@ -215,8 +215,8 @@ public abstract class Realm {
 	 * Subclasses should use {@link #safeRun(Runnable)} to run the runnable.
 	 * </p>
 	 *
-	 * @param milliseconds
-	 * @param runnable
+	 * @param milliseconds wait time before executing the runnable
+	 * @param runnable {@link Runnable} to execute
 	 * @since 1.2
 	 */
 	public void timerExec(int milliseconds, final Runnable runnable) {
@@ -285,7 +285,7 @@ public abstract class Realm {
 	 * only protected access.
 	 * </p>
 	 *
-	 * @param runnable
+	 * @param runnable {@link Runnable} to execute
 	 */
 	protected void syncExec(Runnable runnable) {
 		SyncRunnable syncRunnable = new SyncRunnable(runnable);
@@ -328,8 +328,8 @@ public abstract class Realm {
 	 * {@link Runnable#run()} and resets the previous realm after completion.
 	 * Note that this will not set the given realm as the current realm.
 	 *
-	 * @param realm
-	 * @param runnable
+	 * @param realm default realm for the runnable
+	 * @param runnable {@link Runnable} to execute
 	 */
 	public static void runWithDefault(Realm realm, Runnable runnable) {
 		Realm oldRealm = Realm.getDefault();
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/AbstractObservableList.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/AbstractObservableList.java
index 84a130d26a3..648b4d6aa13 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/AbstractObservableList.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/AbstractObservableList.java
@@ -78,7 +78,7 @@ public abstract class AbstractObservableList<E> extends AbstractList<E>
 	private volatile boolean disposed = false;
 
 	/**
-	 * @param realm
+	 * @param realm the realm; not <code>null</code>
 	 *
 	 */
 	public AbstractObservableList(Realm realm) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/DecoratingObservableList.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/DecoratingObservableList.java
index a0030d8b85d..c7ba0fd565b 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/DecoratingObservableList.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/DecoratingObservableList.java
@@ -40,12 +40,11 @@ public class DecoratingObservableList<E> extends
 	private IListChangeListener<E> listChangeListener;
 
 	/**
-	 * Constructs a DecoratingObservableList which decorates the given
-	 * observable.
+	 * Constructs a DecoratingObservableList which decorates the given observable.
 	 *
-	 * @param decorated
-	 *            the observable list being decorated
-	 * @param disposeDecoratedOnDispose
+	 * @param decorated                 the observable list being decorated
+	 * @param disposeDecoratedOnDispose whether the decorated observable should be
+	 *                                  disposed when the decorator is disposed
 	 */
 	public DecoratingObservableList(IObservableList<E> decorated,
 			boolean disposeDecoratedOnDispose) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IListChangeListener.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IListChangeListener.java
index 7750c660caa..5c24fcc86c3 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IListChangeListener.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IListChangeListener.java
@@ -34,7 +34,7 @@ public interface IListChangeListener<E> extends IObservablesListener {
 	 * method because it may be reused for other change notifications. The diff
 	 * object referenced by the event is immutable and may be used non-locally.
 	 *
-	 * @param event
+	 * @param event the list change event
 	 */
 	void handleListChange(ListChangeEvent<? extends E> event);
 }
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IObservableList.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IObservableList.java
index 695faa8b74c..7f245c47296 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IObservableList.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/list/IObservableList.java
@@ -46,16 +46,16 @@ public interface IObservableList<E> extends List<E>, IObservableCollection<E> {
 	/**
 	 * Adds the given list change listener to the list of list change listeners.
 	 *
-	 * @param listener
+	 * @param listener the change listener to add; not <code>null</code>
 	 */
 	void addListChangeListener(IListChangeListener<? super E> listener);
 
 	/**
 	 * Removes the given list change listener from the list of list change
-	 * listeners. Has no effect if the given listener is not registered as a
-	 * list change listener.
+	 * listeners. Has no effect if the given listener is not registered as a list
+	 * change listener.
 	 *
-	 * @param listener
+	 * @param listener the change listener to remove; not <code>null</code>
 	 */
 	void removeListChangeListener(IListChangeListener<? super E> listener);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/AbstractObservableMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/AbstractObservableMap.java
index b3019df021f..001bddc64da 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/AbstractObservableMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/AbstractObservableMap.java
@@ -96,7 +96,7 @@ public abstract class AbstractObservableMap<K, V> extends AbstractMap<K, V>
 	}
 
 	/**
-	 * @param realm
+	 * @param realm the realm; not <code>null</code>
 	 */
 	public AbstractObservableMap(Realm realm) {
 		Assert.isNotNull(realm, "Realm cannot be null"); //$NON-NLS-1$
@@ -223,7 +223,7 @@ public abstract class AbstractObservableMap<K, V> extends AbstractMap<K, V>
 	/**
 	 * Sets the stale state. Must be invoked from the current realm.
 	 *
-	 * @param stale
+	 * @param stale the new stale state
 	 */
 	public void setStale(boolean stale) {
 		checkRealm();
@@ -252,7 +252,7 @@ public abstract class AbstractObservableMap<K, V> extends AbstractMap<K, V>
 	/**
 	 * Fires map change events. Must be invoked from current realm.
 	 *
-	 * @param diff
+	 * @param diff the change
 	 */
 	protected void fireMapChange(MapDiff<K, V> diff) {
 		checkRealm();
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/BidirectionalMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/BidirectionalMap.java
index 5cf4417a9d4..c1ff2ed303b 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/BidirectionalMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/BidirectionalMap.java
@@ -42,7 +42,8 @@ public class BidirectionalMap<K, V> extends ObservableMap<K, V> {
 	private IMapChangeListener<K, V> mapListener = event -> fireMapChange(Diffs.unmodifiableDiff(event.diff));
 
 	/**
-	 * @param wrappedMap
+	 * @param wrappedMap backing store for the map data, used to implement all map
+	 *                   operations
 	 */
 	public BidirectionalMap(IObservableMap<K, V> wrappedMap) {
 		super(wrappedMap.getRealm(), wrappedMap);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ComputedObservableMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ComputedObservableMap.java
index 309cda9ef30..fca970fef89 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ComputedObservableMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ComputedObservableMap.java
@@ -131,15 +131,15 @@ public abstract class ComputedObservableMap<K, V> extends AbstractObservableMap<
 	}
 
 	/**
-	 * @param keySet
+	 * @param keySet the key set
 	 */
 	public ComputedObservableMap(IObservableSet<K> keySet) {
 		this(keySet, null);
 	}
 
 	/**
-	 * @param keySet
-	 * @param valueType
+	 * @param keySet    the key set
+	 * @param valueType the value type
 	 * @since 1.2
 	 */
 	public ComputedObservableMap(IObservableSet<K> keySet, Object valueType) {
@@ -268,24 +268,24 @@ public abstract class ComputedObservableMap<K, V> extends AbstractObservableMap<
 	}
 
 	/**
-	 * @param removedKey
+	 * @param removedKey element to remove listener from
 	 */
 	protected abstract void unhookListener(K removedKey);
 
 	/**
-	 * @param addedKey
+	 * @param addedKey element to add listener to
 	 */
 	protected abstract void hookListener(K addedKey);
 
 	/**
-	 * @param key
+	 * @param key the key
 	 * @return the value for the given key
 	 */
 	protected abstract V doGet(K key);
 
 	/**
-	 * @param key
-	 * @param value
+	 * @param key   the key
+	 * @param value key's new value
 	 * @return the old value for the given key
 	 */
 	protected abstract V doPut(K key, V value);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/DecoratingObservableMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/DecoratingObservableMap.java
index fa53a188416..8209ce10db8 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/DecoratingObservableMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/DecoratingObservableMap.java
@@ -42,12 +42,11 @@ public class DecoratingObservableMap<K, V> extends DecoratingObservable
 	private IMapChangeListener<K, V> mapChangeListener;
 
 	/**
-	 * Constructs a DecoratingObservableMap which decorates the given
-	 * observable.
+	 * Constructs a DecoratingObservableMap which decorates the given observable.
 	 *
-	 * @param decorated
-	 *            the observable map being decorated
-	 * @param disposeDecoratedOnDispose
+	 * @param decorated                 the observable map being decorated
+	 * @param disposeDecoratedOnDispose whether the decorated observable should be
+	 *                                  disposed when the decorator is disposed
 	 */
 	public DecoratingObservableMap(IObservableMap<K, V> decorated,
 			boolean disposeDecoratedOnDispose) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/IObservableMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/IObservableMap.java
index ef8e1467be5..3d097dc578c 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/IObservableMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/IObservableMap.java
@@ -66,12 +66,12 @@ public interface IObservableMap<K, V> extends Map<K, V>, IObservable {
 	Object getValueType();
 
 	/**
-	 * @param listener
+	 * @param listener the change listener to add; not <code>null</code>
 	 */
 	void addMapChangeListener(IMapChangeListener<? super K, ? super V> listener);
 
 	/**
-	 * @param listener
+	 * @param listener the change listener to remove; not <code>null</code>
 	 */
 	void removeMapChangeListener(IMapChangeListener<? super K, ? super V> listener);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/MapDiff.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/MapDiff.java
index 18c4456dc91..26005062301 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/MapDiff.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/MapDiff.java
@@ -306,7 +306,7 @@ public abstract class MapDiff<K, V> implements IDiff {
 	 * Returns the old value for the given key, which must be an element of
 	 * {@link #getRemovedKeys()} or {@link #getChangedKeys()}.
 	 *
-	 * @param key
+	 * @param key the key
 	 * @return the old value for the given key.
 	 */
 	public abstract V getOldValue(Object key);
@@ -315,7 +315,7 @@ public abstract class MapDiff<K, V> implements IDiff {
 	 * Returns the new value for the given key, which must be an element of
 	 * {@link #getChangedKeys()} or {@link #getAddedKeys()}.
 	 *
-	 * @param key
+	 * @param key the key
 	 * @return the new value for the given key.
 	 */
 	public abstract V getNewValue(Object key);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ObservableMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ObservableMap.java
index c6f68674d29..659e3c0a70c 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ObservableMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/ObservableMap.java
@@ -48,15 +48,17 @@ public class ObservableMap<K, V> extends AbstractObservable implements IObservab
 	private boolean stale = false;
 
 	/**
-	 * @param wrappedMap
+	 * @param wrappedMap backing store for the map data, used to implement all map
+	 *                   operations
 	 */
 	public ObservableMap(Map<K, V> wrappedMap) {
 		this(Realm.getDefault(), wrappedMap);
 	}
 
 	/**
-	 * @param realm
-	 * @param wrappedMap
+	 * @param realm      the realm to use; not <code>null</code>
+	 * @param wrappedMap backing store for the map data, used to implement all map
+	 *                   operations
 	 */
 	public ObservableMap(Realm realm, Map<K, V> wrappedMap) {
 		super(realm);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/WritableMap.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/WritableMap.java
index 745913cbb92..a78ef8bdbb3 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/WritableMap.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/map/WritableMap.java
@@ -63,11 +63,11 @@ public class WritableMap<K, V> extends ObservableMap<K, V> {
 	}
 
 	/**
-	 * Constructs a new WritableMap on the default realm with the specified key
-	 * and value types.
+	 * Constructs a new WritableMap on the default realm with the specified key and
+	 * value types.
 	 *
-	 * @param keyType
-	 * @param valueType
+	 * @param keyType   the type of the keys in this map
+	 * @param valueType the type of the values in this map
 	 * @since 1.2
 	 */
 	public WritableMap(Object keyType, Object valueType) {
@@ -75,12 +75,12 @@ public class WritableMap<K, V> extends ObservableMap<K, V> {
 	}
 
 	/**
-	 * Constructs a new WritableMap on the given realm with the specified key
-	 * and value types.
+	 * Constructs a new WritableMap on the given realm with the specified key and
+	 * value types.
 	 *
-	 * @param realm
-	 * @param keyType
-	 * @param valueType
+	 * @param realm     the realm
+	 * @param keyType   the type of the keys in this map
+	 * @param valueType the type of the values in this map
 	 * @since 1.2
 	 */
 	public WritableMap(Realm realm, Object keyType, Object valueType) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/masterdetail/IObservableFactory.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/masterdetail/IObservableFactory.java
index 4f39bf4d355..d5923448023 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/masterdetail/IObservableFactory.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/masterdetail/IObservableFactory.java
@@ -34,7 +34,7 @@ public interface IObservableFactory<T, E extends IObservable> {
 	/**
 	 * Creates an observable for the given target object.
 	 *
-	 * @param target
+	 * @param target the target object
 	 * @return the new observable
 	 */
 	public E createObservable(T target);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/DecoratingObservableSet.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/DecoratingObservableSet.java
index f5b2bcbfb1b..62ddb2fda47 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/DecoratingObservableSet.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/DecoratingObservableSet.java
@@ -36,12 +36,11 @@ public class DecoratingObservableSet<E> extends
 	private ISetChangeListener<E> setChangeListener;
 
 	/**
-	 * Constructs a DecoratingObservableSet which decorates the given
-	 * observable.
+	 * Constructs a DecoratingObservableSet which decorates the given observable.
 	 *
-	 * @param decorated
-	 *            the observable set being decorated
-	 * @param disposeDecoratedOnDispose
+	 * @param decorated                 the observable set being decorated
+	 * @param disposeDecoratedOnDispose whether the decorated observable should be
+	 *                                  disposed when the decorator is disposed
 	 */
 	public DecoratingObservableSet(IObservableSet<E> decorated,
 			boolean disposeDecoratedOnDispose) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/IObservableSet.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/IObservableSet.java
index f9c263d98a6..7e6f37eb5b4 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/IObservableSet.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/IObservableSet.java
@@ -43,12 +43,12 @@ import org.eclipse.core.databinding.observable.IObservableCollection;
 public interface IObservableSet<E> extends Set<E>, IObservableCollection<E> {
 
 	/**
-	 * @param listener
+	 * @param listener the change listener to add; not <code>null</code>
 	 */
 	public void addSetChangeListener(ISetChangeListener<? super E> listener);
 
 	/**
-	 * @param listener
+	 * @param listener the change listener to remove; not <code>null</code>
 	 */
 	public void removeSetChangeListener(ISetChangeListener<? super E> listener);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/ListToSetAdapter.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/ListToSetAdapter.java
index 2989a328810..10e8b45e1d9 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/ListToSetAdapter.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/ListToSetAdapter.java
@@ -65,7 +65,7 @@ public class ListToSetAdapter<E> extends ObservableSet<E> {
 	};
 
 	/**
-	 * @param list
+	 * @param list the list to adapt
 	 */
 	public ListToSetAdapter(IObservableList<E> list) {
 		super(list.getRealm(), new HashSet<E>(), list.getElementType());
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/MappedSet.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/MappedSet.java
index 9f6c68828c7..6404c5ed68a 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/MappedSet.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/MappedSet.java
@@ -112,8 +112,8 @@ public class MappedSet extends ObservableSet {
 	private IObservableSet input;
 
 	/**
-	 * @param input
-	 * @param map
+	 * @param input input set with keys from the map
+	 * @param map   the map to map
 	 */
 	public MappedSet(IObservableSet input, IObservableMap map) {
 		super(input.getRealm(), Collections.EMPTY_SET, Object.class);
@@ -130,7 +130,7 @@ public class MappedSet extends ObservableSet {
 	}
 
 	/**
-	 * @param mapValue
+	 * @param mapValue map value to add
 	 * @return true if the given mapValue was an addition
 	 */
 	protected boolean handleAddition(Object mapValue) {
@@ -144,7 +144,7 @@ public class MappedSet extends ObservableSet {
 	}
 
 	/**
-	 * @param mapValue
+	 * @param mapValue map value to remove
 	 * @return true if the given mapValue has been removed
 	 */
 	protected boolean handleRemoval(Object mapValue) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/UnionSet.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/UnionSet.java
index b6c4b7736f3..4a342185641 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/UnionSet.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/UnionSet.java
@@ -63,14 +63,14 @@ public final class UnionSet<E> extends ObservableSet<E> {
 	private StalenessTracker stalenessTracker;
 
 	/**
-	 * @param childSets
+	 * @param childSets the sets that form this union
 	 */
 	public UnionSet(IObservableSet<? extends E>[] childSets) {
 		this(new HashSet<>(Arrays.asList(childSets)));
 	}
 
 	/**
-	 * @param childSets
+	 * @param childSets the sets that form this union
 	 * @since 1.6
 	 */
 	public UnionSet(Set<IObservableSet<? extends E>> childSets) {
@@ -78,8 +78,8 @@ public final class UnionSet<E> extends ObservableSet<E> {
 	}
 
 	/**
-	 * @param childSets
-	 * @param elementType
+	 * @param childSets   the sets that form this union
+	 * @param elementType explicit element type for the child set elements
 	 * @since 1.2
 	 */
 	public UnionSet(IObservableSet<? extends E>[] childSets, Object elementType) {
@@ -87,8 +87,8 @@ public final class UnionSet<E> extends ObservableSet<E> {
 	}
 
 	/**
-	 * @param childSets
-	 * @param elementType
+	 * @param childSets   the sets that form this union
+	 * @param elementType explicit element type for the child set elements
 	 * @since 1.6
 	 */
 	public UnionSet(Set<IObservableSet<? extends E>> childSets, Object elementType) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/WritableSet.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/WritableSet.java
index 107ce423053..a2c4a92ac4f 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/WritableSet.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/set/WritableSet.java
@@ -56,7 +56,7 @@ public class WritableSet<E> extends ObservableSet<E> {
 	 * the given collection. Changes to the given collection after calling this
 	 * method do not affect the contents of the created WritableSet.
 	 *
-	 * @param c
+	 * @param c elements to initialize this set with
 	 * @param elementType
 	 *            can be <code>null</code>
 	 */
@@ -68,7 +68,7 @@ public class WritableSet<E> extends ObservableSet<E> {
 	 * Constructs a new empty instance in the given realm and a
 	 * <code>null</code> element type.
 	 *
-	 * @param realm
+	 * @param realm the realm
 	 */
 	public WritableSet(Realm realm) {
 		this(realm, new HashSet<E>(), null);
@@ -80,8 +80,8 @@ public class WritableSet<E> extends ObservableSet<E> {
 	 * given collection after calling this method do not affect the contents of
 	 * the created WritableSet.
 	 *
-	 * @param realm
-	 * @param c
+	 * @param realm the realm
+	 * @param c elements to initialize this set with
 	 * @param elementType
 	 *            can be <code>null</code>
 	 */
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractObservableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractObservableValue.java
index c454112e1f9..6b2dbaa955c 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractObservableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractObservableValue.java
@@ -45,7 +45,7 @@ abstract public class AbstractObservableValue<T> extends AbstractObservable
 	}
 
 	/**
-	 * @param realm
+	 * @param realm the realm to use; not <code>null</code>
 	 */
 	public AbstractObservableValue(Realm realm) {
 		super(realm);
@@ -73,7 +73,7 @@ abstract public class AbstractObservableValue<T> extends AbstractObservable
 	 * Template method for setting the value of the observable. By default the
 	 * method throws an {@link UnsupportedOperationException}.
 	 *
-	 * @param value
+	 * @param value the value to set
 	 */
 	protected void doSetValue(T value) {
 		throw new UnsupportedOperationException();
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractVetoableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractVetoableValue.java
index 902f1a16b19..575d05e8822 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractVetoableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/AbstractVetoableValue.java
@@ -45,7 +45,7 @@ public abstract class AbstractVetoableValue<T> extends
 	}
 
 	/**
-	 * @param realm
+	 * @param realm the realm
 	 */
 	public AbstractVetoableValue(Realm realm) {
 		super(realm);
@@ -67,10 +67,10 @@ public abstract class AbstractVetoableValue<T> extends
 	}
 
 	/**
-	 * Sets the value. Invoked after performing veto checks. Should not fire
-	 * change events.
+	 * Sets the value. Invoked after performing veto checks. Should not fire change
+	 * events.
 	 *
-	 * @param value
+	 * @param value the approved value to set
 	 */
 	protected abstract void doSetApprovedValue(T value);
 
@@ -87,10 +87,10 @@ public abstract class AbstractVetoableValue<T> extends
 	}
 
 	/**
-	 * Notifies listeners about a pending change, and returns true if no
-	 * listener vetoed the change.
+	 * Notifies listeners about a pending change, and returns true if no listener
+	 * vetoed the change.
 	 *
-	 * @param diff
+	 * @param diff the pending change
 	 * @return false if the change was vetoed, true otherwise
 	 */
 	protected boolean fireValueChanging(ValueDiff<T> diff) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ChangeVetoException.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ChangeVetoException.java
index 355a1aeb278..ab46a375a34 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ChangeVetoException.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ChangeVetoException.java
@@ -20,7 +20,7 @@ package org.eclipse.core.databinding.observable.value;
 public class ChangeVetoException extends RuntimeException {
 
 	/**
-	 * @param string
+	 * @param string exception message
 	 */
 	public ChangeVetoException(String string) {
 		super(string);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ComputedValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ComputedValue.java
index b1468c7b41c..43594ad9f95 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ComputedValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/ComputedValue.java
@@ -120,24 +120,22 @@ public abstract class ComputedValue<T> extends AbstractObservableValue<T> {
 	}
 
 	/**
-	 * @param valueType
-	 *            can be <code>null</code>
+	 * @param valueType can be <code>null</code>
 	 */
 	public ComputedValue(Object valueType) {
 		this(Realm.getDefault(), valueType);
 	}
 
 	/**
-	 * @param realm
-	 *
+	 * @param realm the realm to use; not <code>null</code>
 	 */
 	public ComputedValue(Realm realm) {
 		this(realm, null);
 	}
 
 	/**
-	 * @param realm
-	 * @param valueType
+	 * @param realm     the realm to use; not <code>null</code>
+	 * @param valueType can be <code>null</code>
 	 */
 	public ComputedValue(Realm realm, Object valueType) {
 		super(realm);
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingObservableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingObservableValue.java
index b48da743291..d4037395f57 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingObservableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingObservableValue.java
@@ -41,6 +41,8 @@ public class DecoratingObservableValue<T> extends DecoratingObservable
 	 * @param decorated
 	 *            the observable value being decorated
 	 * @param disposeDecoratedOnDispose
+	 *            whether the decorated observable should be disposed when the
+	 *            decorator is disposed
 	 */
 	public DecoratingObservableValue(IObservableValue<T> decorated,
 			boolean disposeDecoratedOnDispose) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingVetoableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingVetoableValue.java
index 99758ef546a..73c44fc13f6 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingVetoableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DecoratingVetoableValue.java
@@ -27,8 +27,9 @@ import org.eclipse.core.databinding.observable.Diffs;
 public class DecoratingVetoableValue<T> extends DecoratingObservableValue<T>
 		implements IVetoableValue<T> {
 	/**
-	 * @param decorated
-	 * @param disposeDecoratedOnDispose
+	 * @param decorated                 the observable value being decorated
+	 * @param disposeDecoratedOnDispose whether the decorated observable should be
+	 *                                  disposed when the decorator is disposed
 	 */
 	public DecoratingVetoableValue(IObservableValue<T> decorated,
 			boolean disposeDecoratedOnDispose) {
@@ -63,7 +64,7 @@ public class DecoratingVetoableValue<T> extends DecoratingObservableValue<T>
 	 * Notifies listeners about a pending change, and returns true if no
 	 * listener vetoed the change.
 	 *
-	 * @param diff
+	 * @param diff the pending change
 	 * @return false if the change was vetoed, true otherwise
 	 */
 	protected boolean fireValueChanging(ValueDiff<T> diff) {
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DuplexingObservableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DuplexingObservableValue.java
index 951461eea2c..3c6014f568d 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DuplexingObservableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/DuplexingObservableValue.java
@@ -37,6 +37,7 @@ public abstract class DuplexingObservableValue<T> extends AbstractObservableValu
 	 * to use if the list is empty or contains multiple different values.
 	 *
 	 * @param <T>
+	 *            the type of value being observed
 	 *
 	 * @param target
 	 *            the observable list
@@ -76,15 +77,15 @@ public abstract class DuplexingObservableValue<T> extends AbstractObservableValu
 	private PrivateInterface privateInterface;
 
 	/**
-	 * @param target
+	 * @param target the observed target list
 	 */
 	public DuplexingObservableValue(IObservableList<T> target) {
 		this(target, target.getElementType());
 	}
 
 	/**
-	 * @param target
-	 * @param valueType
+	 * @param target    the observed target list
+	 * @param valueType the value type or <code>null</code>
 	 */
 	public DuplexingObservableValue(IObservableList<T> target, Object valueType) {
 		super(target.getRealm());
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IObservableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IObservableValue.java
index abc24080b7b..efd9c0b6e5b 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IObservableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IObservableValue.java
@@ -66,12 +66,12 @@ public interface IObservableValue<T> extends IObservable {
 
 	/**
 	 *
-	 * @param listener
+	 * @param listener the change listener to add; not <code>null</code>
 	 */
 	public void addValueChangeListener(IValueChangeListener<? super T> listener);
 
 	/**
-	 * @param listener
+	 * @param listener the change listener to remove; not <code>null</code>
 	 */
 	public void removeValueChangeListener(IValueChangeListener<? super T> listener);
 }
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IValueChangingListener.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IValueChangingListener.java
index 2b8ec7f9cfa..28bea050111 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IValueChangingListener.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IValueChangingListener.java
@@ -36,6 +36,7 @@ public interface IValueChangingListener<T> extends IObservablesListener {
 	 * may be used non-locally.
 	 *
 	 * @param event
+	 *            the event
 	 */
 	public void handleValueChanging(ValueChangingEvent<T> event);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IVetoableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IVetoableValue.java
index ff1b0508a92..ea680de5ea8 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IVetoableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/IVetoableValue.java
@@ -33,12 +33,12 @@ package org.eclipse.core.databinding.observable.value;
 public interface IVetoableValue<T> extends IObservableValue<T> {
 
 	/**
-	 * @param listener
+	 * @param listener the listener to add; not <code>null</code>
 	 */
 	public void addValueChangingListener(IValueChangingListener<T> listener);
 
 	/**
-	 * @param listener
+	 * @param listener the listener to remove; not <code>null</code>
 	 */
 	public void removeValueChangingListener(IValueChangingListener<T> listener);
 
diff --git a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/WritableValue.java b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/WritableValue.java
index 4756443097e..862d5336452 100644
--- a/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/WritableValue.java
+++ b/bundles/org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/value/WritableValue.java
@@ -63,7 +63,7 @@ public class WritableValue<T> extends AbstractObservableValue<T> {
 	 * Constructs a new instance with the provided <code>realm</code>, a
 	 * <code>null</code> value type, and a <code>null</code> initial value.
 	 *
-	 * @param realm
+	 * @param realm the realm
 	 */
 	public WritableValue(Realm realm) {
 		this(realm, null, null);
@@ -72,7 +72,7 @@ public class WritableValue<T> extends AbstractObservableValue<T> {
 	/**
 	 * Constructs a new instance.
 	 *
-	 * @param realm
+	 * @param realm the realm
 	 * @param initialValue
 	 *            can be <code>null</code>
 	 * @param valueType
@@ -110,6 +110,7 @@ public class WritableValue<T> extends AbstractObservableValue<T> {
 
 	/**
 	 * @param <T2>
+	 *            the type of observed value of the created instance
 	 * @param elementType
 	 *            can be <code>null</code>
 	 * @return new instance with the default realm and a value of