add commentary on RArguments

com.oracle.truffle.r.runtime/src/com/oracle/truffle/r/runtime/RArguments.java

@@ -25,11 +25,30 @@ package com.oracle.truffle.r.runtime;
 import com.oracle.truffle.api.frame.*;
 import com.oracle.truffle.r.runtime.data.*;
 
+// @formatter:off
 /**
  * Provide access to arguments contained in frames. This is a purely static class. It defines, by
  * means of slot offsets, where in a frame certain information is stored, such as the function
  * executed in the frame.
+ *
+ * The frame layout, depicted, is as follows:
+ * <pre>
+ *                          +-------------------+
+ * INDEX_FUNCTION        -> | RFunction         |
+ *                          +-------------------+
+ * INDEX_ENCLOSING_FRAME -> | MaterializedFrame |
+ *                          +-------------------+
+ * INDEX_ARGUMENTS       -> | Object[]          |
+ *                          +-------------------+
+ * INDEX_NAMES           -> | Object[]          |
+ *                          +-------------------+
+ * </pre>
+ *
+ * All frame elements should <b>always</b> be accessed through the getter and setter functions
+ * defined in this class, as they provide a means of accessing the frame contents that is
+ * transparent to layout changes.
  */
+// @formatter:on
 public final class RArguments {
 
     public static final Object[] EMPTY_OBJECT_ARRAY = new Object[0];
@@ -42,10 +61,6 @@ public final class RArguments {
     private RArguments() {
     }
 
-    public static RFunction getFunction(Frame frame) {
-        return (RFunction) frame.getArguments()[INDEX_FUNCTION];
-    }
-
     public static Object[] create() {
         return create(null, null, EMPTY_OBJECT_ARRAY);
     }
@@ -66,6 +81,10 @@ public final class RArguments {
         return new Object[]{functionObj, enclosingFrame, evaluatedArgs, names};
     }
 
+    public static RFunction getFunction(Frame frame) {
+        return (RFunction) frame.getArguments()[INDEX_FUNCTION];
+    }
+
     public static Object[] getArgumentsArray(Frame frame) {
         return (Object[]) frame.getArguments()[INDEX_ARGUMENTS];
     }