Associate Bytecode DSL packages with Truffle; fix bad links and doc typos

Author: DSouzaM

truffle/docs/bytecode_dsl/Optimization.md

@@ -13,7 +13,7 @@ Boxing elimination avoids these unnecessary boxing steps.
 The interpreter can speculatively rewrite bytecode instructions to specialized instructions that pass primitive values whenever possible.
 Boxing elimination can also improve compiled performance, because Graal is not always able to remove box-unbox sequences during compilation.
 
-To enable boxing elimination, specify a set of `boxingEliminationTypes` on the [`@GenerateBytecode`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode./src/com/oracle/truffle/api/bytecode/GenerateBytecode.java) annotation. For example, the following configuration
+To enable boxing elimination, specify a set of `boxingEliminationTypes` on the [`@GenerateBytecode`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/GenerateBytecode.java) annotation. For example, the following configuration
 
 ```java
 @GenerateBytecode(
@@ -35,7 +35,7 @@ Quickened operations can be introduced to reduce the work required to evaluate a
 For example, a quickened operation that only accepts `int` inputs might avoid operand boxing and the additional type checks required by the general operation.
 Additionally, a custom operation that has only one active specialization could be quickened to an operation that only supports that single specialization, avoiding extra specialization state checks.
 
-At the moment, quickened instructions can only be specified manually using [`@ForceQuickening`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode./src/com/oracle/truffle/api/bytecode/ForceQuickening.java).
+At the moment, quickened instructions can only be specified manually using [`@ForceQuickening`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/ForceQuickening.java).
 In the future, [tracing](#tracing) will be able to automatically infer useful quickenings.
 
 

truffle/docs/bytecode_dsl/ShortCircuitOperations.md

@@ -3,7 +3,7 @@
 One limitation of regular operations is that they are *eager*: all of the child operations are evaluated before the operation itself evaluates.
 Many languages define *short-circuiting* operators (e.g., Java's `&&`) which can evaluate a subset of their operands, terminating early when an operand meets a particular condition (e.g., when it is `true`).
 
-The Bytecode DSL allows you to define [`@ShortCircuitOperation`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode./src/com/oracle/truffle/api/bytecode/ShortCircuitOperation.java)s to implement short-circuiting behaviour.
+The Bytecode DSL allows you to define [`@ShortCircuitOperation`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/ShortCircuitOperation.java)s to implement short-circuiting behaviour.
 A short-circuit operation implements `AND` or `OR` semantics, executing each child operation until the first `false` or `true` value, respectively.
 
 ### Basic example

truffle/docs/bytecode_dsl/UserGuide.md

@@ -106,7 +106,7 @@ The current state is encapsulated in a [`BytecodeNode`](https://github.com/oracl
 It is worth familiarizing yourself with its APIs.
 
 The `BytecodeNode` (and the bytecode itself) can change over the execution of a program for various reasons (e.g., [transitioning from uncached to cached](#cached-and-uncached-execution), [reparsing metadata](#reparsing), [quickening](Optimization.md#quickening)), so you should use `BytecodeRootNode#getBytecodeNode()` to obtain the up-to-date bytecode node each time you need it.
