Small documentation tweaks.

Readme.md

@@ -308,14 +308,15 @@ User user = UserBuilder.user()
 ```
 
 In addition to the `@Opt` annotation,
-a property will always be considered optional if:
+a property will always be considered optional if either:
 
 * The field or parameter it represents is annotated with a `@Nullable` annotation.
   All types of `@Nullable` annotations are supported,
   including `javax.annotation.Nullable` from [JSR-305](https://mvnrepository.com/artifact/com.google.code.findbugs/jsr305),
   `org.jetbrains.annotations.Nullable` from [JetBrains annotations](https://mvnrepository.com/artifact/org.jetbrains/annotations),
   and others.
-* The field or parameter is of the type `java.util.Optional` introduced in [Java 8](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html).
+* Or, the field or parameter is of the type `java.util.Optional`,
+  introduced in [Java 8](https://docs.oracle.com/javase/8/docs/api/java/util/Optional.html).
 
 ##### 'Staged, but preserving order' Builder style
 

src/main/java/org/jilt/BuilderStyle.java

@@ -316,10 +316,11 @@ public enum BuilderStyle {
      * or if there is a natural order to those properties,
      * like in the {@code FullName} example above.
      * The reason why is that there is only a single spot where a given optional property can be set
-     * (for example, {@code middleName()} above can only be called right after calling {@code firstName()}).
-     * That is different from the {@link #STAGED} style,
+     * (for example, {@code middleName()} above can only be called right after calling {@code firstName()}),
+     * which might make it difficult to find if the class has a large amount of properties without an obvious order to them.
+     * This is different from the {@link #STAGED} style,
      * where all optional properties can be set right before calling {@code build()},
-     * and they can be set in any order, which makes them easier to find.
+     * and they can be set in any order, which makes them more easily discoverable.
      *
      * @see BuilderInterfaces
      * @since 1.4

src/main/java/org/jilt/Opt.java

@@ -16,7 +16,7 @@
  * for the given optional property when constructing an instance of the target class.
  * <p>
  * In addition to using this annotation,
- * a property will also be considered optional if:
+ * a property will also be considered optional if either:
  * <ul>
  *     <li>
  *         The field or parameter it represents is annotated with a {@code @Nullable} annotation.
@@ -25,7 +25,7 @@
  *         and others.
  *     </li>
  *     <li>
- *         The field or parameter is of type {@code java.util.Optional}.
+ *         Or, the field or parameter is of the type {@code java.util.Optional}.
  *     </li>
  * </ul>
  * How exactly does the API for skipping optional properties look like for the consumers of the generated Builder class

src/test/java/org/jilt/test/OptionalsValueTest.java

@@ -10,7 +10,7 @@
 import org.jilt.test.data.optionals.OptionalsWithOrderValueBuilder;
 import org.junit.Test;
 
-import java.util.Arrays;
+import java.util.List;
 import java.util.Optional;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -60,12 +60,13 @@ public void wildcard_optional_uses_java_lang_object_in_unwrapped_setter() {
     }
 
     @Test
-    public void preserving_order_optional_works() {
+    public void null_can_be_passed_to_optional_unwrapped_setter() {
+        List<String> nullList = null;
         OptionalsWithOrderValue<CharSequence> value = OptionalsWithOrderValueBuilder.<CharSequence>optionalsWithOrderValue()
-                .optional(Arrays.asList("a", "b"))
+                .optional(nullList)
                 .v(null)
                 .build();
 
-        assertThat(value.optional).contains(Arrays.asList("a", "b"));
+        assertThat(value.optional).isEmpty();
     }
 }