From 58851b4c6e96a51d1ac298c7ed85efac6ffe8335 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Sat, 17 Nov 2012 19:12:01 +0100 Subject: Updated the javadoc of each and every feature annotation that lombok has: * Removed most documentation and instead put in a link to the much more up to date and extensive documentation at http://projectlombok.org/features * Getting ahead of ourselves a little, added notes on onConstructor/onParam/onMethod which we are about to add in the next few commits. * Updated copyrights to 2012. --- src/core/lombok/AllArgsConstructor.java | 10 +++++-- src/core/lombok/Cleanup.java | 13 +++------ src/core/lombok/Data.java | 21 +++++++------- src/core/lombok/Delegate.java | 4 ++- src/core/lombok/EqualsAndHashCode.java | 28 ++---------------- src/core/lombok/Getter.java | 12 ++++---- src/core/lombok/NoArgsConstructor.java | 15 ++++++---- src/core/lombok/RequiredArgsConstructor.java | 8 ++++-- src/core/lombok/Setter.java | 6 ++-- src/core/lombok/SneakyThrows.java | 33 +++++++++------------- src/core/lombok/Synchronized.java | 4 ++- src/core/lombok/ToString.java | 25 ++-------------- src/core/lombok/experimental/Accessors.java | 3 ++ src/core/lombok/experimental/ExtensionMethod.java | 3 ++ src/core/lombok/experimental/FieldDefaults.java | 5 ++-- src/core/lombok/experimental/Value.java | 31 ++++++-------------- src/core/lombok/experimental/Wither.java | 7 +++-- .../lombok/extern/apachecommons/CommonsLog.java | 3 ++ src/core/lombok/extern/java/Log.java | 3 ++ src/core/lombok/extern/log4j/Log4j.java | 3 ++ src/core/lombok/extern/slf4j/Slf4j.java | 3 ++ src/core/lombok/extern/slf4j/XSlf4j.java | 3 ++ src/core/lombok/val.java | 8 ++++-- 23 files changed, 112 insertions(+), 139 deletions(-) (limited to 'src') diff --git a/src/core/lombok/AllArgsConstructor.java b/src/core/lombok/AllArgsConstructor.java index 7e55e4d1..2147bdae 100644 --- a/src/core/lombok/AllArgsConstructor.java +++ b/src/core/lombok/AllArgsConstructor.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2010-2011 The Project Lombok Authors. + * Copyright (C) 2010-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -27,8 +27,12 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Generates an all-args constructor. An all-args constructor requires one argument - * for every field in the class. + * Generates an all-args constructor. + * An all-args constructor requires one argument for every field in the class. + *

+ * Complete documentation is found at the project lombok features page for @Constructor. + *

+ * Even though it is not listed, this annotation also has the {@code onConstructor} parameter. See the full documentation for more details. * * @see NoArgsConstructor * @see RequiredArgsConstructor diff --git a/src/core/lombok/Cleanup.java b/src/core/lombok/Cleanup.java index 7c849038..eb223958 100644 --- a/src/core/lombok/Cleanup.java +++ b/src/core/lombok/Cleanup.java @@ -31,6 +31,8 @@ import java.lang.annotation.Target; * of what happens. Implemented by wrapping all statements following the local variable declaration to the * end of your scope into a try block that, as a finally action, closes the resource. *

+ * Complete documentation is found at the project lombok features page for @Cleanup. + *

* Example: * 

  * public void copyFile(String in, String out) throws IOException {
@@ -59,20 +61,13 @@ import java.lang.annotation.Target;
  *                 outStream.write(b, 0, r);
  *             }
  *         } finally {
- *             out.close();
+ *             if (out != null) out.close();
  *         }
  *     } finally {
- *         in.close();
+ *         if (in != null) in.close();
  *     }
  * }
  *
