# HG changeset patch
# User Jaroslav Tulach <jaroslav.tulach@oracle.com>
# Date 1449165379 -3600
# Node ID 079cd91831282f30850390354f220eb257314ed5
# Parent  e62921416112d87c09e4295f5a51249c32530260
Documenting and testing some aspects of FrameDescriptor behavior

diff -r e62921416112 -r 079cd9183128 truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/FrameDescriptorTest.java
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/truffle/com.oracle.truffle.api.test/src/com/oracle/truffle/api/FrameDescriptorTest.java	Thu Dec 03 18:56:19 2015 +0100
@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.truffle.api;
+
+import com.oracle.truffle.api.frame.Frame;
+import com.oracle.truffle.api.frame.FrameDescriptor;
+import com.oracle.truffle.api.frame.FrameSlot;
+import com.oracle.truffle.api.frame.FrameSlotTypeException;
+import com.oracle.truffle.api.frame.VirtualFrame;
+import org.junit.Assert;
+import static org.junit.Assert.assertEquals;
+import org.junit.Test;
+
+public class FrameDescriptorTest {
+
+    private FrameSlot s1;
+    private FrameSlot s2;
+    private FrameSlot s3;
+
+    @Test
+    public void localsDefaultValue() throws Exception {
+        Object defaultValue = "default";
+        FrameDescriptor d = new FrameDescriptor(defaultValue);
+        s1 = d.addFrameSlot("v1");
+        s2 = d.addFrameSlot("v2");
+        s3 = d.addFrameSlot("v3");
+        VirtualFrame f = Truffle.getRuntime().createVirtualFrame(new Object[]{1, 2}, d);
+
+        assertFrame(f, d);
+        assertFrame(f.materialize(), d);
+    }
+
+    private void assertFrame(Frame f, FrameDescriptor d) throws FrameSlotTypeException {
+        assertEquals("Three slots", 3, d.getSize());
+        assertEquals("Three slots list", 3, d.getSlots().size());
+        assertEquals("1st slot", d.getSlots().get(0), s1);
+        assertEquals("2nd slot", d.getSlots().get(1), s2);
+        assertEquals("3rd slot", d.getSlots().get(2), s3);
+        assertEquals("default", f.getObject(s1));
+        assertEquals("default", f.getObject(s2));
+        f.setInt(s3, (int) f.getArguments()[0]);
+        assertEquals(1, f.getInt(s3));
+    }
+
+    @Test
+    public void nullDefaultValue() {
+        Assert.assertNull(new FrameDescriptor().getDefaultValue());
+    }
+}
diff -r e62921416112 -r 079cd9183128 truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/FrameDescriptor.java
--- a/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/FrameDescriptor.java	Thu Dec 03 17:28:45 2015 +0100
+++ b/truffle/com.oracle.truffle.api/src/com/oracle/truffle/api/frame/FrameDescriptor.java	Thu Dec 03 18:56:19 2015 +0100
@@ -45,10 +45,18 @@
     private Assumption version;
     private HashMap<Object, Assumption> identifierToNotInFrameAssumptionMap;
 
+    /**
+     * Constructs empty descriptor. The {@link #getDefaultValue()} is <code>null</code>.
+     */
     public FrameDescriptor() {
         this(null);
     }
 
+    /**
+     * Constructs new descriptor with specified {@link #getDefaultValue()}.
+     * 
+     * @param defaultValue to be returned from {@link #getDefaultValue()}
+     */
     public FrameDescriptor(Object defaultValue) {
         CompilerAsserts.neverPartOfCompilation();
         this.defaultValue = defaultValue;
@@ -57,10 +65,24 @@
         version = createVersion();
     }
 
+    /**
+     * Use {@link #FrameDescriptor()}.
+     * 
+     * @return new instance of the descriptor
+     * @deprecated
+     */
+    @Deprecated
     public static FrameDescriptor create() {
         return new FrameDescriptor();
     }
 
+    /**
+     * Use {@link #FrameDescriptor(java.lang.Object) }.
+     * 
+     * @return new instance of the descriptor
+     * @deprecated
+     */
+    @Deprecated
     public static FrameDescriptor create(Object defaultValue) {
         return new FrameDescriptor(defaultValue);
     }
@@ -122,10 +144,20 @@
         getNotInFrameAssumption(identifier);
     }
 
+    /**
+     * Returns number of slots in the descriptor.
+     * 
+     * @return the same value as {@link #getSlots()}.{@link List#size()} would return
+     */
     public int getSize() {
         return slots.size();
     }
 
+    /**
+     * Current set of slots in the descriptor.
+     * 
+     * @return unmodifiable list of {@link FrameSlot}
+     */
     public List<? extends FrameSlot> getSlots() {
         return Collections.unmodifiableList(slots);
     }