-Custom operations can also `@Bind BytecodeNode` in their specializations (see [Bind parameters](#bind-parameters)).
+Custom operations can also `@Bind BytecodeNode` in their specializations (more about special Bind parameters [here](#expressions-in-operations)).
 
 Because the bytecode may change, a bytecode index (obtained using `@Bind("$bytecodeIndex")`) must be paired with a `BytecodeNode` to meaningfully identify a program location.
 You can also instantiate a [`BytecodeLocation`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/BytecodeLocation.java), which logically represents the bytecode node and index, using `BytecodeNode#getBytecodeLocation(int)` or `@Bind BytecodeLocation`.
@@ -271,7 +271,7 @@ The builder will emit code to collect these values into an `Object[]`.
 
 An operation can also define _constant operands_, which are embedded in the bytecode and produce partial evaluation constant values, by declaring [`@ConstantOperand`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/ConstantOperand.java)s.
 
-An operation may need to produce more than one result, or to modify local variables. For either case, the operation can use [`LocalAccessor`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalAccessor.java) or [`LocalAccessorRange`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalAccessorRange.java).
+An operation may need to produce more than one result, or to modify local variables. For either case, the operation can use [`LocalAccessor`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalAccessor.java) or [`LocalRangeAccessor`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalRangeAccessor.java).
 
 
 ## Locals
@@ -298,7 +298,7 @@ b.endBlock();
 All local accesses must be (directly or indirectly) nested within the operation that created the local.
 
 The `LoadLocal` and `StoreLocal` operations are the preferred way to access locals because they are efficient and can be quickened to [avoid boxing](Optimization.md#boxing-elimination).
-Some behaviour cannot be easily implemented using only these operations, in which case an operation can declare a [`LocalAccessor`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalAccessor.java) or [`LocalAccessorRange`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalAccessorRange.java) operand to perform local accesses.
+Some behaviour cannot be easily implemented using only these operations, in which case an operation can declare a [`LocalAccessor`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalAccessor.java) or [`LocalRangeAccessor`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/LocalRangeAccessor.java) operand to perform local accesses.
 For example, an operation producing multiple values cannot "return" both values, and may instead use a local accessor to write one of the values back to a local.
 The [`BytecodeNode`](https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/BytecodeNode.java) class also declares a variety of helper methods for accessing locals.
 These helpers often have extra indirection, so the built-in operations and accessors are preferred.
@@ -533,7 +533,7 @@ It is recommended to enclose the `Root` operation in appropriate `Source` and `S
 The generated root node will override `Node#getSourceSection` to return this information.
 
 Source information is designed to have no performance overhead until it is requested (see [Reparsing metadata](#reparsing)).
-This information [should generally not be accessed from compiled code](RuntimeCompilation.md#source-information).
+Take extra care if accessing source information in [compiled code](RuntimeCompilation.md#source-information).
 
 ### Instrumentation
 

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/GettingStarted.java

@@ -447,6 +447,7 @@ public void testIfThenElse() {
      *   while i < n:
      *     i += 1
      *     total += i
+     *   return total
      * </pre>
      */
     @Test
@@ -507,7 +508,7 @@ public void testLoop() {
     }
 
     /**
-     * For more advanced control flow, The Bytecode DSL also allows you to define and branch to
+     * For more advanced control flow, the Bytecode DSL also allows you to define and branch to
      * labels. Programs can branch forward to labels using the {@code Branch} operation. Let's use
      * labels to implement {@code sumToN} using a {@code break}:
      *
@@ -593,7 +594,7 @@ public void testLoopWithBreak() {
     }
 
     /*
-     * In addition to the condition and looping contructs, The Bytecode DSL has other control flow
+     * In addition to the condition and looping constructs, the Bytecode DSL has other control flow
      * mechanisms for exception handling ({@code TryCatch}, {@code TryFinally}, and {@code
      * TryCatchOtherwise}) and continuations ({@code Yield}). We will not cover those here.
      */

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/ParsingTutorial.java

@@ -60,10 +60,6 @@
  * This tutorial demonstrates how to programmatically parse bytecode for a Bytecode DSL interpreter.
  * It refers to the interpreter defined in the {@link GettingStarted} guide. It is recommended to
  * read that guide first.
- *
- * @see <a href=
- *      "https://github.com/oracle/graal/blob/master/truffle/docs/bytecode_dsl/GettingStarted.md">Getting
- *      started guide</a>
  */
 public class ParsingTutorial {
     /**
@@ -565,7 +561,25 @@ public void visitForEach(ForEach f) {
     }
 
     /**
-     * Now, let's test it.
+     * Finally, let's test it below.
+     *
+     * This tutorial demonstrated how to parse programs using visitors. It also demonstrated how to
+     * "desugar" complex nodes into simpler operations.
+     * <p>
+     * Still, some more advanced features (e.g., {@code TryFinally} operations) have not been
+     * covered. We encourage you to consult the other resources available:
+     *
+     * @see <a href=
+     *      "https://github.com/oracle/graal/blob/master/truffle/docs/bytecode_dsl/UserGuide.md">User
+     *      guide</a>.
+     *
+     * @see <a href=
+     *      "https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/bytecode/package-summary.html">Javadoc
+     *      </a>.
+     *
+     * @see <a href=
+     *      "https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.sl/src/com/oracle/truffle/sl/bytecode/SLBytecodeRootNode.java">Simple
+     *      Language implementation</a>.
      */
     public void testForEach() {
         // @formatter:off
@@ -599,28 +613,4 @@ private static BytecodeDSLTestLanguage getLanguage() {
         return null;
     }
 
-    /**
-     * This tutorial demonstrated how to parse programs using visitors. It also demonstrated how to
-     * "desugar" complex nodes into simpler operations.
-     * <p>
-     * Still, some more advanced features (e.g., {@code TryFinally} operations) have not been
-     * covered. We encourage you to consult the other resources available:
-     *
-     * @see <a href=
-     *      "https://github.com/oracle/graal/blob/master/truffle/docs/bytecode_dsl/UserGuide.md">User
-     *      guide</a>.
-     *
-     * @see <a href=
-     *      "https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/bytecode/package-summary.html">Javadoc
-     *      </a>.
-     *
-     * @see <a href=
-     *      "https://github.com/oracle/graal/blob/master/truffle/src/com.oracle.truffle.sl/src/com/oracle/truffle/sl/bytecode/SLBytecodeRootNode.java">Simple
-     *      Language implementation</a>.
-     *
-     * @see <a href=
-     *      "https://github.com/oracle/graalpython/blob/master/graalpython/com.oracle.graal.python/src/com/oracle/graal/python/nodes/bytecode_dsl/PBytecodeDSLRootNode.java">GraalPython
-     *      implementation</a>.
-     */
-
 }

truffle/src/com.oracle.truffle.api.bytecode.test/src/com/oracle/truffle/api/bytecode/test/examples/SerializationTutorial.java

@@ -93,7 +93,7 @@ public class SerializationTutorial {
      * {@link GenerateBytecode} specification, set {@code enableSerialization = true}. Then, rebuild
      * your project to update the generated interpreter.
      * <p>
-     * When serialization is enabled, The Bytecode DSL generates extra methods that you can use to
+     * When serialization is enabled, the Bytecode DSL generates extra methods that you can use to
      * serialize/deserialize your bytecode nodes. It also validates that all of the
      * non-{@code transient} fields (which will be serialized) are reachable.
      */

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/debug/package-info.java

@@ -39,6 +39,12 @@
  * SOFTWARE.
  */
 
+/*
+ @ApiInfo(
+ group="Truffle"
+ )
+ */
+
 /**
  * Debug utilities for the Bytecode DSL. These features are not intended to be used in production
  * interpreters for performance reasons.

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/package-info.java

@@ -39,6 +39,12 @@
  * SOFTWARE.
  */
 
+/*
+ @ApiInfo(
+ group="Truffle"
+ )
+ */
+
 /**
  * The Bytecode DSL is a DSL and runtime support component of Truffle that makes it easier to
  * implement bytecode interpreters. Start {@link com.oracle.truffle.api.bytecode.GenerateBytecode

truffle/src/com.oracle.truffle.api.bytecode/src/com/oracle/truffle/api/bytecode/serialization/package-info.java

@@ -39,6 +39,12 @@
  * SOFTWARE.
  */
 
+/*
+ @ApiInfo(
+ group="Truffle"
+ )
+ */
+
 /**
  * Serialization-specific classes for the Bytecode DSL.
  *