Minor code cleanup, add @documented, and add @Format annotation for e…

…xpensive format tasks

src/main/java/org/jboss/logging/Cause.java

@@ -22,17 +22,20 @@
 
 package org.jboss.logging;
 
-import java.lang.annotation.ElementType;
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Mark a parameter as being the "exception cause" parameter rather than a positional format parameter.
  *
  * @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
  */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.PARAMETER)
+@Retention(RUNTIME)
+@Target(PARAMETER)
+@Documented
 public @interface Cause {
 }

src/main/java/org/jboss/logging/Format.java

@@ -0,0 +1,52 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * Copyright 2011, Red Hat Inc., and individual contributors
+ * as indicated by the @author tags. See the copyright.txt file in the
+ * distribution for a full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+
+package org.jboss.logging;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+/**
+ * Indicate that the given parameter should be wrapped with a formatting object of the given class.  The class
+ * must have a one-argument constructor which unambiguously accepts a value of this parameter's type.  The resultant
+ * object will be passed in as a parameter to the underlying format type; thus its {@link Object#toString() toString()}
+ * method will be invoked (or, if the format style is {@link org.jboss.logging.Message.Format#PRINTF PRINTF}, the
+ * object may implement {@link java.util.Formattable Formattable} to get extra functionality).
+ *
+ * @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
+ */
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Documented
+public @interface Format {
+
+    /**
+     * The class of the formatting object to use.
+     *
+     * @return the class
+     */
+    Class<?> value();
+}

src/main/java/org/jboss/logging/LogMessage.java

@@ -22,19 +22,22 @@
 
 package org.jboss.logging;
 
-import java.lang.annotation.ElementType;
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * A typed logger method.  Indicates that this method will log the associated {@link Message} to the logger system, as
  * opposed to being a simple message lookup.
  *
  * @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
  */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.METHOD)
+@Retention(RUNTIME)
+@Target(METHOD)
+@Documented
 public @interface LogMessage {
 
     /**

src/main/java/org/jboss/logging/Message.java

@@ -22,19 +22,22 @@
 
 package org.jboss.logging;
 
-import java.lang.annotation.ElementType;
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Assigns a message string to a resource method.  The method arguments are used to supply the positional parameter
  * values for the method.
  *
  * @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
  */
-@Target(ElementType.METHOD)
-@Retention(RetentionPolicy.RUNTIME)
+@Target(METHOD)
+@Retention(RUNTIME)
+@Documented
 public @interface Message {
 
     /**

src/main/java/org/jboss/logging/MessageBundle.java

@@ -22,18 +22,21 @@
 
 package org.jboss.logging;
 
-import java.lang.annotation.ElementType;
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Signify that an interface is a message bundle interface.
  *
  * @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
  */
-@Target(ElementType.TYPE)
-@Retention(RetentionPolicy.RUNTIME)
+@Target(TYPE)
+@Retention(RUNTIME)
+@Documented
 public @interface MessageBundle {
 
     /**

src/main/java/org/jboss/logging/MessageLogger.java

@@ -22,19 +22,22 @@
 
 package org.jboss.logging;
 
-import java.lang.annotation.ElementType;
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
 /**
  * Signify that an interface is a typed logger interface.  A message logger interface may optionally extend other message logger
  * interfaces and message bundle interfaces (see {@link MessageBundle}, as well as the {@link org.jboss.logging.BasicLogger} interface.
  *
  * @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
  */
-@Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.TYPE)
+@Retention(RUNTIME)
+@Target(TYPE)
+@Documented
 public @interface MessageLogger {
 
     /**