Clarify that Optional values can be set from @Nullable parameters.

This was not all that clear from the documentation. If you have `Optional<String> getFoo()` property then you can set it with `setFoo(String)` _or_ `setFoo(@nullable String)`. In the first case, you'll get an exception if the parameter is null, but in the second it will work, and `foo` will be `Optional.empty()`.

Also add a test that checks that you do indeed get an exception without `@Nullable`.

RELNOTES=n/a
PiperOrigin-RevId: 375607596

Author: eamonnmcmanus

value/src/it/functional/src/test/java/com/google/auto/value/AutoValueTest.java

@@ -1672,6 +1672,13 @@ public void testOmitOptionalWithBuilder() {
             .build();
     assertThat(suppliedDirectly.optionalString()).hasValue("foo");
     assertThat(suppliedDirectly.optionalInteger()).hasValue(23);
+
+    try {
+      // The parameter is not marked @Nullable so this should fail.
+      OptionalPropertiesWithBuilder.builder().setOptionalString((String) null);
+      fail();
+    } catch (NullPointerException expected) {
+    }
   }
 
   @AutoValue

value/userguide/builders-howto.md

@@ -311,7 +311,8 @@ property of type `Optional<String>`, say, then it will default to an empty
 `Optional` without needing to [specify](#default) a default explicitly. And,
 instead of or as well as the normal `setFoo(Optional<String>)` method, you can
 have `setFoo(String)`. Then `setFoo(s)` is equivalent to
-`setFoo(Optional.of(s))`.
+`setFoo(Optional.of(s))`. (If it is `setFoo(@Nullable String)`, then `setFoo(s)`
+is equivalent to `setFoo(Optional.ofNullable(s))`.)
 
 Here, `Optional` means either [`java.util.Optional`] from Java (Java 8 or
 later), or [`com.google.common.base.Optional`] from Guava. Java 8 also