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, 59 insertions, 1 deletions

diff --git a/src/lombok/core/SpiLoadUtil.java b/src/lombok/core/SpiLoadUtil.java
index b26dd747..b3b70f27 100644
--- a/src/lombok/core/SpiLoadUtil.java
+++ b/src/lombok/core/SpiLoadUtil.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.io.BufferedReader;
@@ -16,13 +37,44 @@ import java.util.Set;
 
 import lombok.Lombok;
 
+/**
+ * The java core libraries have a SPI discovery system, but it works only in Java 1.6 and up. For at least eclipse,
+ * lombok actually works in java 1.5, so we've rolled our own SPI discovery system.
+ * 
+ * It is not API compatible with <code>ServiceLoader</code>.
+ * 
+ * @see java.util.ServiceLoader
+ */
 public class SpiLoadUtil {
-	private SpiLoadUtil() {}
+	private SpiLoadUtil() {
+		//Prevent instantiation
+	}
 	
+	/**
+	 * Returns an iterator of instances that, at least according to the spi discovery file, are implementations
+	 * of the stated class.
+	 * 
+	 * Like ServiceLoader, each listed class is turned into an instance by calling the public no-args constructor.
+	 * 
+	 * Convenience method that calls the more elaborate {@link #findServices(Class, ClassLoader)} method with
+	 * this {@link java.lang.Thread}'s context class loader as <code>ClassLoader</code>.
+	 * 
+	 * @param target class to find implementations for.
+	 */
 	public static <C> Iterator<C> findServices(Class<C> target) throws IOException {
 		return findServices(target, Thread.currentThread().getContextClassLoader());
 	}
 	
+	/**
+	 * Returns an iterator of class objects that, at least according to the spi discovery file, are implementations
+	 * of the stated class.
+	 * 
+	 * Like ServiceLoader, each listed class is turned into an instance by calling the public no-args constructor.
+	 * 
+	 * @param target class to find implementations for.
+	 * @param loader The classloader object to use to both the spi discovery files, as well as the loader to use
+	 * to make the returned instances.
+	 */
 	public static <C> Iterator<C> findServices(final Class<C> target, final ClassLoader loader) throws IOException {
 		Enumeration<URL> resources = loader.getResources("META-INF/services/" + target.getName());
 		final Set<String> entries = new LinkedHashSet<String>();
@@ -70,6 +122,12 @@ public class SpiLoadUtil {
 		}
 	}
 	
+	/**
+	 * This method will find the <code>T</code> in <code>public class Foo extends BaseType&lt;T&gt;.
+	 * 
+	 * It returns an annotation type because it is used exclusively to figure out which annotations are
+	 * being handled by {@link lombok.eclipse.EclipseAnnotationHandler} and {@link lombok.javac.JavacAnnotationHandler}.
+	 */
 	@SuppressWarnings("unchecked")
 	public static Class<? extends Annotation> findAnnotationClass(Class<?> c, Class<?> base) {
 		if ( c == Object.class || c == null ) return null;