Updated documentation on @Log and moved them all to lombok.extern.*

6 files changed, 215 insertions, 44 deletions

diff --git a/src/core/lombok/eclipse/handlers/HandleLog.java b/src/core/lombok/eclipse/handlers/HandleLog.java
index dfb45a29..ad0ad200 100644
--- a/src/core/lombok/eclipse/handlers/HandleLog.java
+++ b/src/core/lombok/eclipse/handlers/HandleLog.java
@@ -172,51 +172,51 @@ public class HandleLog {
 	}
 	
 	/**
-	 * Handles the {@link lombok.commons.Log} annotation for Eclipse.
+	 * Handles the {@link lombok.extern.apachecommons.Log} annotation for Eclipse.
 	 */
 	@ProviderFor(EclipseAnnotationHandler.class)
-	public static class HandleCommonsLog implements EclipseAnnotationHandler<lombok.commons.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.commons.Log> annotation, Annotation source, EclipseNode annotationNode) {
+	public static class HandleCommonsLog implements EclipseAnnotationHandler<lombok.extern.apachecommons.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.apachecommons.Log> annotation, Annotation source, EclipseNode annotationNode) {
 			return processAnnotation(LoggingFramework.COMMONS, annotation, source, annotationNode);
 		}
 	}
 	
 	/**
-	 * Handles the {@link lombok.jul.Log} annotation for Eclipse.
+	 * Handles the {@link lombok.extern.jul.Log} annotation for Eclipse.
 	 */
 	@ProviderFor(EclipseAnnotationHandler.class)
-	public static class HandleJulLog implements EclipseAnnotationHandler<lombok.jul.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.jul.Log> annotation, Annotation source, EclipseNode annotationNode) {
+	public static class HandleJulLog implements EclipseAnnotationHandler<lombok.extern.jul.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.jul.Log> annotation, Annotation source, EclipseNode annotationNode) {
 			return processAnnotation(LoggingFramework.JUL, annotation, source, annotationNode);
 		}
 	}
 	
 	/**
-	 * Handles the {@link lombok.log4j.Log} annotation for Eclipse.
+	 * Handles the {@link lombok.extern.log4j.Log} annotation for Eclipse.
 	 */
 	@ProviderFor(EclipseAnnotationHandler.class)
-	public static class HandleLog4jLog implements EclipseAnnotationHandler<lombok.log4j.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.log4j.Log> annotation, Annotation source, EclipseNode annotationNode) {
+	public static class HandleLog4jLog implements EclipseAnnotationHandler<lombok.extern.log4j.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.log4j.Log> annotation, Annotation source, EclipseNode annotationNode) {
 			return processAnnotation(LoggingFramework.LOG4J, annotation, source, annotationNode);
 		}
 	}
 	
 	/**
-	 * Handles the {@link lombok.slf4j.Log} annotation for Eclipse.
+	 * Handles the {@link lombok.extern.slf4j.Log} annotation for Eclipse.
 	 */
 	@ProviderFor(EclipseAnnotationHandler.class)
