Merge Google changes as of 2016-05-10

[eamonnmcmanus]

• Allow an @AutoValue.Builder to extend a parent builder using the <B extends Builder<B>> idiom.
• Add support for "optional getters", where a getter in an AutoValue Builder can have type Optional<T> and it will return Optional.of(x) where x is the value that has been set in the Builder, or Optional.empty() if no value has been set.
• In AutoValue builders, support setting a property of type Optional<T> via a setter with an argument of type T.
• In AutoValue builders, make optional properties default to Optional.empty().
• Have AutoAnnotation factor in package names when detecting overloads. Previously it treated all annotations with the same SimpleName as being overload attempts.
• Support for TYPE_USE @Nullable. This is patch for "AutoValue should respect @Nullable annotations on types #283" #293 by @brychcy.
• Restructure the code in AutoValueProcessor for handling extensions to get rid of warnings about abstract methods when those methods are going to be implemented by an extension, and to fix a bug where extensions would not work right if there was a toBuilder() method. Some of the code in this change is based on Moves method verification after extensions have had the chance to consume properties. #299 by @rharter.
• Remove an inaccurate javadoc reference, which referred to an artifact from an earlier draft version of the Extensions API. This is Removing inaccurate JavaDocs reference #322 by @lucastsa.
• Add logic to AutoValue to detect the confusing case where you think you are using JavaBeans conventions (like getFoo()) but you aren't because at least one method isn't.
• Add a README.md describing EscapeVelocity.
• Add a bit more information in the changelog about 1.0 and 1.1. Also quote some instances of @AutoValue that needed it.

[cgruber]

LGTM

[lucastsa]

"In AutoValue builders, support setting a property of type Optional via a setter with an argument of type T."

Why did you use Optional.of() instead of Optional.ofNullable() in that implementation? It makes it impossible to reset that property after you set it in that way (specially after getting a builder from toBuilder()), unless you have a setter with an Optional argument.

[eamonnmcmanus]

This probably isn't the best place to have this discussion, but we did deliberately decide against allowing a null argument here. We didn't feel that it would be appropriate to distort the semantics just because null and empty feel sort of like the same thing. It's at least as likely that you would want to get a NullPointerException when the argument is null as that you would want Optional.empty(). This is any case only a minor convenience. You can always write explicitly:

@AutoValue.Builder
public abstract static class Builder {
  public Builder setFoo(String foo) {
    return setFoo(Optional.ofNullable(foo));
  }
  abstract Builder setFoo(Optional<String> foo);
}