Build and JavaDoc cleanups

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2012, 2016 Oracle and/or its affiliates. All rights reserved.
+Copyright (c) 2012, 2018 Oracle and/or its affiliates. All rights reserved.
 
 The Universal Permissive License (UPL), Version 1.0
 

README.md

@@ -4,8 +4,8 @@ A simple demonstration language built using Truffle for the GraalVM.
 
 SimpleLanguage is heavily documented to explain the how and why of writing a
 Truffle language. A good way to read this documentation is to generate HTML of
-the JavaDoc comments and read that, and then read the source alongside the
-comments.
+the JavaDoc comments with `mvn compile javadoc:aggregate` and read that,
+and then read the source alongside the comments.
 
 This repository is licensed under the permissive UPL licence. Fork it to begin
 your own Truffle language.

component/pom.xml

@@ -14,6 +14,7 @@
       <plugin>
         <artifactId>exec-maven-plugin</artifactId>
         <groupId>org.codehaus.mojo</groupId>
+        <version>1.6.0</version>
         <executions>
           <execution>
             <id>make_component</id>

language/pom.xml

@@ -12,6 +12,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-eclipse-plugin</artifactId>
+        <version>2.10</version>
         <configuration>
           <downloadSources>true</downloadSources>
           <downloadJavadocs>true</downloadJavadocs>

