Document occasional failure to invoke removeState() #925

Use of weak references in
org.eclipse.e4.core.commands.internal.HandlerServiceHandler may result
in occasional failure to call removeState() on an underlying handler
after use. We document this in IObjectWithState, until a better solution
is found.

Author: basilevs

bundles/org.eclipse.core.commands/src/org/eclipse/core/commands/IObjectWithState.java

@@ -31,12 +31,18 @@ public interface IObjectWithState {
 	/**
 	 * Adds state to this object.
 	 *
-	 * @param id
-	 *            The identifier indicating the type of state being added; must
-	 *            not be <code>null</code>.
-	 * @param state
-	 *            The new state to add to this object; must not be
-	 *            <code>null</code>.
+	 * Usually, consumers will call <code>removeState()</code> with a matching id in
+	 * the same lifecycle of IObjectWithState. However, this behavior is not
+	 * guaranteed. Implementors should not rely on <code>removeState()</code> for
+	 * resource disposal. The recommended practice is to free resources associated
+	 * with non-removed states in some kind of dispose() method.
+	 *
+	 * @see AbstractHandlerWithState
+	 *
+	 * @param id    The identifier indicating the type of state being added; must
+	 *              not be <code>null</code>.
+	 * @param state The new state to add to this object; must not be
+	 *              <code>null</code>.
 	 */
 	public void addState(String id, State state);