/*
 * Copyright (C) 2016 The Dagger Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package dagger;

import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

/**
 * Annotates <em>abstract</em> methods of a {@link Module} that delegate bindings. For example, to
 * bind {@link java.util.Random} to {@link java.security.SecureRandom} a module could declare the
 * following: {@code @Binds abstract Random bindRandom(SecureRandom secureRandom);}
 *
 * <p>{@code @Binds} methods are a drop-in replacement for {@link Provides} methods that simply
 * return an injected parameter.  Prefer {@code @Binds} because the generated implementation is
 * likely to be more efficient.
 *
 * <p>A {@code @Binds} method:
 * <ul>
 * <li>Must be {@code abstract}.
 * <li>Must have a single parameter whose type is assignable to the return type.  The return type is
 * the bound type and the parameter is the type to which it is bound.
 * <li>May be {@linkplain javax.inject.Scope scoped}.
 * <li>May be {@linkplain javax.inject.Qualifier qualified}.
 * </ul>
 */
@Documented
@Retention(RUNTIME)
@Target(METHOD)
public @interface Binds {}

@@ -1262,17 +1262,16 @@
 rameter.
- 
  Prefer 
@@ -1325,16 +1325,16 @@
 tion is%0A
+
  * likel
@@ -1391,16 +1391,19 @@
 method:%0A
+ *%0A
  * %3Cul%3E%0A
@@ -1404,16 +1404,18 @@
  %3Cul%3E%0A *
+  
  %3Cli%3EMus
@@ -1435,24 +1435,145 @@
 bstract%7D.%0A *
+   %3Cli%3EMay be %7B@linkplain javax.inject.Scope scoped%7D.%0A *   %3Cli%3EMay be %7B@linkplain javax.inject.Qualifier qualified%7D.%0A *  
  %3Cli%3EMust ha
@@ -1638,17 +1638,16 @@
 rn type.
- 
  The ret
@@ -1658,196 +1658,1301 @@
 type
- is%0A * the bound type and the parameter is the type to which it is bound.%0A * %3Cli%3EMay be %7B@linkplain javax.inject.Scope scoped%7D.%0A * %3Cli%3EMay be %7B@linkpla
+%0A *       declares the bound type (just as it would for a %7B@literal @%7D%7B@link dagger.Provides%7D method)%0A *       and the parameter is the type to which it is bound.%0A *       %3Cp%3EFor %7B@linkplain dagger.multibindings multibindings%7D, assignability is checked in similar%0A *       ways:%0A *       %3Cdl%3E%0A *         %3Cdt%3E%7B@link dagger.multibindings.IntoSet%7D%0A *         %3Cdd%3EThe parameter must be assignable to the only parameter of %7B@link java.util.Set#add%7D%0A *             when viewed as a member of the return type %E2%80%94 the parameter must be assignable to the%0A *             return type.%0A *         %3Cdt%3E%7B@link dagger.multibindings.ElementsIntoSet%7D%0A *         %3Cdd%3EThe parameter must be assignable to the the only parameter of %7B@link%0A *             java.util.Set#addAll%7D when viewed as a member of the return type %E2%80%94 if the return type%0A *             is %7B@code Set%3CE%3E%7D, the parameter must be assignable to%0A *            %7B@code Collection%3C? extends E%3E%7D.%0A *         %3Cdt%3E%7B@link dagger.multibindings.IntoMap%7D%0A *         %3Cdd%3EThe parameter must be assignable to the %7B@code value%7D parameter of %7B@link%0A *             java.util.Map#put%7D when viewed as a member of a %7B@l
 in
+k
  java
-x.inject.Qualifier qualified%7D.
+.util.Map%7D in which %7B@code%0A *             V%7D is bound to the return type %E2%80%94 the parameter must be assignable to the return type%0A *       %3C/dl%3E%0A *
 %0A * 

Add some javadoc to @Binds to explicitly describe how assignability is checked for multibindings.