--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/DynamicObject.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/DynamicObject.java	Mon Aug 17 17:40:00 2015 +0200
@@ -27,6 +27,11 @@
 import com.oracle.truffle.api.*;
 import com.oracle.truffle.api.interop.*;
 
+/**
+ * Represents an object members of which can be dynamically added and removed at run time.
+ *
+ * @see Shape
+ */
 public abstract class DynamicObject implements TypedObject, TruffleObject {
     /**
      * Get the object's current shape.
@@ -163,6 +168,12 @@
      */
     public abstract DynamicObject copy(Shape currentShape);
 
+    /**
+     * Represents an operation on a single {@code int}-valued operand that produces an {@code int}
+     * -valued result.
+     *
+     * For Java 7 compatibility (equivalent to IntUnaryOperator).
+     */
     public interface FlagsFunction {
         int apply(int t);
     }

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/FinalLocationException.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/FinalLocationException.java	Mon Aug 17 17:40:00 2015 +0200
@@ -26,6 +26,9 @@
 
 import com.oracle.truffle.api.nodes.*;
 
+/**
+ * This exception is thrown on an attempt to assign a value to a final location.
+ */
 public final class FinalLocationException extends SlowPathException {
     private static final long serialVersionUID = -30188494510914293L;
 }

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/HiddenKey.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/HiddenKey.java	Mon Aug 17 17:40:00 2015 +0200
@@ -24,6 +24,10 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * A unique key to be used for private object fields; excluded from enumeration and compared by
+ * object identity.
+ */
 public final class HiddenKey {
     private final String name;
 

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/IncompatibleLocationException.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/IncompatibleLocationException.java	Mon Aug 17 17:40:00 2015 +0200
@@ -26,6 +26,9 @@
 
 import com.oracle.truffle.api.nodes.*;
 
+/**
+ * This exception is thrown on an attempt to assign an incompatible value to a location.
+ */
 public final class IncompatibleLocationException extends SlowPathException {
     private static final long serialVersionUID = -7734865392357341789L;
 }

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Layout.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Layout.java	Mon Aug 17 17:40:00 2015 +0200
@@ -29,6 +29,11 @@
 import com.oracle.truffle.api.nodes.NodeUtil.FieldOffsetProvider;
 import com.oracle.truffle.api.object.Shape.Allocator;
 
+/**
+ * Describes layout and behavior of a {@link DynamicObject} subclass and is used to create shapes.
+ *
+ * An object may change its shape but only to shapes of the same layout.
+ */
 public abstract class Layout {
     public static final EnumSet<ImplicitCast> NONE = EnumSet.noneOf(ImplicitCast.class);
     public static final EnumSet<ImplicitCast> INT_TO_DOUBLE = EnumSet.of(ImplicitCast.IntToDouble);
@@ -38,6 +43,9 @@
 
     private static final LayoutFactory LAYOUT_FACTORY = loadLayoutFactory();
 
+    /**
+     * Specifies the allowed implicit casts between primitive types without losing type information.
+     */
     public enum ImplicitCast {
         IntToDouble,
         IntToLong,

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutBuilder.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutBuilder.java	Mon Aug 17 17:40:00 2015 +0200
@@ -29,6 +29,11 @@
 import com.oracle.truffle.api.nodes.NodeUtil.FieldOffsetProvider;
 import com.oracle.truffle.api.object.Layout.ImplicitCast;
 
+/**
+ * Layout builder.
+ *
+ * @see Layout
+ */
 public class LayoutBuilder {
     private EnumSet<ImplicitCast> allowedImplicitCasts;
     private FieldOffsetProvider fieldOffsetProvider;

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LocationModifier.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LocationModifier.java	Mon Aug 17 17:40:00 2015 +0200
@@ -24,7 +24,17 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * Location modifiers specify the desired semantics and allowed use of a location to be allocated by
+ * {@link Shape.Allocator}.
+ */
 public enum LocationModifier {
+    /**
+     * Location is going to be set only during object initialization.
+     */
     Final,
+    /**
+     * Location is never set to {@code null} and initialized before it is read.
+     */
     NonNull,
 }

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Shape.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Shape.java	Mon Aug 17 17:40:00 2015 +0200
@@ -284,7 +284,9 @@
     }
 
     /**
-     * Represents a predicate (boolean-valued function) of one argument. For Java 7 compatibility.
+     * Represents a predicate (boolean-valued function) of one argument.
+     *
+     * For Java 7 compatibility (equivalent to Predicate).
      *
      * @param <T> the type of the input to the predicate
      */

--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/TypedLocation.java	Mon Aug 17 16:40:43 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/TypedLocation.java	Mon Aug 17 17:40:00 2015 +0200
@@ -24,6 +24,9 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * A location that can store a value of a particular type.
+ */
 public interface TypedLocation extends BaseLocation {
     /**
      * The type of this location.