- * - * Note that the final close method call, if it throws an exception, will overwrite any exception thrown - * in the main body of the generated try block. You should NOT rely on this behaviour - future versions of - * lombok intend to silently swallow any exception thrown by the cleanup method _IF the main body - * throws an exception as well, as the earlier exception is usually far more useful. - *

- * However, in java 1.6, generating the code to do this is prohibitively complicated. */ @Target(ElementType.LOCAL_VARIABLE) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/Data.java b/src/core/lombok/Data.java index dda8b144..ee6f2fcb 100644 --- a/src/core/lombok/Data.java +++ b/src/core/lombok/Data.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009 The Project Lombok Authors. + * Copyright (C) 2009-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -30,17 +30,16 @@ import java.lang.annotation.Target; * Generates getters for all fields, a useful toString method, and hashCode and equals implementations that check * all non-transient fields. Will also generate setters for all non-final fields, as well as a constructor. *

- * If any method to be generated already exists (in name and parameter count - the return type or parameter types are not relevant), then - * that method will not be generated by the Data annotation. + * Equivalent to {@code @Getter @Setter @RequiredArgsConstructor @ToString @EqualsAndHashCode}. *

- * The generated constructor will have 1 parameter for each final field. The generated toString will print all fields, - * while the generated hashCode and equals take into account all non-transient fields.
- * Static fields are skipped (no getter or setter, and they are not included in toString, equals, hashCode, or the constructor). - *

- * {@code toString}, {@code equals}, and {@code hashCode} use the deepX variants in the - * {@code java.util.Arrays} utility class. Therefore, if your class has arrays that contain themselves, - * these methods will just loop endlessly until the inevitable {@code StackOverflowError}. This behaviour - * is no different from {@code java.util.ArrayList}, though. + * Complete documentation is found at the project lombok features page for @Data. + * + * @see Getter + * @see Setter + * @see RequiredArgsConstructor + * @see ToString + * @see EqualsAndHashCode + * @see lombok.experimental.Value */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/Delegate.java b/src/core/lombok/Delegate.java index 9ab9acae..b599e4f0 100644 --- a/src/core/lombok/Delegate.java +++ b/src/core/lombok/Delegate.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2010 The Project Lombok Authors. + * Copyright (C) 2010-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -39,6 +39,8 @@ import java.lang.annotation.Target; * All public instance methods of the field's type, as well as all public instance methods of all the field's type's superfields are delegated, except for all methods * that exist in {@link Object}, the {@code canEqual(Object)} method, and any methods that appear in types * that are listed in the {@code excludes} property. + *

+ * Complete documentation is found at the project lombok features page for @Delegate. */ @Target({ElementType.FIELD, ElementType.METHOD}) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/EqualsAndHashCode.java b/src/core/lombok/EqualsAndHashCode.java index 120cc4d0..8b809c4b 100644 --- a/src/core/lombok/EqualsAndHashCode.java +++ b/src/core/lombok/EqualsAndHashCode.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2010 The Project Lombok Authors. + * Copyright (C) 2009-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -27,31 +27,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Generates implementations for the {@code equals} and {@code hashCode} methods inherited by all objects. + * Generates implementations for the {@code equals} and {@code hashCode} methods inherited by all objects, based on relevant fields. *

- * If either method already exists, then {@code @EqualsAndHashCode} will not generate that particular method. - * If they all exist, {@code @EqualsAndHashCode} generates no methods, and emits a warning instead to highlight - * that its doing nothing at all. The parameter list and return type are not relevant when deciding to skip generation of - * a method; any method named {@code hashCode} will make {@code @EqualsAndHashCode} not generate that method, - * for example. - *

- * By default, all fields that are non-static and non-transient are used in the equality check and hashCode generation. - * You can exclude more fields by specifying them in the {@code exclude} parameter. You can also explicitly specify - * the fields that are to be used by specifying them in the {@code of} parameter. - *

