Polish @Primary Javadoc

org.springframework.context/src/main/java/org/springframework/context/annotation/Primary.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2009 the original author or authors.
+ * Copyright 2002-2011 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,21 +26,57 @@ import java.lang.annotation.Target;
 /**
  * Indicates that a bean should be given preference when multiple candidates
  * are qualified to autowire a single-valued dependency. If exactly one 'primary'
- * bean exists among the candidates, it will be the autowired value.
+ * bean exists among the candidates, it will be the autowired value. This annotation
+ * is semantically equivalent to the {@code <bean>} element's {@code primary} attribute
+ * in Spring XML.
  *
- * <p>May be used on any class directly or indirectly annotated with
- * {@link org.springframework.stereotype.Component} or on methods annotated
- * with {@link Bean}.
+ * <p>May be used on any class directly or indirectly annotated with @{@link
+ * org.springframework.stereotype.Component Component} or on methods annotated
+ * with @{@link Bean}.
  *
- * <p>Using {@link Primary} at the class level has no effect unless component-scanning
- * is being used. If a {@link Primary}-annotated class is declared via XML,
- * {@link Primary} annotation metadata is ignored, and
+ * <h2>Example</h2>
+ * <pre class="code">
+ * &#064;Component
+ * public class FooService {
+ *     private FooRepository fooRepository;
+ *
+ *     &#064;Autowired
+ *     public FooService(FooRepository fooRepository) {
+ *         this.fooRepository = fooRepository;
+ *     }
+ * }
+ *
+ * &#064;Component
+ * public class JdbcFooRepository {
+ *     public JdbcFooService(DataSource dataSource) {
+ *         // ...
+ *     }
+ * }
+ *
+ * &#064;Primary
+ * &#064;Component
+ * public class HibernateFooRepository {
+ *     public HibernateFooService(SessionFactory sessionFactory) {
+ *         // ...
+ *     }
+ * }
+ * </pre>
+ *
+ * <p>Because {@code HibernateFooRepository} is marked with {@code @Primary}, it will
+ * be injected preferentially over the jdbc-based variant assuming both are present as
+ * beans within the same Spring application context, which is often the case when
+ * component-scanning is applied liberally.
+ *
+ * <p>Note that using {@code @Primary} at the class level has no effect unless
+ * component-scanning is being used. If a {@code @Primary}-annotated class is declared via
+ * XML, {@code @Primary} annotation metadata is ignored, and
  * {@code <bean primary="true|false"/>} is respected instead.
  *
  * @author Chris Beams
  * @since 3.0
  * @see Lazy
  * @see Bean
+ * @see ComponentScan
  * @see org.springframework.stereotype.Component
  */
 @Target({ElementType.TYPE, ElementType.METHOD})