[issue #2039] update docs to warn about a javac peculiarity for named static imports.

2 files changed, 4 insertions, 0 deletions

diff --git a/website/templates/features/Builder.html b/website/templates/features/Builder.html
index 793c7b54..082b97ed 100644
--- a/website/templates/features/Builder.html
+++ b/website/templates/features/Builder.html
@@ -183,6 +183,8 @@ public class JacksonExample {
 			The initializer on a <code>@Builder.Default</code> field is removed and stored in a static method, in order to guarantee that this initializer won't be executed at all if a value is specified in the build. This does mean the initializer cannot refer to <code>this</code>, <code>super</code> or any non-static member. If lombok generates a constructor for you, it'll also initialize this field with the initializer.
 		</p><p>
 			Various well known annotations about nullity cause null checks to be inserted and will be copied to parameter of the builder's 'setter' method. See <a href="/features/GetterSetter">Getter/Setter</a> documentation's small print for more information.
+		</p><p>
+			Due to a peculiar way javac processes static imports, trying to do a non-star static import of the static <code>builder()</code> method won't work. Either use a star static import: `import static TypeThatHasABuilder.*;` or don't statically import the <code>builder</code> method.
 		</p>
 	</@f.smallPrint>
 </@f.scaffold>
diff --git a/website/templates/features/experimental/UtilityClass.html b/website/templates/features/experimental/UtilityClass.html
index 4cee3657..c5f51e29 100644
--- a/website/templates/features/experimental/UtilityClass.html
+++ b/website/templates/features/experimental/UtilityClass.html
@@ -39,6 +39,8 @@
 	<@f.smallPrint>
 		<p>
 			There isn't currently any way to create non-static members, or to define your own constructor. If you want to instantiate the utility class, even only as an internal implementation detail, <code>@UtilityClass</code> cannot be used.
+		</p><p>
+			Due to a peculiar way javac processes static imports, trying to do a non-star static import of any of the members of a `@UtilityClass` won't work. Either use a star static import: `import static TypeMarkedWithUtilityClass.*;` or don't statically import any of the members.
 		</p>
 	</@f.smallPrint>
 </@f.scaffold>