- * Normally, auto-generating {@code hashCode} and {@code equals} implementations in a subclass is a bad idea, as - * the superclass also defines fields, for which equality checks/hashcodes won't be auto-generated. Therefore, a warning - * is emitted when you try. Instead, you can set the {@code callSuper} parameter to true which will call - * {@code super.equals} and {@code super.hashCode}. Doing this with {@code java.lang.Object} as superclass is - * pointless, so, conversely, setting this flag when NOT extending something (other than Object) will also generate - * a warning. Be aware that not all implementations of {@code equals} correctly handle being called from a subclass! - * Fortunately, lombok-generated {@code equals} implementations do correctly handle it. - *

- * Array fields are handled by way of {@link java.util.Arrays#deepEquals(Object[], Object[])} where necessary, as well - * as {@code deepHashCode}. The downside is that arrays with circular references (arrays that contain themselves, - * possibly indirectly) results in calls to {@code hashCode} and {@code equals} throwing a - * {@link java.lang.StackOverflowError}. However, the implementations for java's own {@link java.util.ArrayList} suffer - * from the same flaw. + * Complete documentation is found at the project lombok features page for @EqualsAndHashCode. */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/Getter.java b/src/core/lombok/Getter.java index 3a92f67a..fa12ce1b 100644 --- a/src/core/lombok/Getter.java +++ b/src/core/lombok/Getter.java @@ -28,7 +28,11 @@ import java.lang.annotation.Target; /** * Put on any field to make lombok build a standard getter. - * + *

+ * Complete documentation is found at the project lombok features page for @Getter and @Setter. + *

+ * Even though it is not listed, this annotation also has the {@code onMethod} parameter. See the full documentation for more details. + *

* Example: * 

  *     private @Getter int foo;
@@ -41,12 +45,6 @@ import java.lang.annotation.Target;
  *         return this.foo;
  *     }
  *
- * - * Note that fields of type {@code boolean} (but not {@code java.lang.Boolean}) will result in an - * {@code isFoo} name instead of {@code getFoo}. - *

- * If any method named {@code getFoo}/{@code isFoo} (case insensitive) exists, regardless of return type or parameters, - * no method is generated, and instead a compiler warning is emitted. *

* This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have * a {@code @Getter} annotation have the annotation. diff --git a/src/core/lombok/NoArgsConstructor.java b/src/core/lombok/NoArgsConstructor.java index 985225f7..ba53e39f 100644 --- a/src/core/lombok/NoArgsConstructor.java +++ b/src/core/lombok/NoArgsConstructor.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2010-2011 The Project Lombok Authors. + * Copyright (C) 2010-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -27,11 +27,14 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Generates a no-args constructor. Will generate an error message if such - * a constructor cannot be written due to the existence of final fields. - * - * NB: Fields with constraints such as {@code @NonNull} will NOT be checked - * in such a constructor, of course! + * Generates a no-args constructor. + * Will generate an error message if such a constructor cannot be written due to the existence of final fields. + *

+ * Complete documentation is found at the project lombok features page for @Constructor. + *

+ * Even though it is not listed, this annotation also has the {@code onConstructor} parameter. See the full documentation for more details. + *

