Merge pull request #5 from smarr/pr/object-mode-comments

Improved documentation of some object model classes

Author: woess

truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Layout.java

@@ -65,11 +65,30 @@ public static Layout createLayout() {
 
     public abstract Class<? extends DynamicObject> getType();
 
-    public abstract Shape createShape(ObjectType operations);
+    /**
+     * Create a root shape.
+     *
+     * @param objectType that describes the object instance with this shape.
+     */
+    public abstract Shape createShape(ObjectType objectType);
 
-    public abstract Shape createShape(ObjectType operations, Object sharedData);
+    /**
+     * Create a root shape.
+     *
+     * @param objectType that describes the object instance with this shape.
+     * @param sharedData for language-specific use
+     */
+    public abstract Shape createShape(ObjectType objectType, Object sharedData);
 
-    public abstract Shape createShape(ObjectType operations, Object sharedData, int id);
+    /**
+     * Create a root shape.
+     *
+     * @param objectType that describes the object instance with this shape.
+     * @param sharedData for language-specific use
+     * @param id for language-specific use
+     * @return
+     */
+    public abstract Shape createShape(ObjectType objectType, Object sharedData, int id);
 
     /**
      * Create an allocator for static property creation. Reserves all array extension slots.

truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Location.java

@@ -125,7 +125,7 @@ public final void set(DynamicObject store, Object value) throws IncompatibleLoca
     protected abstract void setInternal(DynamicObject store, Object value) throws IncompatibleLocationException;
 
     /**
-     * Returns {@code true} if the location can be set to the value.
+     * Returns {@code true} if the location can be set to the given value.
      *
      * @param store the receiver object
      * @param value the value in question
@@ -144,9 +144,10 @@ public boolean canSet(Object value) {
     }
 
     /**
-     * Returns {@code true} if the location is compatible with the value.
+     * Returns {@code true} if the location is compatible with the type of the value.
      *
-     * The value may still be rejected if {@link #canSet(DynamicObject, Object)} returns false.
+     * The actual value may still be rejected if {@link #canSet(DynamicObject, Object)} returns
+     * false.
      *
      * @param value the value in question
      */

truffle/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/Property.java

@@ -34,6 +34,8 @@ protected Property() {
 
     /**
      * Create a new property.
+     *
+     * @param flags, for language-specific use
      */
     public static Property create(Object key, Location location, int flags) {
         return Layout.getFactory().createProperty(key, location, flags);
@@ -45,7 +47,7 @@ public static Property create(Object key, Location location, int flags) {
     public abstract Object getKey();
 
     /**
-     * Get property flags.
+     * Get property flags, which are free for language-specific use.
      */
     public abstract int getFlags();
 

truffle/com.oracle.truffle.object.basic/src/com/oracle/truffle/object/basic/BasicLayout.java

@@ -62,8 +62,8 @@ public DynamicObject newInstance(Shape shape) {
     }
 
     @Override
-    public Shape createShape(ObjectType operations, Object sharedData, int id) {
-        return new ShapeBasic(this, sharedData, operations, id);
+    public Shape createShape(ObjectType objectType, Object sharedData, int id) {
+        return new ShapeBasic(this, sharedData, objectType, id);
     }
 
     @Override

truffle/com.oracle.truffle.object.basic/src/com/oracle/truffle/object/basic/ShapeBasic.java

@@ -29,8 +29,8 @@
 import com.oracle.truffle.object.Transition;
 
 public final class ShapeBasic extends ShapeImpl {
-    public ShapeBasic(Layout layout, Object sharedData, ObjectType operations, int id) {
-        super(layout, operations, sharedData, id);
+    public ShapeBasic(Layout layout, Object sharedData, ObjectType objectType, int id) {
+        super(layout, objectType, sharedData, id);
     }
 
     public ShapeBasic(Layout layout, Object sharedData, ShapeImpl parent, ObjectType objectType, PropertyMap propertyMap, Transition transition, Allocator allocator, int id) {

truffle/com.oracle.truffle.object/src/com/oracle/truffle/object/LayoutImpl.java

@@ -68,13 +68,13 @@ public Class<? extends DynamicObject> getType() {
     }
 
     @Override
-    public final Shape createShape(ObjectType operations, Object sharedData) {
-        return createShape(operations, sharedData, 0);
+    public final Shape createShape(ObjectType objectType, Object sharedData) {
+        return createShape(objectType, sharedData, 0);
     }
 
     @Override
-    public final Shape createShape(ObjectType operations) {
-        return createShape(operations, null);
+    public final Shape createShape(ObjectType objectType) {
+        return createShape(objectType, null);
     }
 
     public boolean isAllowedIntToDouble() {