Last massive documentation dump. All basic javadoc is now done, though especially the docs

on the lombok annotations in the lombok package need far more massaging.

Also added a feature to HandleSynchronized to not auto-generate the locker fields if
a specific name is provided (because, imagine you typoed those. You'd never find it!)

1 files changed, 87 insertions, 8 deletions

diff --git a/src/lombok/core/AnnotationValues.java b/src/lombok/core/AnnotationValues.java
index 432d507f..ee434f1f 100644
--- a/src/lombok/core/AnnotationValues.java
+++ b/src/lombok/core/AnnotationValues.java
@@ -1,3 +1,24 @@
+/*
+ * Copyright © 2009 Reinier Zwitserloot and Roel Spilker.
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package lombok.core;
 
 import java.lang.annotation.Annotation;
@@ -10,13 +31,23 @@ import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Represents a single annotation in a source file and can be used to query the parameters present on it.
+ */
 public class AnnotationValues<A extends Annotation> {
 	private final Class<A> type;
 	private final Map<String, AnnotationValue> values;
 	private final AST<?>.Node ast;
-
+	
+	/**
+	 * Represents a single method on the annotation class. For example, the value() method on the Getter annotation.
+	 */
 	public static class AnnotationValue {
+		/** A list of the raw expressions. List is size 1 unless an array is provided. */
 		public final List<String> raws;
+		
+		/** Guesses for each raw expression. If the raw expression is a literal expression, the guess will
+		 * likely be right. If not, it'll be wrong. */
 		public final List<Object> valueGuesses;
 		private final AST<?>.Node node;
 		
@@ -33,7 +64,9 @@ public class AnnotationValues<A extends Annotation> {
 			this.valueGuesses = Collections.singletonList(valueGuess);
 		}
 		
-		/** When the value is an array type. */
+		/**
+		 * Like the other constructor, but used for when the annotation method is initialized with an array value.
+		 */
 		public AnnotationValue(AST<?>.Node node, List<String> raws, List<Object> valueGuesses) {
 			this.node = node;
 			this.raws = raws;
@@ -52,21 +85,39 @@ public class AnnotationValues<A extends Annotation> {
 			node.addError(message);
 		}
 		
+		/** {@inheritDoc} */
 		@Override public String toString() {
 			return "raws: " + raws + " valueGuesses: " + valueGuesses;
 		}
 	}
 	
+	/**
+	 * Creates a new AnnotationValues.
+	 * 
+	 * @param type The annotation type. For example, "Getter.class"
+	 * @param values a Map of method names to AnnotationValue instances, for example 'value -> annotationValue instance'.
+	 * @param ast The Annotation node.
+	 */
 	public AnnotationValues(Class<A> type, Map<String, AnnotationValue> values, AST<?>.Node ast) {
 		this.type = type;
 		this.values = values;
 		this.ast = ast;
 	}
 	
+	/**
+	 * Thrown on the fly if an actual annotation instance procured via the {@link #getInstance()} method is queried
+	 * for a method for which this AnnotationValues instance either doesn't have a guess or can't manage to fit
+	 * the guess into the required data type.
+	 */
 	public static class AnnotationValueDecodeFail extends RuntimeException {
 		private static final long serialVersionUID = 1L;
 		
+		/** The index into an array initializer (e.g. if the second value in an array initializer is
+		 * an integer constant expression like '5+SomeOtherClass.CONSTANT', this exception will be thrown,
+		 * and you'll get a '1' for idx. */
 		public final int idx;
+		
+		/** The AnnotationValue object that goes with the annotation method for which the failure occurred. */
 		public final AnnotationValue owner;
 		
 		public AnnotationValueDecodeFail(AnnotationValue owner, String msg, int idx) {
@@ -83,8 +134,15 @@ public class AnnotationValues<A extends Annotation> {
 	
 	private A cachedInstance = null;
 	
+	/**
+	 * Creates an actual annotation instance. You can use this to query any annotation methods, except for
+	 * those annotation methods with class literals, as those can most likely not be turned into Class objects.
+	 * 
+	 * If some of the methods cannot be implemented, this method still works; it's only when you call a method
+	 * that has a problematic value that an AnnotationValueDecodeFail exception occurs.
+	 */
 	@SuppressWarnings("unchecked")
-	public A getInstance() throws AnnotationValueDecodeFail {
+	public A getInstance() {
 		if ( cachedInstance != null ) return cachedInstance;
 		InvocationHandler invocations = new InvocationHandler() {
 			public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
@@ -217,16 +275,32 @@ public class AnnotationValues<A extends Annotation> {
 				"Can't translate a " + guess.getClass() + " to the expected " + expected, pos);
 	}
 	
+	/**
+	 * Returns the raw expressions used for the provided annotationMethodName.
+	 * 
+	 * You should use this method for annotation methods that return Class objects. Remember that
+	 * class literals end in ".class" which you probably want to strip off.
+	 */
 	public List<String> getRawExpressions(String annotationMethodName) {
 		AnnotationValue v = values.get(annotationMethodName);
 		return v == null ? Collections.<String>emptyList() : v.raws;
 	}
 	
+	/**
+	 * Convenience method to return the first result in a {@link getRawExpressions(String)} call.
+	 * 
+	 * You should use this method if the annotation method is not an array type.
+	 */
 	public String getRawExpression(String annotationMethodName) {
 		List<String> l = getRawExpressions(annotationMethodName);
 		return l.isEmpty() ? null : l.get(0);
 	}
 	
+	/**
+	 * Attempts to translate class literals to their fully qualified names, such as 'Throwable.class' to 'java.lang.Throwable'.
+	 * 
+	 * This process is at best a guess, but it will take into account import statements.
+	 */
 	public List<String> getProbableFQTypes(String annotationMethodName) {
 		List<String> result = new ArrayList<String>();
 		AnnotationValue v = values.get(annotationMethodName);
@@ -236,6 +310,16 @@ public class AnnotationValues<A extends Annotation> {
 		return result;
 	}
 	
+	/**
+	 * Convenience method to return the first result in a {@link getProbableFQType(String)} call.
+	 * 
+	 * You should use this method if the annotation method is not an array type.
+	 */
+	public String getProbableFQType(String annotationMethodName) {
+		List<String> l = getProbableFQTypes(annotationMethodName);
+		return l.isEmpty() ? null : l.get(0);
+	}
+	
 	private String toFQ(String typeName) {
 		Class<?> c;
 		boolean fqn = typeName.indexOf('.') > -1;
@@ -279,9 +363,4 @@ public class AnnotationValues<A extends Annotation> {
 			return null;
 		}
 	}
-	
-	public String getProbableFQType(String annotationMethodName) {
-		List<String> l = getProbableFQTypes(annotationMethodName);
-		return l.isEmpty() ? null : l.get(0);
-	}
 }