--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Layout.java	Mon Sep 14 13:43:21 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Layout.java	Mon Sep 14 13:40:10 2015 +0200
@@ -24,9 +24,9 @@
  */
 package com.oracle.truffle.api.object;
 
-import java.util.*;
+import java.util.EnumSet;
+import java.util.ServiceLoader;
 
-import com.oracle.truffle.api.nodes.NodeUtil.FieldOffsetProvider;
 import com.oracle.truffle.api.object.Shape.Allocator;
 
 /**
@@ -51,16 +51,28 @@
         IntToLong,
     }
 
+    /**
+     * Create a new {@link LayoutBuilder}.
+     */
+    @SuppressWarnings("deprecation")
+    public static LayoutBuilder newLayout() {
+        return new LayoutBuilder();
+    }
+
+    /**
+     * Equivalent to {@code Layout.newLayout().build()}.
+     */
     public static Layout createLayout() {
         return createLayout(NONE);
     }
 
+    /**
+     * Equivalent to
+     * {@code Layout.newLayout().setAllowedImplicitCasts(allowedImplicitCasts).build()}.
+     */
+    @Deprecated
     public static Layout createLayout(EnumSet<ImplicitCast> allowedImplicitCasts) {
-        return new LayoutBuilder().setAllowedImplicitCasts(allowedImplicitCasts).build();
-    }
-
-    public static Layout createLayout(EnumSet<ImplicitCast> allowedImplicitCasts, FieldOffsetProvider fieldOffsetProvider) {
-        return new LayoutBuilder().setAllowedImplicitCasts(allowedImplicitCasts).setFieldOffsetProvider(fieldOffsetProvider).build();
+        return newLayout().setAllowedImplicitCasts(allowedImplicitCasts).build();
     }
 
     public abstract DynamicObject newInstance(Shape shape);

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutBuilder.java	Mon Sep 14 13:43:21 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutBuilder.java	Mon Sep 14 13:40:10 2015 +0200
@@ -38,20 +38,35 @@
     private EnumSet<ImplicitCast> allowedImplicitCasts;
     private FieldOffsetProvider fieldOffsetProvider;
 
+    /**
+     * Use {@link Layout#newLayout()} instead.
+     */
+    @Deprecated
     public LayoutBuilder() {
         this.allowedImplicitCasts = Layout.NONE;
         this.fieldOffsetProvider = null;
     }
 
+    /**
+     * Build {@link Layout} from the configuration in this builder.
+     */
     public Layout build() {
         return Layout.getFactory().createLayout(this);
     }
 
+    /**
+     * Set the allowed implicit casts in this layout.
+     *
+     * @see Layout.ImplicitCast
+     */
     public LayoutBuilder setAllowedImplicitCasts(EnumSet<ImplicitCast> allowedImplicitCasts) {
         this.allowedImplicitCasts = allowedImplicitCasts;
         return this;
     }
 
+    /**
+     * Set a custom field offset provider for this layout.
+     */
     public LayoutBuilder setFieldOffsetProvider(FieldOffsetProvider fieldOffsetProvider) {
         this.fieldOffsetProvider = fieldOffsetProvider;
         return this;