[GR-7923] Javadoc updated with deterministic iteration order of varia…

…bles and arguments. PullRequest: graal/966
argan · Jan 31, 2018 · 223d702 · 223d702
2 parents e5bea41 + 8412a04
commit 223d702
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 1 deletion.
diff --git a/truffle/src/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java b/truffle/src/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/Message.java
@@ -519,7 +519,7 @@ public static Message createNew(int argumentsLength) {
      * <p>
      * The return value from using this message is another {@link TruffleObject} that responds to
      * {@link #HAS_SIZE} message and its indexes 0 to {@link #GET_SIZE} - 1 contain {@link String}
-     * names of individual properties.
+     * names of individual properties. The properties should be provided in deterministic order.
      *
      * @since 0.18
      */

diff --git a/truffle/src/com.oracle.truffle.api/src/com/oracle/truffle/api/Scope.java b/truffle/src/com.oracle.truffle.api/src/com/oracle/truffle/api/Scope.java
@@ -63,6 +63,9 @@ private Scope() {
 
     /**
      * Create a new Scope builder.
+     * <p>
+     * The properties representing the variables needs to have deterministic iteration order,
+     * variable declaration order is recommended.
      *
      * @param name name of the scope, a name description like block, name of a function, closure,
      *            script, module, etc.
@@ -98,6 +101,9 @@ public Node getNode() {
      * Get variables declared in this scope. When a {@link Node} (and a {@link Frame}) was provided
      * when this scope was obtained, variables are valid at that specified {@link Node} (and
      * {@link Frame}).
+     * <p>
+     * The properties representing the variables have deterministic iteration order, variable
+     * declaration order is preferred.
      *
      * @return A {@link com.oracle.truffle.api.interop.TruffleObject} containing the variables as
      *         its properties, never <code>null</code>.
@@ -110,6 +116,9 @@ public Object getVariables() {
     /**
      * Get arguments of this scope. There might be different arguments returned in local scopes when
      * different {@link Frame} instances were provided.
+     * <p>
+     * The properties representing the arguments have deterministic iteration order, argument
+     * declaration order is preferred.
      *
      * @return A {@link com.oracle.truffle.api.interop.TruffleObject} containing the arguments as
      *         its properties for named arguments, or as its array for unnamed arguments. A
@@ -156,6 +165,9 @@ public Builder node(Node node) {
 
         /**
          * Set arguments of the scope.
+         * <p>
+         * The properties representing the arguments needs to have deterministic iteration order,
+         * argument declaration order is recommended.
          *
          * @param arguments arguments of the scope
          * @since 0.30