language/src/main/java/com/oracle/truffle/sl/SLException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -80,6 +80,9 @@ public Node getLocation() {
     /**
      * Provides a user-readable message for run-time type errors. SL is strongly typed, i.e., there
      * are no automatic type conversions of values.
+     * @param operation the node representing the failed operation.
+     * @param values the values that caused the type error.
+     * @return an exception containing a description of the run-time error.
      */
     @TruffleBoundary
     public static SLException typeError(Node operation, Object... values) {

language/src/main/java/com/oracle/truffle/sl/SLLanguage.java

@@ -154,7 +154,7 @@
  * {@link SLWhileNode while} with {@link SLBreakNode break} and {@link SLContinueNode continue},
  * {@link SLReturnNode return}.
  * <li>Debugging control: {@link SLDebuggerNode debugger} statement uses
- * {@link DebuggerTags#AlwaysHalt} tag to halt the execution when run under the debugger.
+ * {@link DebuggerTags.AlwaysHalt} tag to halt the execution when run under the debugger.
  * <li>Function calls: {@link SLInvokeNode invocations} are efficiently implemented with
  * {@link SLDispatchNode polymorphic inline caches}.
  * <li>Object access: {@link SLReadPropertyNode} uses {@link SLReadPropertyCacheNode} as the

language/src/main/java/com/oracle/truffle/sl/builtins/SLGetSizeBuiltin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -51,7 +51,7 @@
 
 /**
  * Built-in function that queries the size property of a foreign object. See
- * <link>Messages.GET_SIZE</link>.
+ * {@link Message#GET_SIZE}
  */
 @NodeInfo(shortName = "getSize")
 public abstract class SLGetSizeBuiltin extends SLBuiltinNode {

language/src/main/java/com/oracle/truffle/sl/builtins/SLHasSizeBuiltin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -49,7 +49,7 @@
 
 /**
  * Built-in function that queries if the foreign object has a size. See
- * <link>Messages.HAS_SIZE</link>.
+ * {@link Message#HAS_SIZE}.
  */
 @NodeInfo(shortName = "hasSize")
 public abstract class SLHasSizeBuiltin extends SLBuiltinNode {

language/src/main/java/com/oracle/truffle/sl/builtins/SLIsExecutableBuiltin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -49,7 +49,7 @@
 
 /**
  * Built-in function that queries if the foreign object is executable. See
- * <link>Messages.IS_EXECUTABLE</link>.
+ * {@link }Messages#IS_EXECUTABLE}.
  */
 @NodeInfo(shortName = "isExecutable")
 public abstract class SLIsExecutableBuiltin extends SLBuiltinNode {

language/src/main/java/com/oracle/truffle/sl/builtins/SLIsNullBuiltin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -49,7 +49,7 @@
 
 /**
  * Built-in function that queries if the foreign object is a null value. See
- * <link>Messages.IS_NULL</link>.
+ * {@link Message#IS_NULL}.
  */
 @NodeInfo(shortName = "isNull")
 public abstract class SLIsNullBuiltin extends SLBuiltinNode {

language/src/main/java/com/oracle/truffle/sl/nodes/SLExpressionNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -64,12 +64,15 @@ public abstract class SLExpressionNode extends SLStatementNode {
     /**
      * The execute method when no specialization is possible. This is the most general case,
      * therefore it must be provided by all subclasses.
+     * @param frame the frame containing local variables.
+     * @return the result of executing the expression node.
      */
     public abstract Object executeGeneric(VirtualFrame frame);
 
     /**
      * When we use an expression at places where a {@link SLStatementNode statement} is already
      * sufficient, the return value is just discarded.
+     * @param frame the frame containing local variables.
      */
     @Override
     public void executeVoid(VirtualFrame frame) {

language/src/main/java/com/oracle/truffle/sl/nodes/SLStatementNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -161,6 +161,7 @@ public WrapperNode createWrapper(ProbeNode probe) {
 
     /**
      * Execute this node as as statement, where no return value is necessary.
+     * @param frame the local variable frame.
      */
     public abstract void executeVoid(VirtualFrame frame);
 

language/src/main/java/com/oracle/truffle/sl/nodes/SLTypes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -66,6 +66,8 @@ public abstract class SLTypes {
      * check that the Truffle DSL would generate. For {@link SLNull}, we do not need an
      * {@code instanceof} check, because we know that there is only a {@link SLNull#SINGLETON
      * singleton} instance.
+     * @param value the object to check for nullity.
+     * @return true if the object is equal to the null singleton.
      */
     @TypeCheck(SLNull.class)
     public static boolean isSLNull(Object value) {
@@ -76,6 +78,8 @@ public static boolean isSLNull(Object value) {
      * Example of a manually specified type cast that replaces the automatically generated type cast
      * that the Truffle DSL would generate. For {@link SLNull}, we do not need an actual cast,
      * because we know that there is only a {@link SLNull#SINGLETON singleton} instance.
+     * @param value the object to cast to the null singleton.
+     * @return the null singleton.
      */
     @TypeCast(SLNull.class)
     public static SLNull asSLNull(Object value) {
@@ -89,6 +93,8 @@ public static SLNull asSLNull(Object value) {
      * only has an arbitrary precision Number type (implemented as {@link SLBigNumber}, and
      * {@code long} is only used as a performance optimization to avoid the costly
      * {@link SLBigNumber} arithmetic for values that fit into a 64-bit primitive value.
+     * @param value the long value to convert to a {@link SLBigNumber}.
+     * @return the {@link SLBigNumber} corresponding to the long value.
      */
     @ImplicitCast
     @TruffleBoundary

language/src/main/java/com/oracle/truffle/sl/nodes/access/SLPropertyCacheNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2016, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -67,17 +67,19 @@ protected static Shape lookupShape(DynamicObject receiver) {
     }
 
     /**
-     * Property names can be arbitrary SL objects. We could call {@link Object.equals}, but that is
-     * generally a bad idea and therefore discouraged in Truffle.{@link Object.equals} is a virtual
+     * Property names can be arbitrary SL objects. We could call {@link Object#equals}, but that is
+     * generally a bad idea and therefore discouraged in Truffle.{@link Object#equals} is a virtual
      * call that can call possibly large methods that we do not want in compiled code. For example,
      * we do not want {@link SLBigNumber#equals} in compiled code but behind a
-     * {@link TruffleBoundary). Therfore, we check types individually. The checks are semantically
-     * the same as {@link SLEqualNode}.
+     * {@link com.oracle.truffle.api.CompilerDirectives.TruffleBoundary}. Therefore, we check types individually.
+     * The checks are semantically the same as {@link SLEqualNode}.
      * <p>
      * Note that the {@code cachedName} is always a constant during compilation. Therefore, compiled
      * code is always reduced to a single {@code if} that only checks whether the {@code name} has
      * the same type.
-     *
+     * @param cachedName the cached property name that we want to compare to name.
+     * @param name the value to compare against.
+     * @return true if {@code cachedName} and {@code name} are equal.
      */
     protected static boolean namesEqual(Object cachedName, Object name) {
         if (cachedName instanceof Long && name instanceof Long) {

language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyCacheNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -57,6 +57,12 @@ public abstract class SLReadPropertyCacheNode extends SLPropertyCacheNode {
 
     /**
      * Polymorphic inline cache for a limited number of distinct property names and shapes.
+     * @param receiver the object to receive the read value.
+     * @param name the name of the required property.
+     * @param cachedName the cache object to store the name in.
+     * @param shape the shape of {@code receiver}.
+     * @param location the location of the property.
+     * @return the read object.
      */
     @Specialization(limit = "CACHE_LIMIT", //
                     guards = {
@@ -90,6 +96,10 @@ protected Location lookupLocation(Shape shape, Object name) {
     /**
      * The generic case is used if the number of shapes accessed overflows the limit of the
      * polymorphic inline cache.
+     * @param receiver the object to receive the read value.
+     * @param name the name of the required property.
+     * @return the requested property.
+     * @throws SLUndefinedNameException if the property does not exist.
      */
     @TruffleBoundary
     @Specialization(replaces = {"readCached"}, guards = "receiver.getShape().isValid()")

language/src/main/java/com/oracle/truffle/sl/nodes/access/SLReadPropertyNode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2018, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -86,6 +86,11 @@ protected Object read(DynamicObject receiver, Object name,
     /**
      * Language interoperability: if the receiver object is a foreign value we use Truffle's interop
      * API to access the foreign data.
+     * @param receiver the foreign object to receive the read value.
+     * @param name the name of the foreign property to retrieve.
+     * @param foreignReadNode the AST node that will handle the read request.
+     * @param toSLTypeNode the node to convert the foreign value to the corresponding SL type.
+     * @return the foreign value.
      */
     @Specialization(guards = "!isSLObject(receiver)")
     protected Object readForeign(TruffleObject receiver, Object name,
@@ -109,6 +114,10 @@ protected Object readForeign(TruffleObject receiver, Object name,
     /**
      * When no specialization fits, the receiver is either not an object (which is a type error), or
      * the object has a shape that has been invalidated.
+     * @param r the receiver object (unused).
+     * @param name the name of the property to read.
+     * @return nothing - always throws an exception.
+     * @throws SLUndefinedNameException denoting the value can't be read.
      */
     @Fallback
     protected Object typeError(@SuppressWarnings("unused") Object r, Object name) {