Context: improve javadoc for explicit service list

When instantiating a Context with an explicit list of services,
compatible services will be loaded in the order given, regardless of
their relative priorities. For example, if you write:

    new Context(UsageService.class, EventService.class)

Then the DefaultUsageService will be loaded before the
DefaultEventService, resulting in the DefaultUsageService's event
handlers not being registered properly, since at the time of its
initialization the context's EventService will still be null.

So for the EventService in particular, it should almost always be the
first service given in the explicit list.

Presumably, there are similar problems when doing things like:

    new Context(SCIFIOService.class, SciJavaService.class)

Since the EventService matches SciJavaService but not SCIFIOService,
although I did not test this. We will either need to:

A) Change such constructions to list the core SciJava services first; or

B) Change the behavior of context creation such that all compatible
   services are _always_ loaded in priority order, regardless of the
   order of the specified service template types.

Otherwise, any services which register event handlers, but do not
depend on the EventService explicitly or transitively, will not work
as expected in such scenarios.

Author: ctrueden

src/main/java/org/scijava/Context.java

@@ -117,7 +117,11 @@ public Context(final boolean empty) {
 	 * </p>
 	 * 
 	 * @param serviceClasses A list of types that implement the {@link Service}
-	 *          interface (e.g., {@code DisplayService.class}).
+	 *          interface (e.g., {@code DisplayService.class}). Compatible
+	 *          services will be loaded in the order given,
+	 *          <em>regardless of their relative priorities</em>. In particular,
+	 *          take care to specify the {@link EventService} first if you need
+	 *          proper event handling for the other services.
 	 * @see #Context(Collection, PluginIndex, boolean)
 	 * @throws ClassCastException If any of the given arguments do not implement
 	 *           the {@link Service} interface.
@@ -132,6 +136,10 @@ public Context(@SuppressWarnings("rawtypes") final Class... serviceClasses) {
 	 * 
 	 * @param serviceClasses A collection of types that implement the
 	 *          {@link Service} interface (e.g., {@code DisplayService.class}).
+	 *          Compatible services will be loaded according to the order of the
+	 *          collection, <em>regardless of their relative priorities</em>. In
+	 *          particular, take care to specify the {@link EventService} first if
+	 *          you need proper event handling for the other services.
 	 * @see #Context(Collection, PluginIndex, boolean)
 	 */
 	public Context(final Collection<Class<? extends Service>> serviceClasses) {
@@ -144,8 +152,12 @@ public Context(final Collection<Class<? extends Service>> serviceClasses) {
 	 * 
 	 * @param serviceClasses A collection of types that implement the
 	 *          {@link Service} interface (e.g., {@code DisplayService.class}).
+	 *          Compatible services will be loaded according to the order of the
+	 *          collection, <em>regardless of their relative priorities</em>. In
+	 *          particular, take care to specify the {@link EventService} first if
+	 *          you need proper event handling for the other services.
 	 * @param strict Whether context creation will fail fast when there is
-	 *          is an error instantiating a required service.
+	 *          an error instantiating a required service.
 	 * @see #Context(Collection, PluginIndex, boolean)
 	 */
 	public Context(final Collection<Class<? extends Service>> serviceClasses,
@@ -155,10 +167,10 @@ public Context(final Collection<Class<? extends Service>> serviceClasses,
 	}
 
 	/**
-	 * Creates a new SciJava application with the specified PluginIndex. This
-	 * allows a base set of available plugins to be defined, and is useful when
-	 * plugins that would not be returned by the {@link PluginIndex}'s
-	 * {@link org.scijava.plugin.PluginFinder} are desired.
+	 * Creates a new SciJava application context with all available services from
+	 * the specified PluginIndex. This allows a base set of available plugins to
+	 * be defined, and is useful when plugins that would not be returned by the
+	 * {@link PluginIndex}'s {@link org.scijava.plugin.PluginFinder} are desired.
 	 * 
 	 * @param pluginIndex The plugin index to use when discovering and indexing
 	 *          plugins. If you wish to completely control how services are
@@ -181,6 +193,10 @@ public Context(final PluginIndex pluginIndex) {
 	 * 
 	 * @param serviceClasses A collection of types that implement the
 	 *          {@link Service} interface (e.g., {@code DisplayService.class}).
+	 *          Compatible services will be loaded according to the order of the
+	 *          collection, <em>regardless of their relative priorities</em>. In
+	 *          particular, take care to specify the {@link EventService} first if
+	 *          you need proper event handling for the other services.
 	 * @param pluginIndex The plugin index to use when discovering and indexing
 	 *          plugins. If you wish to completely control how services are
 	 *          discovered (i.e., use your own
@@ -212,14 +228,18 @@ public Context(final Collection<Class<? extends Service>> serviceClasses,
 	 * 
 	 * @param serviceClasses A collection of types that implement the
 	 *          {@link Service} interface (e.g., {@code DisplayService.class}).
+	 *          Compatible services will be loaded according to the order of the
+	 *          collection, <em>regardless of their relative priorities</em>. In
+	 *          particular, take care to specify the {@link EventService} first if
+	 *          you need proper event handling for the other services.
 	 * @param pluginIndex The plugin index to use when discovering and indexing
 	 *          plugins. If you wish to completely control how services are
 	 *          discovered (i.e., use your own
 	 *          {@link org.scijava.plugin.PluginFinder} implementation), then you
 	 *          can pass a custom {@link PluginIndex} here. Passing null will
 	 *          result in a default plugin index being constructed and used.
 	 * @param strict Whether context creation will fail fast when there is
-	 *          is an error instantiating a required service.
+	 *          an error instantiating a required service.
 	 */
 	public Context(final Collection<Class<? extends Service>> serviceClasses,
 		final PluginIndex pluginIndex, final boolean strict)