#414 JavaDoc/README for new IgnoredByEquals and NotInToString annotations

Author: alicederyn

README.md

@@ -506,10 +506,13 @@ abstract class Person {
 
 Note that it is a compile error to leave hashCode abstract if equals is implemented, and vice versa, as FreeBuilder has no reasonable way to ensure the consistency of any implementation it might generate.
 
+If you have a small set of properties you wish to exclude from equals or toString without losing the generated code entirely, you can annotate them `@IgnoredByEquals` and/or `@NotInToString`.
+
 **Warning:**
 It is rarely a good idea to redefine equality on a value type, as it makes testing very hard.
 For instance, `assertEquals` in JUnit relies on equality; it will not know to check individual fields, and as a result, tests may be failing to catch bugs that, on the face of it, they looks like they should be.
 If you are only testing a subset of your fields for equality, consider separating your class in two, as you may have accidentally combined the key and the value of a map into a single object, and you may find your code becomes healthier after the separation.
+Alternatively, creating a custom [Comparator] will make it explicit that you are not using the natural definition of equality.
 
 ### Custom functional interfaces
 

src/main/java/org/inferred/freebuilder/IgnoredByEquals.java

@@ -4,10 +4,22 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.Comparator;
+import java.util.Map;
+import java.util.Set;
 
 /**
- * If present, do not include this property in the generated
- * {@link Object#equals(Object)} and {@link Object#hashCode()}.
+ * {@link FreeBuilder} will not check properties annotated {@code @IgnoredByEquals} when comparing
+ * objects in its generated {@link Object#equals(Object)}.
+ *
+ * <p>To maintain the contract of {@link Object#hashCode()}), the value of these properties will
+ * also be ignored in the generated implementation of that method.
+ *
+ * <p><b>Warning</b>: Dropping properties from equality checks makes it very easy to accidentally
+ * write broken unit tests (and hard to write good ones). If you find yourself wanting to use
+ * this annotation, consider first whether you actually want a different collection type
+ * (typicaly a {@link Map} rather than a {@link Set}, for instance), or whether you can use an
+ * explicit field-ignoring {@link Comparator} in the parts of the code that need it.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.SOURCE)

src/main/java/org/inferred/freebuilder/NotInToString.java

@@ -6,7 +6,8 @@
 import java.lang.annotation.Target;
 
 /**
- * If present, do not include this property in the generated {@link Object#toString()}.
+ * {@link FreeBuilder} will not include properties annotated {@code @NotInToString} in the output of
+ * its generated {@link Object#toString()} implementation.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.SOURCE)