Add docs and fix style

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/base/DoCall.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2021, 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
@@ -207,8 +207,8 @@ public Object doSlowPathInEvalFrame(VirtualFrame virtualFrame, String funcName,
         /**
          * The contract is that the function call will be evaluated in the given environment, but at
          * the same time some primitives expect to see {@code do.call(foo, ...)} as the caller, so
-         * we create a frame that fakes the caller, but otherwise delegates to the frame backing
-         * the explicitly given environment.
+         * we create a frame that fakes the caller, but otherwise delegates to the frame backing the
+         * explicitly given environment.
          *
          * @param currentFrame the current materialized frame, which is set as the caller frame
          * @param envFrame the frame from which the clone is made

com.oracle.truffle.r.nodes.builtin/src/com/oracle/truffle/r/nodes/builtin/base/Recall.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2021, 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

com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/function/PromiseHelperNode.java

@@ -379,7 +379,8 @@ private static Object generateValueFromFullPromiseSlowPath(VirtualFrame frame, R
     private static VirtualEvalFrame wrapPromiseFrame(VirtualFrame frame, MaterializedFrame promiseFrame, RPromise promise, Object callerFrameObject) {
         assert promise != null;
         assert promiseFrame != null;
-        return VirtualEvalFrame.create(promiseFrame, RArguments.getFunction(promiseFrame), callerFrameObject, RCaller.createForPromise(RArguments.getCall(promiseFrame), RArguments.getCall(frame), promise));
+        return VirtualEvalFrame.create(promiseFrame, RArguments.getFunction(promiseFrame), callerFrameObject,
+                        RCaller.createForPromise(RArguments.getCall(promiseFrame), RArguments.getCall(frame), promise));
     }
 
     private static Object generateValueFromEagerPromiseSlowPath(VirtualFrame frame, int state, EagerPromise promise, boolean visibleExec) {

com.oracle.truffle.r.nodes/src/com/oracle/truffle/r/nodes/function/RCallerHelper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2021, 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2021, 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2021, 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
@@ -40,10 +40,10 @@
  * Represents the caller of a function and other information related an R stack frame evaluation
  * context. It is created by the caller of the function and passed in the arguments array.
  * {@link RCaller} instances for all R stack frames form a linked list.
- *
+ * <p>
  * A value of this type never appears in a Truffle execution. The closest concept in GNU-R is
  * RCNTXT, see {@code main/context.c}.
- *
+ * <p>
  * On the high level {@link RCaller} instance holds:
  * <ul>
  * <li>link to the {@link RCaller} associated with the previous R stack frame.</li>
@@ -78,14 +78,18 @@
  *   global          (depth = 0, parent = null, payload = null)
  * </pre>
  *
+ * For convenience, there is a diagram representing the aforementioned stack frames here:
+ * <p>
+ * <img src="doc_files/promise_fun_rcaller_hierarchy.svg">
+ * <p>
  * Where the 'internal frame' wraps the frame of bar so that the promise code can access all the
  * local variables of bar, but the {@link RCaller} can be different: the depth that would normally
  * be 1 is 2, and parent and payload are different (see docs of {@link #isPromise()}). The purpose
  * of {@link #payload} in such frames is that we can use it to reach the actual frame where the
  * promise is logically evaluated, should the promise call some stack introspection built-in, e.g.
  * {@code parent.frame()}. The reason why depths is 2 is that any consecutive function call uses
  * current depth + 1 as the new depth and we need the new depth to be 3.
- *
+ * <p>
  * Note that the 'internal frame' may not be on the real execution stack (i.e. not iterable by
  * Truffle). The {@code InlineCacheNode} directly injects the AST of the promise into the calling
  * function AST (foo in this case), but passes the 'internal frame' to the execute method instead of
@@ -94,9 +98,21 @@
  * {@link com.oracle.truffle.api.CallTarget} and calls it with 'internal frame', in which case there
  * will be additional frame when iterating frames with Truffle, but that frame will hold the
  * 'internal frame' inside its arguments array.
- *
- * For debugging purposes, there is {@code com.oracle.truffle.r.nodes.builtin.fastr.FastRRCallerTrace}
- * builtin that prints RCaller hierarchy from the current Truffle execution frame.
+ * <p>
+ * For debugging purposes, there is
+ * {@code com.oracle.truffle.r.nodes.builtin.fastr.FastRRCallerTrace} builtin that prints RCaller
+ * hierarchy from the current Truffle execution frame.
+ * <p>
+ * To fully understand {@code RCaller}, we provide the following diagrams drawn according to the
+ * output of {@code .fastr.rcallertrace()}:
+ * <p>
+ * <img src="doc_files/nested_promises_rcaller_hierarchy.svg">
+ * <p>
+ * Depicting a stack frame with nested promises. Source code taken from {@code stack-intro-tests.R}.
+ * <p>
+ * <img src="doc_files/parent_frame_not_on_stack_rcaller_hierarchy.svg">
+ * <p>
+ * Depicting a parent.frame that is not on the stack frame any more.
  *
  * See {@code FrameFunctions}.
  *
@@ -158,9 +174,9 @@ public final class RCaller {
 
     /**
      * When constructing an RCaller for a promise, we may add a reference to the promise itself.
-     * This helps with the performance of {@code sys.frame} and {@code parent.frame} - if this
-     * field is not null, we get the materialized frame straight from the {@link RPromise} rather
-     * than iterating all the truffle frames.
+     * This helps with the performance of {@code sys.frame} and {@code parent.frame} - if this field
+     * is not null, we get the materialized frame straight from the {@link RPromise} rather than
+     * iterating all the truffle frames.
      *
      * Note that this field may be null even if {@link #isPromise()} returns true.
      */