-	public static class HandleSlf4jLog implements EclipseAnnotationHandler<lombok.slf4j.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.slf4j.Log> annotation, Annotation source, EclipseNode annotationNode) {
+	public static class HandleSlf4jLog implements EclipseAnnotationHandler<lombok.extern.slf4j.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.slf4j.Log> annotation, Annotation source, EclipseNode annotationNode) {
 			return processAnnotation(LoggingFramework.SLF4J, annotation, source, annotationNode);
 		}
 	}
 	
 	enum LoggingFramework {
 		// private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory.getLog(TargetType.class);
-		COMMONS(lombok.jul.Log.class, "org.apache.commons.logging.Log", "org.apache.commons.logging.LogFactory", "getLog"),
+		COMMONS(lombok.extern.jul.Log.class, "org.apache.commons.logging.Log", "org.apache.commons.logging.LogFactory", "getLog"),
 		
 		// private static final java.util.logging.Logger log = java.util.logging.Logger.getLogger(TargetType.class.getName());
-		JUL(lombok.jul.Log.class, "java.util.logging.Logger", "java.util.logging.Logger", "getLogger") {
+		JUL(lombok.extern.jul.Log.class, "java.util.logging.Logger", "java.util.logging.Logger", "getLogger") {
 			@Override public Expression createFactoryParameter(String typeName, Annotation source) {
 				int pS = source.sourceStart, pE = source.sourceEnd;
 				long p = (long)pS << 32 | pE;
@@ -236,10 +236,10 @@ public class HandleLog {
 		},
 		
 		// private static final org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(TargetType.class);
-		LOG4J(lombok.jul.Log.class, "org.apache.log4j.Logger", "org.apache.log4j.Logger", "getLogger"),
+		LOG4J(lombok.extern.jul.Log.class, "org.apache.log4j.Logger", "org.apache.log4j.Logger", "getLogger"),
 
 		// private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(TargetType.class);
-		SLF4J(lombok.slf4j.Log.class, "org.slf4j.Logger", "org.slf4j.LoggerFactory", "getLogger"),
+		SLF4J(lombok.extern.slf4j.Log.class, "org.slf4j.Logger", "org.slf4j.LoggerFactory", "getLogger"),
 		
 		;
 		
diff --git a/src/core/lombok/slf4j/Log.java b/src/core/lombok/extern/apachecommons/Log.java
index 4a82e239..2afc2a6e 100644
--- a/src/core/lombok/slf4j/Log.java
+++ b/src/core/lombok/extern/apachecommons/Log.java
@@ -19,16 +19,59 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package lombok.slf4j;
+package lombok.extern.apachecommons;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Causes lombok to generate a logger field.
+ * Example:
+ * <pre>
+ * &#64;Log
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory.getLog(LogExample.class);
+ * }
+ * </pre>
+ * 
+ * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class.
+ * Example:
+ * <pre>
+ * &#64;Log(java.util.List.class)
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory.getLog(java.util.List.class);
+ * }
+ * </pre>
+ * 
+ * This annotation is valid for classes and enumerations.<br />
+ * 
+ * @see lombok.extern.jul.Log lombok.extern.jul.Log
+ * @see lombok.extern.log4j.Log lombok.extern.log4j.Log
+ * @see lombok.extern.slf4j.Log lombok.extern.slf4j.Log
+ */
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.TYPE)
 public @interface Log {
-	
+	/**
+	 * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class here.
+	 * <br />
+	 * NB: If {@code void.class} is passed, it will be considered the same as specifying no parameter.
+	 */
 	Class<?> value() default void.class;
-}
+}
\ No newline at end of file
diff --git a/src/core/lombok/log4j/Log.java b/src/core/lombok/extern/jul/Log.java
index 6a0e6b0a..c2e7428e 100644
--- a/src/core/lombok/log4j/Log.java
+++ b/src/core/lombok/extern/jul/Log.java
@@ -19,16 +19,59 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package lombok.log4j;
+package lombok.extern.jul;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Causes lombok to generate a logger field.
+ * Example:
+ * <pre>
+ * &#64;Log
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final java.util.logging.Logger log = java.util.logging.Logger.getLogger(LogExample.class.getName());
+ * }
+ * </pre>
+ * 
+ * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class.
+ * Example:
+ * <pre>
+ * &#64;Log(java.util.List.class)
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final java.util.logging.Logger log = java.util.logging.Logger.getLogger(java.util.List.class.getName());
+ * }
+ * </pre>
+ * 
+ * This annotation is valid for classes and enumerations.<br />
+ * 
+ * @see lombok.extern.apachecommons.Log lombok.extern.apachecommons.Log
+ * @see lombok.extern.log4j.Log lombok.extern.log4j.Log
+ * @see lombok.extern.slf4j.Log lombok.extern.slf4j.Log
+ */
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.TYPE)
 public @interface Log {
-	
+	/**
+	 * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class here.
+ 	 * <br />
+	 * NB: If {@code void.class} is passed, it will be considered the same as specifying no parameter.
+	 */
 	Class<?> value() default void.class;
-}
+}
\ No newline at end of file
diff --git a/src/core/lombok/jul/Log.java b/src/core/lombok/extern/log4j/Log.java
index 5d41d1df..e5fcbba0 100644
--- a/src/core/lombok/jul/Log.java
+++ b/src/core/lombok/extern/log4j/Log.java
@@ -19,16 +19,59 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package lombok.jul;
+package lombok.extern.log4j;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Causes lombok to generate a logger field.
+ * Example:
+ * <pre>
+ * &#64;Log
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(LogExample.class);
+ * }
+ * </pre>
+ * 
+ * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class.
+ * Example:
+ * <pre>
+ * &#64;Log(java.util.List.class)
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(java.util.List.class);
+ * }
+ * </pre>
+ * 
+ * This annotation is valid for classes and enumerations.<br />
+ * 
+ * @see lombok.extern.apachecommons.Log lombok.extern.apachecommons.Log
+ * @see lombok.extern.jul.Log lombok.extern.jul.Log
+ * @see lombok.extern.slf4j.Log lombok.extern.slf4j.Log
+ */
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.TYPE)
 public @interface Log {
-	
+	/**
+	 * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class here.
+ 	 * <br />
+	 * NB: If {@code void.class} is passed, it will be considered the same as specifying no parameter.
+	 */
 	Class<?> value() default void.class;
-}
+}
\ No newline at end of file
diff --git a/src/core/lombok/commons/Log.java b/src/core/lombok/extern/slf4j/Log.java
index 974979b7..306ade16 100644
--- a/src/core/lombok/commons/Log.java
+++ b/src/core/lombok/extern/slf4j/Log.java
@@ -19,16 +19,58 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package lombok.commons;
+package lombok.extern.slf4j;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
-
+/**
+ * Causes lombok to generate a logger field.
+ * Example:
+ * <pre>
+ * &#64;Log
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(LogExample.class);
+ * }
+ * </pre>
+ * 
+ * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class.
+ * Example:
+ * <pre>
+ * &#64;Log(java.util.List.class)
+ * public class LogExample {
+ * }
+ * </pre>
+ * 
+ * will generate:
+ * 
+ * <pre>
+ * public class LogExample {
+ *     private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(java.util.List.class); 
+ * }
+ * </pre>
+ * 
+ * This annotation is valid for classes and enumerations.<br />
+ * 
+ * @see lombok.extern.apachecommons.Log lombok.extern.apachecommons.Log
+ * @see lombok.extern.jul.Log lombok.extern.jul.Log
+ * @see lombok.extern.log4j.Log lombok.extern.log4j.Log
+ */
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.TYPE)
 public @interface Log {
-	
+	/**
+	 * If you do not want to use the annotated class as the logger parameter, you can specify an alternate class here.
+ 	 * <br />
+	 * NB: If {@code void.class} is passed, it will be considered the same as specifying no parameter.
+	 */
 	Class<?> value() default void.class;
 }