+ * NB: Fields with constraints such as {@code @NonNull} will NOT be checked in a {@code @NoArgsConstructor} constructor, of course! * * @see RequiredArgsConstructor * @see AllArgsConstructor diff --git a/src/core/lombok/RequiredArgsConstructor.java b/src/core/lombok/RequiredArgsConstructor.java index da2d1e15..afe9773e 100644 --- a/src/core/lombok/RequiredArgsConstructor.java +++ b/src/core/lombok/RequiredArgsConstructor.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2010-2011 The Project Lombok Authors. + * Copyright (C) 2010-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -29,7 +29,11 @@ import java.lang.annotation.Target; /** * Generates a constructor with required arguments. * Required arguments are final fields and fields with constraints such as {@code @NonNull}. - * + *

+ * Complete documentation is found at the project lombok features page for @Constructor. + *

+ * Even though it is not listed, this annotation also has the {@code onConstructor} parameter. See the full documentation for more details. + * * @see NoArgsConstructor * @see AllArgsConstructor */ diff --git a/src/core/lombok/Setter.java b/src/core/lombok/Setter.java index a7318259..59ed9346 100644 --- a/src/core/lombok/Setter.java +++ b/src/core/lombok/Setter.java @@ -29,6 +29,10 @@ import java.lang.annotation.Target; /** * Put on any field to make lombok build a standard setter. *

+ * Complete documentation is found at the project lombok features page for @Getter and @Setter. + *

+ * Even though it is not listed, this annotation also has the {@code onParam} and {@code onMethod} parameter. See the full documentation for more details. + *

* Example: * 

  *     private @Setter int foo;
@@ -42,8 +46,6 @@ import java.lang.annotation.Target;
  *     }
  *
* - * If any method named {@code setFoo} (case insensitive) exists, regardless of return type or parameters, - * no method is generated, and instead a compiler warning is emitted. *

* This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have * a {@code Setter} annotation have the annotation. diff --git a/src/core/lombok/SneakyThrows.java b/src/core/lombok/SneakyThrows.java index d1ffa5b6..4bd79065 100644 --- a/src/core/lombok/SneakyThrows.java +++ b/src/core/lombok/SneakyThrows.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009 The Project Lombok Authors. + * Copyright (C) 2009-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -34,21 +34,7 @@ import java.lang.annotation.Target; * checked exception types. The JVM does not check for the consistency of the checked exception system; javac does, * and this annotation lets you opt out of its mechanism. *

- * You should use this annotation ONLY in the following two cases:

    - *
  1. You are certain the listed exception can't actually ever happen, or only in vanishingly rare situations. - * You don't try to catch OutOfMemoryError on every statement either. Examples:
    - * {@code IOException} in {@code ByteArrayOutputStream}
    - * {@code UnsupportedEncodingException} in new String(byteArray, "UTF-8").
    2. - *
  2. You know for certain the caller can handle the exception (for example, because the caller is - * an app manager that will handle all throwables that fall out of your method the same way), but due - * to interface restrictions you can't just add these exceptions to your 'throws' clause. - *

    - * Note that, as SneakyThrow is an implementation detail and NOT part of your method signature, it is - * a compile time error if none of the statements in your method body can throw a listed exception. - *

    - * WARNING: You must have lombok.jar available at the runtime of your app if you use SneakyThrows, - * because your code is rewritten to use {@link Lombok#sneakyThrow(Throwable)}. - *

    + * Complete documentation is found at the project lombok features page for @SneakyThrows. *

    * Example: * 

    @@ -58,10 +44,17 @@ import java.lang.annotation.Target;
  * }
  *
    * - * {@code @SneakyThrows} without a parameter defaults to allowing every checked exception. - * (The default is {@code Throwable.class}). - * - * @see Lombok#sneakyThrow(Throwable) + * Becomes: + * 
    + * public void utf8ToString(byte[] bytes) {
+ *     try {
+ *         return new String(bytes, "UTF-8");
+ *     } catch (UnsupportedEncodingException $uniqueName) {
+ *         throw useMagicTrickeryToHideThisFromTheCompiler($uniqueName);
+ *         // This trickery involves a bytecode transformer run automatically during the final stages of compilation;
+ *         // there is no runtime dependency on lombok.
+ *     }
+ *
    */ @Target({ElementType.METHOD, ElementType.CONSTRUCTOR}) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/Synchronized.java b/src/core/lombok/Synchronized.java index dbccbbf9..fadea89a 100644 --- a/src/core/lombok/Synchronized.java +++ b/src/core/lombok/Synchronized.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2011 The Project Lombok Authors. + * Copyright (C) 2009-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -34,6 +34,8 @@ import java.lang.annotation.Target; * For non-static methods, a field named {@code $lock} is used, and for static methods, * {@code $LOCK} is used. These will be generated if needed and if they aren't already present. The contents * of the fields will be serializable. + *

    + * Complete documentation is found at the project lombok features page for @Synchronized. */ @Target(ElementType.METHOD) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/ToString.java b/src/core/lombok/ToString.java index 326dcdab..e39b9858 100644 --- a/src/core/lombok/ToString.java +++ b/src/core/lombok/ToString.java @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2010 The Project Lombok Authors. + * Copyright (C) 2009-2012 The Project Lombok Authors. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal @@ -27,28 +27,9 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Generates an implementation for the {@code toString} method inherited by all objects. + * Generates an implementation for the {@code toString} method inherited by all objects, consisting of printing the values of relevant fields. *

    - * If the method already exists, then {@code ToString} will not generate any method, and instead warns - * that it's doing nothing at all. The parameter list and return type are not relevant when deciding to skip generation of - * the method; any method named {@code toString} will make {@code ToString} not generate anything. - *

    - * By default, all fields that are non-static are used in the toString generation. You can exclude fields by specifying them - * in the {@code exclude} parameter. You can also explicitly specify the fields that - * are to be used by specifying them in the {@code of} parameter. - *

    - * Array fields are handled by way of {@link java.util.Arrays#deepToString(Object[])} where necessary. - * The downside is that arrays with circular references (arrays that contain themselves, - * possibly indirectly) results in calls to {@code toString} throwing a - * {@link java.lang.StackOverflowError}. However, the implementations for java's own {@link java.util.ArrayList} suffer - * from the same flaw. - *

    - * The {@code toString} method that is generated will print the class name as well as each field (both the name - * and the value). You can optionally choose to suppress the printing of the field name, by setting the - * {@code includeFieldNames} flag to false. - *

    - * You can also choose to include the result of {@code toString} in your class's superclass by setting the - * {@code callSuper} to true. + * Complete documentation is found at the project lombok features page for @ToString. */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.SOURCE) diff --git a/src/core/lombok/experimental/Accessors.java b/src/core/lombok/experimental/Accessors.java index b925e746..2748bfa9 100644 --- a/src/core/lombok/experimental/Accessors.java +++ b/src/core/lombok/experimental/Accessors.java @@ -28,6 +28,9 @@ import java.lang.annotation.Target; /** * A container for settings for the generation of getters and setters. + *

    + * Complete documentation is found at the project lombok features page for @Accessors. + *

    * Using this annotation does nothing by itself; an annotation that makes lombok generate getters and setters, * such as {@link lombok.Setter} or {@link lombok.Data} is also required. */ diff --git a/src/core/lombok/experimental/ExtensionMethod.java b/src/core/lombok/experimental/ExtensionMethod.java index 74787fac..44f28d04 100644 --- a/src/core/lombok/experimental/ExtensionMethod.java +++ b/src/core/lombok/experimental/ExtensionMethod.java @@ -31,6 +31,9 @@ import java.lang.annotation.*; * otherwise modifying the original type. Extension methods are a special kind of static method, but they are called as * if they were instance methods on the extended type. *

    + * Complete documentation is found at the project lombok features page for @ExtensionMethod. + *

    + *

    * Before: * * 

    diff --git a/src/core/lombok/experimental/FieldDefaults.java b/src/core/lombok/experimental/FieldDefaults.java
index 5bbf92dc..8a3fb534 100644
--- a/src/core/lombok/experimental/FieldDefaults.java
+++ b/src/core/lombok/experimental/FieldDefaults.java
@@ -30,12 +30,13 @@ import lombok.AccessLevel;
 
 /**
  * Adds modifiers to each field in the type with this annotation.
+ * 
    
+ * Complete documentation is found at the project lombok features page for @FieldDefaults.
+ * 
    
  * If {@code makeFinal} is {@code true}, then each field that is not annotated with {@code @NonFinal} will have the {@code final} modifier added.
  * 
    
  * If {@code level} is set, then each field that is package private (i.e. no access modifier) and does not have the {@code @PackagePrivate} annotation will
  * have the appropriate access level modifier added.
- * 
    
- * The only fields that are skipped are those that start with a '$'; everything else, including static, volatile, and transient fields, are modified.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.SOURCE)
diff --git a/src/core/lombok/experimental/Value.java b/src/core/lombok/experimental/Value.java
index 70ac1ba7..6c07d2fc 100644
--- a/src/core/lombok/experimental/Value.java
+++ b/src/core/lombok/experimental/Value.java
@@ -28,30 +28,17 @@ import java.lang.annotation.Target;
 
 /**
  * Generates a lot of code which fits with a class that is a representation of an immutable entity.
- * Specifically, it generates:
      
- * 
    • Getters for all fields
- * 
    • toString method
- * 
    • hashCode and equals implementations that check all non-transient fields.
- * 
    • Generates withers for all fields (except final fields that are initialized in the field declaration itself)
- * 
    • Generates a constructor for each argument
- * 
    • Adds {@code private} and {@code final} to each field.
- * 
    • Makes the class itself final.
- * 
    
- * 
- * In other words, {@code @Value} is a shorthand for:
    
- * {@code final @Getter @Wither @FieldDefaults(makeFinal=true,level=AccessLevel.PRIVATE) @EqualsAndHashCode @ToString @AllArgsConstructor}.
- * 
    
- * If any method to be generated already exists (in name and parameter count - the return type or parameter types are not relevant), then
- * that method will not be generated by the Value annotation.
  * 
    
- * The generated constructor will have 1 parameter for each field. The generated toString will print all fields,
- * while the generated hashCode and equals take into account all non-transient fields.
    
- * Static fields are skipped (no getter or setter, and they are not included in toString, equals, hashCode, or the constructor).
+ * Equivalent to {@code @Getter @Wither @FieldDefaults(makeFinal=true, level=AccessLevel.PRIVATE) @RequiredArgsConstructor @ToString @EqualsAndHashCode}.
  * 
    
- * {@code toString}, {@code equals}, and {@code hashCode} use the deepX variants in the
- * {@code java.util.Arrays} utility class. Therefore, if your class has arrays that contain themselves,
- * these methods will just loop endlessly until the inevitable {@code StackOverflowError}. This behaviour
- * is no different from {@code java.util.ArrayList}, though.
+ * Complete documentation is found at the project lombok features page for @Value.
+ * 
+ * @see lombok.Getter
+ * @see Wither
+ * @see lombok.RequiredArgsConstructor
+ * @see lombok.ToString
+ * @see lombok.EqualsAndHashCode
+ * @see lombok.Data
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.SOURCE)
diff --git a/src/core/lombok/experimental/Wither.java b/src/core/lombok/experimental/Wither.java
index ec2f5496..58be660a 100644
--- a/src/core/lombok/experimental/Wither.java
+++ b/src/core/lombok/experimental/Wither.java
@@ -31,6 +31,10 @@ import lombok.AccessLevel;
 /**
  * Put on any field to make lombok build a 'wither' - a withX method which produces a clone of this object (except for 1 field which gets a new value).
  * 
    
+ * Complete documentation is found at the project lombok features page for @Wither.
+ * 
    
+ * Even though it is not listed, this annotation also has the {@code onParam} and {@code onMethod} parameter. See the full documentation for more details.
+ * 
    
  * Example:
  * 
      *     private @Wither final int foo;
@@ -43,9 +47,6 @@ import lombok.AccessLevel;
  *         return this.foo == foo ? this : new SELF_TYPE(otherField1, otherField2, foo);
  *     }
  * 
    
- * 
- * If any method named {@code withFoo} (case insensitive) exists, regardless of return type or parameters,
- * no method is generated, and instead a compiler warning is emitted.
  * 
    
  * This annotation can also be applied to a class, in which case it'll be as if all non-static fields that don't already have
  * a {@code Wither} annotation have the annotation.
diff --git a/src/core/lombok/extern/apachecommons/CommonsLog.java b/src/core/lombok/extern/apachecommons/CommonsLog.java
index 3fb178c7..f178ae05 100644
--- a/src/core/lombok/extern/apachecommons/CommonsLog.java
+++ b/src/core/lombok/extern/apachecommons/CommonsLog.java
@@ -28,6 +28,9 @@ import java.lang.annotation.Target;
 
 /**
  * Causes lombok to generate a logger field.
+ * 
    
+ * Complete documentation is found at the project lombok features page for lombok log annotations.
+ * 
    
  * Example:
  * 
      * @CommonsLog
diff --git a/src/core/lombok/extern/java/Log.java b/src/core/lombok/extern/java/Log.java
index dba83c60..90c62956 100644
--- a/src/core/lombok/extern/java/Log.java
+++ b/src/core/lombok/extern/java/Log.java
@@ -28,6 +28,9 @@ import java.lang.annotation.Target;
 
 /**
  * Causes lombok to generate a logger field.
+ * 
    
+ * Complete documentation is found at the project lombok features page for lombok log annotations.
+ * 
    
  * Example:
  * 
      * @Log
diff --git a/src/core/lombok/extern/log4j/Log4j.java b/src/core/lombok/extern/log4j/Log4j.java
index 3de291b6..9cfc5839 100644
--- a/src/core/lombok/extern/log4j/Log4j.java
+++ b/src/core/lombok/extern/log4j/Log4j.java
@@ -28,6 +28,9 @@ import java.lang.annotation.Target;
 
 /**
  * Causes lombok to generate a logger field.
+ * 
    
+ * Complete documentation is found at the project lombok features page for lombok log annotations.
+ * 
    
  * Example:
  * 
      * @Log4j
diff --git a/src/core/lombok/extern/slf4j/Slf4j.java b/src/core/lombok/extern/slf4j/Slf4j.java
index fababb83..14dbcba6 100644
--- a/src/core/lombok/extern/slf4j/Slf4j.java
+++ b/src/core/lombok/extern/slf4j/Slf4j.java
@@ -27,6 +27,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 /**
  * Causes lombok to generate a logger field.
+ * 
    
+ * Complete documentation is found at the project lombok features page for lombok log annotations.
+ * 
    
  * Example:
  * 
      * @Slf4j
diff --git a/src/core/lombok/extern/slf4j/XSlf4j.java b/src/core/lombok/extern/slf4j/XSlf4j.java
index 73fbd74c..bdf8a62c 100644
--- a/src/core/lombok/extern/slf4j/XSlf4j.java
+++ b/src/core/lombok/extern/slf4j/XSlf4j.java
@@ -27,6 +27,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 /**
  * Causes lombok to generate a logger field.
+ * 
    
+ * Complete documentation is found at the project lombok features page for lombok log annotations.
+ * 
    
  * Example:
  * 
      * @XSlf4j
diff --git a/src/core/lombok/val.java b/src/core/lombok/val.java
index e2a56f1c..7e495c8d 100644
--- a/src/core/lombok/val.java
+++ b/src/core/lombok/val.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2010 The Project Lombok Authors.
+ * Copyright (C) 2010-2012 The Project Lombok Authors.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -25,7 +25,9 @@ package lombok;
  * Use {@code val} as the type of any local variable declaration (even in a for-each statement), and the type will be inferred from the initializing expression.
  * For example: {@code val x = 10.0;} will infer {@code double}, and {@code val y = new ArrayList();} will infer {@code ArrayList}. The local variable
  * will also be made final.
- * 
- * Note that this is an interface because {@code val x = 10;} will be desugared to {@code @val int x = 10;}
+ * 
    
+ * Note that this is an annotation type because {@code val x = 10;} will be desugared to {@code @val final int x = 10;}
+ * 
    
+ * Complete documentation is found at the project lombok features page for @val.
  */
 public @interface val {}
-- 
cgit