# HG changeset patch
# User Andreas Woess <andreas.woess@oracle.com>
# Date 1442928734 -7200
# Node ID 4eb6f179a326b6869377a030be0911b26241f524
# Parent  5e5b38579bdaac2c6475b9ef9c4c663918308a9c
api.object: add some missing javadoc

diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/DynamicObjectFactory.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/DynamicObjectFactory.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/DynamicObjectFactory.java	Tue Sep 22 15:32:14 2015 +0200
@@ -24,8 +24,24 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * This factory can be used to create a new {@link DynamicObject} from an initial shape, with its
+ * instance properties initialized to the values passed to {@link #newInstance(Object...)}.
+ *
+ * @see Shape#createFactory()
+ */
 public interface DynamicObjectFactory {
+    /**
+     * Create a new {@link DynamicObject} and initialize instance properties with the provided
+     * values. Exactly as many values are required as there are instance properties.
+     *
+     * @param initialValues the values to initialize the object with, in order.
+     * @return a new {@link DynamicObject} initialized with the provided values.
+     */
     DynamicObject newInstance(Object... initialValues);
 
+    /**
+     * @return the shape of objects created by this factory.
+     */
     Shape getShape();
 }
diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutFactory.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutFactory.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LayoutFactory.java	Tue Sep 22 15:32:14 2015 +0200
@@ -24,6 +24,9 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * Implementation class.
+ */
 public interface LayoutFactory {
     Layout createLayout(Layout.Builder layoutBuilder);
 
diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LocationFactory.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LocationFactory.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/LocationFactory.java	Tue Sep 22 15:32:14 2015 +0200
@@ -24,6 +24,11 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * This interface allows to provide a custom location for a given shape and value.
+ *
+ * @see DynamicObject#define(Object, Object, int, LocationFactory)
+ */
 public interface LocationFactory {
     Location createLocation(Shape shape, Object value);
 }
diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ObjectType.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ObjectType.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ObjectType.java	Tue Sep 22 15:32:14 2015 +0200
@@ -30,6 +30,9 @@
 import com.oracle.truffle.api.interop.Message;
 import com.oracle.truffle.api.interop.TruffleObject;
 
+/**
+ * An extensible object type descriptor for {@link DynamicObject}s.
+ */
 public class ObjectType {
     /**
      * Delegate method for {@link DynamicObject#equals(Object)}.
diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Property.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Property.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Property.java	Tue Sep 22 15:32:14 2015 +0200
@@ -32,6 +32,9 @@
     protected Property() {
     }
 
+    /**
+     * Create a new property.
+     */
     public static Property create(Object key, Location location, int flags) {
         return Layout.getFactory().createProperty(key, location, flags);
     }
diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ShapeListener.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ShapeListener.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ShapeListener.java	Tue Sep 22 15:32:14 2015 +0200
@@ -24,6 +24,9 @@
  */
 package com.oracle.truffle.api.object;
 
+/**
+ * A listener to be notified of property transitions.
+ */
 public interface ShapeListener {
     /**
      * Called when a property is added, removed, or replaced.
diff -r 5e5b38579bda -r 4eb6f179a326 truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/package-info.java
--- a/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/package-info.java	Tue Sep 22 14:56:59 2015 +0200
+++ b/truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/package-info.java	Tue Sep 22 15:32:14 2015 +0200
@@ -29,7 +29,8 @@
  )
  */
 
-/** Optimal object model.
+/**
+ * Dynamic object storage model.
  */
 package com.oracle.truffle.api.object;