Minor javadoc tidy in context API
diff --git a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/Active.java b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/Active.java
index fc45296..601ccc2 100644
--- a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/Active.java
+++ b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/Active.java
@@ -1,5 +1,5 @@
/*******************************************************************************
- * Copyright (c) 2010 IBM Corporation and others.
+ * Copyright (c) 2010, 2013 IBM Corporation 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
@@ -15,11 +15,15 @@
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import javax.inject.Inject;
import javax.inject.Qualifier;
/**
- * Instructs dependency injection mechanism to obtain value from the active
- * context.
+ * This annotation can be added to injectable fields ands methods
+ * to indicate that the injected value should come from the active context.
+ *
+ * @see Inject
+ * @see IEclipseContext#activate
*/
@Qualifier
@Documented
diff --git a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java
index 8a6a19e..31de170 100644
--- a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java
+++ b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/IEclipseContext.java
@@ -15,7 +15,8 @@
* A context is used to isolate application code from its dependencies on an application framework
* or container. This helps avoid building in dependencies on a specific framework that inhibit
* reuse of the application code. Fundamentally a context supplies values (either data objects or
- * services), and allows values to be set.
+ * services), and allows values to be set. Typically a client will be provided values
+ * from a context through injection, removing the need for clients to even depend on this interface.
* <p>
* While a context appears superficially to be a Map, it may in fact compute values for requested
* keys dynamically rather than simply retrieving a stored value.
@@ -27,6 +28,11 @@
* context.
* </p>
* <p>
+ * Contexts may have child contexts. Children inherit context values from their parent
+ * as described earlier. At any time, one of the children may be considered the <i>active</i>
+ * child. The interpretation of what active means depends on the domain in which the context
+ * is used.
+ * <p>
* Like maps, values are stored in the context based on keys. Two types of keys can be used: strings
* and classes. When classes are used to access objects in the context, keys are calculated based on
* the class name, so the value stored for the class {@link java.lang.String} can be retrieved
diff --git a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/RunAndTrack.java b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/RunAndTrack.java
index ac87164..6bafef9 100644
--- a/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/RunAndTrack.java
+++ b/bundles/org.eclipse.e4.core.contexts/src/org/eclipse/e4/core/contexts/RunAndTrack.java
@@ -15,9 +15,11 @@
import org.eclipse.e4.core.internal.contexts.EclipseContext;
/**
- * Extended version of a runnable that can be used with the
- * {@link IEclipseContext#runAndTrack(RunAndTrack)} version gets more detailed
- * information on the change, such as the service name and the event type.
+ * Instances of this class contain behavior that is executed within an
+ * {@link IEclipseContext}. The context records all values accessed by this
+ * object, and will re-evaluate this runnable whenever any accessed value changes.
+ *
+ * @see IEclipseContext#runAndTrack(RunAndTrack)
*/
abstract public class RunAndTrack {
