Declaring selected alternatives - add some docs

docs/src/main/asciidoc/cdi-reference.adoc

@@ -248,6 +248,24 @@ class MyBeanStarter {
 <1> The `AmazingService` is created during injection.
 <2> The `CoolService` is a normal scoped bean so we have to invoke a method upon the injected proxy to force the instantiation.
 
+* Annotate the bean with `@io.quarkus.runtime.Startup` as described in <<startup_annotation>>:
++
+[source,java]
+----
+@Startup // <1> 
+@ApplicationScoped
+public class EagerAppBean {
+  
+   private final String name;
+
+   EagerAppBean(NameGenerator generator) { // <2>
+     this.name = generator.createName();
+   }
+}
+----
+1. For each bean annotated with `@Startup` a synthetic observer of `StartupEvent` is generated. The default priority is used.
+2. The bean constructor is called when the application starts and the resulting contextual instance is stored in the application context.
+
 NOTE: Quarkus users are encouraged to always prefer the `@Observes StartupEvent` to `@Initialized(ApplicationScoped.class)` as explained in the link:lifecycle[Application Initialization and Termination] guide. 
 
 === Request Context Lifecycle 
@@ -408,6 +426,35 @@ public class CustomTracerConfiguration {
 `@DefaultBean` allows extensions (or any other code for that matter) to provide defaults while backing off if beans of that type are supplied in any
 way Quarkus supports.
 
+=== Declaring Selected Alternatives
+
+In CDI, an alternative bean may be selected either globally for an application by means of `@Priority`, or for a bean archive using a `beans.xml` descriptor.
+Quarkus has a simplified bean discovery and the content of `beans.xml` is ignored.
+
+The disadvantage of `@Priority` is that it has `@Target({ TYPE, PARAMETER })` and so it cannot be used for producer methods and fields.
+To address this problem and to simplify the code Quarkus provides the `io.quarkus.arc.AlternativePriority` annotation.
+It's basically a shortcut for `@Alternative` plus `@Priority`.
+Additionaly, it can be used for producers.
+
+However, it is also possible to select alternatives for an application using the unified configuration.
+The `quarkus.arc.selected-alternatives` property accepts a list of string values that are used to match alternative beans.
+If any value matches then the priority of `Integer#MAX_VALUE` is used for the relevant bean. 
+The priority declared via `@Priority` or `@AlernativePriority` is overriden.
+
+.Value Examples
+|===
+|Value|Description
+|`org.acme.Foo`| Match the fully qualified name of the bean class or the bean class of the bean that declares the producer
+|`org.acme.*`| Match beans where the package of the bean class is `org.acme`
+|`org.acme.**`| Match beans where the package of the bean class starts with `org.acme` 
+|`Bar`| Match the simple name of the bean class or the bean class of the bean that declares the producer
+|===
+
+.Example application.properties
+[source,properties]
+----
+quarkus.arc.selected-alternatives=org.acme.Foo,org.acme.*,Bar
+----
 
 == Build Time Extension Points
 

docs/src/main/asciidoc/lifecycle.adoc

@@ -102,6 +102,7 @@ See link:writing-extensions#bootstrap-three-phases[Three Phases of Bootstrap and
 
 NOTE: In CDI applications, an event with qualifier `@Initialized(ApplicationScoped.class)` is fired when the application context is initialized. See https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html#application_context[the spec, window="_blank"] for more info.
 
+[[startup_annotation]]
 === Using `@Startup` to initialize a CDI bean at application startup
 
 A bean represented by a class, producer method or field annotated with `@Startup` is initialized at application startup:

extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/ArcConfig.java

@@ -93,8 +93,9 @@ public class ArcConfig {
      * <li>a package name with suffix {@code .**}, i.e. {@code org.acme.**}, matches a package that starts with the value</li>
      * </ul>
      * Each element value is used to match an alternative bean class, an alternative stereotype annotation type or a bean class
-     * that declares an alternative producer. If matched the priority of {@link Integer#MAX_VALUE} is used for the relevant
-     * bean.
+     * that declares an alternative producer. If any value matches then the priority of {@link Integer#MAX_VALUE} is used for
+     * the relevant bean. The priority declared via {@link javax.annotation.Priority} or
+     * {@link io.quarkus.arc.AlternativePriority} is overriden.
      */
     @ConfigItem
     public Optional<List<String>> selectedAlternatives;