diff --git a/src/core/lombok/javac/handlers/HandleLog.java b/src/core/lombok/javac/handlers/HandleLog.java
index 014895a1..771f6a2b 100644
--- a/src/core/lombok/javac/handlers/HandleLog.java
+++ b/src/core/lombok/javac/handlers/HandleLog.java
@@ -112,51 +112,51 @@ public class HandleLog {
 	}
 	
 	/**
-	 * Handles the {@link lombok.commons.Log} annotation for javac.
+	 * Handles the {@link lombok.extern.apachecommons.Log} annotation for javac.
 	 */
 	@ProviderFor(JavacAnnotationHandler.class)
-	public static class HandleCommonsLog implements JavacAnnotationHandler<lombok.commons.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.commons.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
+	public static class HandleCommonsLog implements JavacAnnotationHandler<lombok.extern.apachecommons.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.apachecommons.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
 			return processAnnotation(LoggingFramework.COMMONS, annotation, annotationNode);
 		}
 	}
 	
 	/**
-	 * Handles the {@link lombok.jul.Log} annotation for javac.
+	 * Handles the {@link lombok.extern.jul.Log} annotation for javac.
 	 */
 	@ProviderFor(JavacAnnotationHandler.class)
-	public static class HandleJulLog implements JavacAnnotationHandler<lombok.jul.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.jul.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
+	public static class HandleJulLog implements JavacAnnotationHandler<lombok.extern.jul.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.jul.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
 			return processAnnotation(LoggingFramework.JUL, annotation, annotationNode);
 		}
 	}	
 	
 	/**
-	 * Handles the {@link lombok.log4j.Log} annotation for javac.
+	 * Handles the {@link lombok.extern.log4j.Log} annotation for javac.
 	 */
 	@ProviderFor(JavacAnnotationHandler.class)
