More documentation.

src/lombok/javac/HandlerLibrary.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.javac;
 
 import java.lang.annotation.Annotation;
@@ -10,7 +31,6 @@ import java.util.ServiceConfigurationError;
 import java.util.ServiceLoader;
 
 import javax.annotation.processing.Messager;
-import javax.lang.model.element.TypeElement;
 import javax.tools.Diagnostic;
 
 import lombok.core.PrintAST;
@@ -22,7 +42,12 @@ import lombok.core.AnnotationValues.AnnotationValueDecodeFail;
 import com.sun.tools.javac.tree.JCTree.JCAnnotation;
 import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;
 
-
+/**
+ * This class tracks 'handlers' and knows how to invoke them for any given AST node.
+ * 
+ * This class can find the handlers (via SPI discovery) and will set up the given AST node, such as
+ * building an AnnotationValues instance.
+ */
 public class HandlerLibrary {
 	private final TypeLibrary typeLibrary = new TypeLibrary();
 	private final Map<String, AnnotationHandlerContainer<?>> annotationHandlers = new HashMap<String, AnnotationHandlerContainer<?>>();
@@ -30,6 +55,10 @@ public class HandlerLibrary {
 	private final Messager messager;
 	private boolean skipPrintAST = true;
 	
+	/**
+	 * Creates a new HandlerLibrary that will report any problems or errors to the provided messager.
+	 * You probably want to use {@link #load(Messager)} instead.
+	 */
 	public HandlerLibrary(Messager messager) {
 		this.messager = messager;
 	}
@@ -48,6 +77,11 @@ public class HandlerLibrary {
 		}
 	}
 	
+	/**
+	 * Creates a new HandlerLibrary that will report any problems or errors to the provided messager,
+	 * then uses SPI discovery to load all annotation and visitor based handlers so that future calls
+	 * to the handle methods will defer to these handlers.
+	 */
 	public static HandlerLibrary load(Messager messager) {
 		HandlerLibrary library = new HandlerLibrary(messager);
 		
@@ -57,6 +91,7 @@ public class HandlerLibrary {
 		return library;
 	}
 	
+	/** Uses SPI Discovery to find implementations of {@link JavacAnnotationHandler}. */
 	@SuppressWarnings("unchecked")
 	private static void loadAnnotationHandlers(HandlerLibrary lib) {
 		//No, that seemingly superfluous reference to JavacAnnotationHandler's classloader is not in fact superfluous!
@@ -78,22 +113,7 @@ public class HandlerLibrary {
 		}
 	}
 	
-	public void javacWarning(String message) {
-		javacWarning(message, null);
-	}
-	
-	public void javacWarning(String message, Throwable t) {
-		messager.printMessage(Diagnostic.Kind.WARNING, message + (t == null ? "" : (": " + t)));
-	}
-	
-	public void javacError(String message) {
-		javacWarning(message, null);
-	}
-	
-	public void javacError(String message, Throwable t) {
-		messager.printMessage(Diagnostic.Kind.ERROR, message + (t == null ? "" : (": " + t)));
-	}
-	
+	/** Uses SPI Discovery to find implementations of {@link JavacASTVisitor}. */
 	private static void loadVisitorHandlers(HandlerLibrary lib) {
 		//No, that seemingly superfluous reference to JavacASTVisitor's classloader is not in fact superfluous!
 		Iterator<JavacASTVisitor> it = ServiceLoader.load(JavacASTVisitor.class,
@@ -108,6 +128,43 @@ public class HandlerLibrary {
 		}
 	}
 	
+	/** Generates a warning in the Messager that was used to initialize this HandlerLibrary. */
+	public void javacWarning(String message) {
+		javacWarning(message, null);
+	}
+	
+	/** Generates a warning in the Messager that was used to initialize this HandlerLibrary. */
+	public void javacWarning(String message, Throwable t) {
+		messager.printMessage(Diagnostic.Kind.WARNING, message + (t == null ? "" : (": " + t)));
+	}
+	
+	/** Generates an error in the Messager that was used to initialize this HandlerLibrary. */
+	public void javacError(String message) {
+		javacWarning(message, null);
+	}
+	
+	/** Generates an error in the Messager that was used to initialize this HandlerLibrary. */
+	public void javacError(String message, Throwable t) {
+		messager.printMessage(Diagnostic.Kind.ERROR, message + (t == null ? "" : (": " + t)));
+	}
+	
+	/**
+	 * Handles the provided annotation node by first finding a qualifying instance of
+	 * {@link JavacAnnotationHandler} and if one exists, calling it with a freshly cooked up
+	 * instance of {@link AnnotationValues}.
+	 * 
+	 * Note that depending on the printASTOnly flag, the {@link lombok.core.PrintAST} annotation
+	 * will either be silently skipped, or everything that isn't <code>PrintAST</code> will be skipped.
+	 * 
+	 * The HandlerLibrary will attempt to guess if the given annotation node represents a lombok annotation.
+	 * For example, if <code>lombok.*</code> is in the import list, then this method will guess that
+	 * <code>Getter</code> refers to <code>lombok.Getter</code>, presuming that {@link lombok.javac.handlers.HandleGetter}
+	 * has been loaded.
+	 * 
+	 * @param unit The Compilation Unit that contains the Annotation AST Node.
+	 * @param node The Lombok AST Node representing the Annotation AST Node.
+	 * @param annotation 'node.get()' - convenience parameter.
+	 */
 	public boolean handleAnnotation(JCCompilationUnit unit, JavacAST.Node node, JCAnnotation annotation) {
 		TypeResolver resolver = new TypeResolver(typeLibrary, node.getPackageDeclaration(), node.getImportStatements());
 		String rawType = annotation.annotationType.toString();
@@ -130,6 +187,9 @@ public class HandlerLibrary {
 		return handled;
 	}
 	
+	/**
+	 * Will call all registered {@link JavacASTVisitor} instances.
+	 */
 	public void callASTVisitors(JavacAST ast) {
 		for ( JavacASTVisitor visitor : visitorHandlers ) try {
 			ast.traverse(visitor);
@@ -138,14 +198,18 @@ public class HandlerLibrary {
 		}
 	}
 	
-	public boolean hasHandlerFor(TypeElement annotationType) {
-		return annotationHandlers.containsKey(annotationType.getQualifiedName().toString());
-	}
-	
+	/**
+	 * Lombok does not currently support triggering annotations in a specified order; the order is essentially
+	 * random right now. This lack of order is particularly annoying for the <code>PrintAST</code> annotation,
+	 * which is almost always intended to run last. Hence, this hack, which lets it in fact run last.
+	 * 
+	 * {@see #skipAllButPrintAST}
+	 */
 	public void skipPrintAST() {
 		skipPrintAST = true;
 	}
 	
+	/** {@see #skipPrintAST} */
 	public void skipAllButPrintAST() {
 		skipPrintAST = false;
 	}

src/lombok/javac/Javac.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.javac;
 
 import java.lang.annotation.Annotation;
@@ -25,11 +46,20 @@ import com.sun.tools.javac.tree.JCTree.JCLiteral;
 import com.sun.tools.javac.tree.JCTree.JCNewArray;
 import com.sun.tools.javac.util.JCDiagnostic.DiagnosticPosition;
 
+/**
+ * Container for static utility methods relevant to lombok's operation on javac.
+ */
 public class Javac {
 	private Javac() {
 		//prevent instantiation
 	}
 	
+	/**
+	 * Checks if the Annotation AST Node provided is likely to be an instance of the provided annotation type.
+	 * 
+	 * @param type An actual annotation type, such as <code>lombok.Getter.class</code>.
+	 * @param node A Lombok AST node representing an annotation in source code.
+	 */
 	public static boolean annotationTypeMatches(Class<? extends Annotation> type, Node node) {
 		if ( node.getKind() != Kind.ANNOTATION ) return false;
 		String typeName = ((JCAnnotation)node.get()).annotationType.toString();
@@ -46,6 +76,12 @@ public class Javac {
 		return false;
 	}
 	
+	/**
+	 * Creates an instance of <code>AnnotationValues</code> for the provided AST Node.
+	 * 
+	 * @param type An annotation class type, such as <code>lombok.Getter.class</code>.
+	 * @param node A Lombok AST node representing an annotation in source code.
+	 */
 	public static <A extends Annotation> AnnotationValues<A> createAnnotation(Class<A> type, final Node node) {
 		Map<String, AnnotationValue> values = new HashMap<String, AnnotationValue>();
 		JCAnnotation anno = (JCAnnotation) node.get();
@@ -86,6 +122,11 @@ public class Javac {
 		return new AnnotationValues<A>(type, values, node);
 	}
 	
+	/**
+	 * Turns an expression into a guessed intended literal. Only works for literals, as you can imagine.
+	 * 
+	 * Will for example turn a TrueLiteral into 'Boolean.valueOf(true)'.
+	 */
 	private static Object calculateGuess(JCExpression expr) {
 		if ( expr instanceof JCLiteral ) {
 			JCLiteral lit = (JCLiteral)expr;

src/lombok/javac/JavacAnnotationHandler.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.javac;
 
 import java.lang.annotation.Annotation;
@@ -6,6 +27,32 @@ import lombok.core.AnnotationValues;
 
 import com.sun.tools.javac.tree.JCTree.JCAnnotation;
 
+/**
+ * Implement this interface if you want to be triggered for a specific annotation.
+ * 
+ * You MUST replace 'T' with a specific annotation type, such as:
+ * 
+ * <code>public class HandleGetter implements JavacAnnotationHandler&lt;<b>Getter</b>&gt;</code>
+ * 
+ * Because this generics parameter is inspected to figure out which class you're interested in.
+ * 
+ * You also need to register yourself via SPI discovery as being an implementation of <code>JavacAnnotationHandler</code>.
+ */
 public interface JavacAnnotationHandler<T extends Annotation> {
+	/**
+	 * Called when an annotation is found that is likely to match the annotation you're interested in.
+	 * 
+	 * Be aware that you'll be called for ANY annotation node in the source that looks like a match. There is,
+	 * for example, no guarantee that the annotation node belongs to a method, even if you set your
+	 * TargetType in the annotation to methods only.
+	 * 
+	 * @param annotation The actual annotation - use this object to retrieve the annotation parameters.
+	 * @param ast The javac AST node representing the annotation.
+	 * @param annotationNode The Lombok AST wrapper around the 'ast' parameter. You can use this object
+	 * to travel back up the chain (something javac AST can't do) to the parent of the annotation, as well
+	 * as access useful methods such as generating warnings or errors focussed on the annotation.
+	 * @return <code>true</code> if you don't want to be called again about this annotation during this
+	 * compile session (you've handled it), or <code>false</code> to indicate you aren't done yet.
+	 */
 	boolean handle(AnnotationValues<T> annotation, JCAnnotation ast, JavacAST.Node annotationNode);
 }

src/lombok/javac/apt/Processor.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.javac.apt;
 
 import java.util.ArrayList;
@@ -28,6 +49,16 @@ import com.sun.tools.javac.tree.JCTree.JCMethodDecl;
 import com.sun.tools.javac.tree.JCTree.JCVariableDecl;
 
 
+/**
+ * This Annotation Processor is the standard injection mechanism for lombok-enabling the javac compiler.
+ * 
+ * Due to lots of changes in the core javac code, as well as lombok's heavy usage of non-public API, this
+ * code only works for the javac v1.6 compiler; it definitely won't work for javac v1.5, and it probably
+ * won't work for javac v1.7 without modifications.
+ * 
+ * To actually enable lombok in a javac compilation run, this class should be in the classpath when
+ * running javac; that's the only requirement.
+ */
 @SupportedAnnotationTypes("*")
 @SupportedSourceVersion(SourceVersion.RELEASE_6)
 public class Processor extends AbstractProcessor {