/*
 * Copyright (C) 2012 Google, Inc.
 *
 * 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 com.google.auto.value;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotation indicating that the annotated type is a value type with an automatically-generated
 * implementation.
 *
 * <p>Here is a simple example of a value type using {@code @AutoValue}:
 *
 * <pre>
 * {@code @AutoValue}
 * {@code public abstract class Contact {
 *   public abstract String name();
 *   public abstract List<String> phoneNumbers();
 *   public abstract int sortOrder();
 *
 *   public static Contact create(String name, List<String> phoneNumbers, int sortOrder) {
 *     return new AutoValue_Contact(name, phoneNumbers, sortOrder);
 *   }
 * }}</pre>
 *
 * <p>The generated subclass is called {@code AutoValue_Contact} but users of {@code Contact} do not
 * need to know that. Only the implementation of the {@code create} method does.
 *
 * <p>As an alternative to instantiating the generated subclass in the {@code create} method, you
 * can define a {@code Factory} interface like this:</p>
 *
 * <pre>
 * {@code @AutoValue}
 * {@code public abstract class Contact {
 *   public abstract String name();
 *   public abstract List<String> phoneNumbers();
 *   public abstract int sortOrder();
 *
 *   public static Contact create(String name, List<String> phoneNumbers, int sortOrder) {
 *     return AutoValues.using(Factory.class).create(name, phoneNumbers, sortOrder);
 *   }
 *
 *   interface Factory {
 *     Contact create(String name, List<String> phoneNumbers, int sortOrder);
 *   }
 * }}</pre>
 *
 * @author Éamonn McManus
 */
/*
 *  TODO(gak): We should obviously try to figure out whether this whole factory mechanism can be
 *  replaced with @AutoFactory
 */
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface AutoValue {
}
@@ -100,19 +100,16 @@
 cense%22);
-%0A *
  you may
@@ -133,16 +133,19 @@
 e except
+%0A *
  in comp
@@ -168,19 +168,16 @@
 License.
-%0A *
  You may
@@ -331,19 +331,16 @@
 software
-%0A *
  distrib
@@ -361,16 +361,19 @@
  License
+%0A *
  is dist
@@ -400,19 +400,16 @@
 %22 BASIS,
-%0A *
  WITHOUT
@@ -461,16 +461,19 @@
  express
+%0A *
  or impl
@@ -476,19 +476,16 @@
 implied.
-%0A *
  See the
@@ -544,19 +544,16 @@
 ions and
-%0A *
  limitat
@@ -558,24 +558,27 @@
 ations under
+%0A *
  the License
@@ -788,100 +788,83 @@
 %0A * 
-Annotation indicating that the annotated type is a value type with an automatically-
+Specifies that %3Ca href=%22http://goo.gl/Ter394%22%3EAutoValue%3C/a%3E should 
 generate
 d%0A *
@@ -863,12 +863,11 @@
 rate
-d%0A *
+ an
  imp
@@ -881,308 +881,266 @@
 tion
-.
 %0A *
-%0A * %3Cp%3EHere is a simple example of a value type using %7B@code @AutoValue%7D:%0A *%0A * %3Cpre%3E%0A * %7B@code @AutoValue%7D%0A * %7B@code public abstract class Contact %7B%0A *   public abstract String name();%0A *   public abstract List%3CString%3E phoneNumbers();%0A *   public abstract int sortOrder();%0A *%0A *   public
+ class for the annotated abstract class, implementing the standard %7B@link Object%7D methods like%0A * %7B@link Object#equals equals%7D to have conventional value semantics. A simple example: %3Cpre%3E%0A *%0A *   &#64;AutoValue%0A *   abstract class Person %7B%0A *    
  static 
 Cont
@@ -1127,39 +1127,38 @@
 %7B%0A *     static 
-Contact
+Person
  create(String n
@@ -1166,54 +1166,22 @@
 me, 
-List%3CString%3E phoneNumbers, int sortOrder
+int id
 ) %7B%0A *
+  
     
@@ -1206,1084 +1206,398 @@
 lue_
-Contact(name, phoneNumbers, sortOrder);%0A *   %7D%0A * %7D%7D%3C/pre%3E%0A *%0A * %3Cp%3EThe generated subclass is called %7B@code AutoValue_Contact%7D but users of %7B@code Contact%7D do not%0A * need to know that. Only the implementation of the %7B@code create%7D method does.%0A *%0A * %3Cp%3EAs an alternative to instantiating the generated subclass in the %7B@code create%7D method, you%0A * can define a %7B@code Factory%7D interface like this:%3C/p%3E%0A *%0A * %3Cpre%3E%0A * %7B@code @AutoValue%7D%0A * %7B@code public abstract class Contact %7B%0A *   public abstract String name();%0A *   public abstract List%3CString%3E phoneNumbers();%0A *   public abstract int sortOrder();%0A *%0A *   public static Contact create(String name, List%3CString%3E phoneNumbers, int sortOrder) %7B%0A *     return AutoV
+Person(name, id);%0A *     %7D%0A *%0A *     abstract String name();%0A *     abstract int id();%0A *   %7D%3C/pre%3E%0A *%0A * @see %3Ca href=%22http://goo.gl/Ter394%22%3EAutoValue User's Guide%3C/a%3E%0A *%0A * %3C!-- MOE:begin_intracomment_strip --%3E%0A * @see %3Ca href=%22http://go/autov
 alue
-s.using(Factory.class).create(name, phoneNumbers, sortOrder);%0A *   %7D%0A *%0A *   interface Factory %7B%0A *     Contact create(String name, List%3CString%3E phoneNumbers, int sortOrder);%0A *   %7D%0A * %7D%7D%3C/pre%3E%0A *%0A * @author %C3%89amonn McManus%0A */%0A/*%0A *  TODO(gak): We should obviously try to figure out whether this whole factory mechanism can be%0A *  replaced with @AutoFactory
+%22%3EAdditional Google-internal information%3Ca/%3E%0A * %3C!-- MOE:end_intracomment_strip --%3E%0A *%0A * @author %C3%89amonn McManus%0A * @author Kevin Bourrillion
 %0A */
@@ -1691,6 +1691,6 @@
 ue %7B
-%0A
 %7D
+%0A

Revise the @AutoValue docs.