-	public static class HandleLog4jLog implements JavacAnnotationHandler<lombok.log4j.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.log4j.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
+	public static class HandleLog4jLog implements JavacAnnotationHandler<lombok.extern.log4j.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.log4j.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
 			return processAnnotation(LoggingFramework.LOG4J, annotation, annotationNode);
 		}
 	}
 	
 	/**
-	 * Handles the {@link lombok.slf4j.Log} annotation for javac.
+	 * Handles the {@link lombok.extern.slf4j.Log} annotation for javac.
 	 */
 	@ProviderFor(JavacAnnotationHandler.class)
-	public static class HandleSlf4jLog implements JavacAnnotationHandler<lombok.slf4j.Log> {
-		@Override public boolean handle(AnnotationValues<lombok.slf4j.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
+	public static class HandleSlf4jLog implements JavacAnnotationHandler<lombok.extern.slf4j.Log> {
+		@Override public boolean handle(AnnotationValues<lombok.extern.slf4j.Log> annotation, JCAnnotation ast, JavacNode annotationNode) {
 			return processAnnotation(LoggingFramework.SLF4J, annotation, annotationNode);
 		}
 	}
 	
 	enum LoggingFramework {
 		// private static final org.apache.commons.logging.Log log = org.apache.commons.logging.LogFactory.getLog(TargetType.class);
-		COMMONS(lombok.jul.Log.class, "org.apache.commons.logging.Log", "org.apache.commons.logging.LogFactory.getLog"),
+		COMMONS(lombok.extern.jul.Log.class, "org.apache.commons.logging.Log", "org.apache.commons.logging.LogFactory.getLog"),
 		
 		// private static final java.util.logging.Logger log = java.util.logging.Logger.getLogger(TargetType.class.getName());
-		JUL(lombok.jul.Log.class, "java.util.logging.Logger", "java.util.logging.Logger.getLogger") {
+		JUL(lombok.extern.jul.Log.class, "java.util.logging.Logger", "java.util.logging.Logger.getLogger") {
 			@Override public JCExpression createFactoryParameter(JavacNode typeNode, String typeName) {
 				TreeMaker maker = typeNode.getTreeMaker();
 				JCExpression classAccess = super.createFactoryParameter(typeNode, typeName);
@@ -166,10 +166,10 @@ public class HandleLog {
 		},
 		
 		// private static final org.apache.log4j.Logger log = org.apache.log4j.Logger.getLogger(TargetType.class);
-		LOG4J(lombok.jul.Log.class, "org.apache.log4j.Logger", "org.apache.log4j.Logger.getLogger"),
+		LOG4J(lombok.extern.jul.Log.class, "org.apache.log4j.Logger", "org.apache.log4j.Logger.getLogger"),
 		
 		// private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(TargetType.class);
-		SLF4J(lombok.slf4j.Log.class, "org.slf4j.Logger", "org.slf4j.LoggerFactory.getLogger"),
+		SLF4J(lombok.extern.slf4j.Log.class, "org.slf4j.Logger", "org.slf4j.LoggerFactory.getLogger"),
 		
 		;