Consider annotating class {@link Foo}
+ *Consider annotating class {@code Foo} * *
* {@link Builtin @Builtin}(pkg = "example", stdLibName = "Standard.Base.Data.Foo")
@@ -24,16 +24,14 @@
* public class Foo extends Builtin {}
*
*
- * that refers to Foo builtin type present in Standard Library under the {@link Standard.Base.Data.Foo}
- *
- * type Foo
- * {@link @Builtin_Type}
- * type Foo
- *
+ * that refers to Foo builtin type present in Standard Library under {@code Standard.Base.Data.Foo}
+ * namespace.
+ *
+ * By default, all generated classes are being located in {@link
+ * org.enso.interpreter.node.expression.builtin} package.
*
- * By default, all generated classes are being located in {@link org.enso.interpreter.node.expression.builtin} package.
- *
A {@link Builtin#pkg()} element allows to further customize the subpackage.
- * Class for @BuiltinType {@link Foo} and of its methods will be located in {@link
+ *
A {@link Builtin#pkg()} element allows to further customize the subpackage. Class
+ * for @BuiltinType {@link Foo} and of its methods will be located in {@link
* org.enso.interpreter.node.expression.builtin.example}.
*/
@Target(ElementType.TYPE)
@@ -49,13 +47,13 @@
String name() default "";
/**
- * A method (or constructor) annotated with {@link Builtin.Method} will generate a base
- * implementation for {@link BuiltinMethod}. {@link com.oracle.truffle.api.nodes.Node} class.
+ * A method (or constructor) annotated with {@link Builtin.Method} will generate an implementation
+ * for {@link BuiltinMethod} {@link com.oracle.truffle.api.nodes.Node} class.
*
*
In its simplest form, annotating a simple non-overloaded with the annotation will generate a
* concrete class with a single `execute` method, inside which we call the annotated method.
*
- *
Consider the following class and its to-be builtin methods
+ *
Consider the following class and its to-be-generated builtin methods
*
*
* public class Foo extends {@link TruffleObject} {
@@ -72,7 +70,7 @@
* }
*
*
- * The annotation processing will generate the corresponding classes
+ * The annotation processor will generate the corresponding builtin classes
*
*
* {@link BuiltinMethod @BuiltinMethod}(type = "Foo", name = "length")
@@ -98,13 +96,14 @@
* }
*
*
- * The generated `execute` method ensures that a correct number of method parameters is captured,
- * while taking into account static modifier and return type of the method, including {@link void}
+ * thus eliminating a lot of boilerplate-code that would otherwise have to be written by hand. The
+ * generated `execute` method ensures that a correct number of method parameters is captured,
+ * while taking into account static modifier and return type of the method, including {@code void}
* type.
*
* Overloaded methods, representing different specializations of a single Builtin method have
- * to be additionally annotated with {@link Builtin.Specialize}, or a compiler error will be
- * reported about generated duplicate classes. Similarly, methods that use parameter of type
+ * to be additionally annotated with {@link Builtin.Specialize}, or a compile error will be
+ * reported about generating duplicate classes. Similarly, methods that use parameter of type
* {@link org.enso.interpreter.runtime.Context} or parameters with one of Truffle's {@link
* com.oracle.truffle.api.dsl DSL} or Enso's {@link org.enso.interpreter.dsl DSL} must also be
* marked with {@link Builtin.Specialize}.
@@ -112,7 +111,7 @@
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
@interface Method {
/**
- * @return a custom name for the generated builting method. By default, it uses the name of the
+ * @return a custom name for the generated builtin method. By default, it uses the name of the
* annotated method.
*/
String name() default "";
@@ -121,17 +120,45 @@
String description() default "";
/**
- * @return When applied to a method/constructor with varargs, indicates how many times vararg
- * parameter should be expanded and implicitly how many builtin nodes should be generated.
- * Must be zero when there are no varaargs in the parameters list.
+ * Element indicates how many times a method with vararg parameter should be expanded and
+ * implicitly how many builtin nodes should be generated. Must be zero when there are no
+ * varaargs in the parameters list.
+ *
+ *
+ * class Foo {
+ * {@link Builtin.Method @Builtin.Method}(expandVarargs = 2)
+ * public static Foo create(Object items...) {
+ * // ...
+ * }
+ * }
+ *
+ *
+ * will generate 2 classes
+ *
+ *
+ * {@link BuiltinMethod @BuiltinMethod}(type = "Foo", name = "create_1")
+ * public class Create1FooNode extends Node {
+ * Foo execute(Foo _this, Object items_1) {
+ * return Foo.create(items_1);
+ * }
+ * }
+ * {@link BuiltinMethod @BuiltinMethod}(type = "Foo", name = "create_2")
+ * public class Create2FooNode extends Node {
+ * Foo execute(Foo _this, Object items_1, Object items_2) {
+ * return Foo.create(items_1, items_2);
+ * }
+ * }
+ *
+ *
+ * @return number of desired expansions for vararg parameter.
*/
int expandVarargs() default 0;
}
/**
- * Annotation indicating that compile- or run-time exception the method can throw should be
- * wrapped in Enso's error type that will be reported to the user. The annotation can be repeated
- * leading to multiple catch clauses.
+ * Annotation indicating that compile- or run-time exception should be wrapped in Enso's error
+ * type that will be reported to the user. The annotation can be repeated leading to multiple
+ * catch-clauses.
*
* Consider simple method with possible runtime exception:
*
@@ -143,20 +170,13 @@
* public Object get(long index) {
* return items[index];
* }
- *
- * {@link Builtin.Method @Builtin.Method}
- * {@link Builtin.WrapException @Builtin.WrapException}(from=IOException.class, to=PolyglotError.class, propagate=true)
- * public Object create(String path) throws java.io.IOException {
- * // ...
- * }
- * }
*
*
* Given the information from {@link WrapException#from()} and {@link WrapException#to()}
- * elements, the processor knows that the call to {@link get()} has to be wrapped in try/catch,
+ * elements, the processor knows that the call to {@code get()} has to be wrapped in try/catch,
* catching and re-throwing values of a particular type, respectively. The processor will
- * automatically infer what parameters need to be passed using the information from {@link
- * WrapException#to()} class.
+ * automatically infer what parameters need to be passed to the new exception using the
+ * information from the {@link WrapException#to()} class.
*
* The generated class will therefore ensure that calls to methods are safe and wrapped in an * appropriate catch-clause: @@ -175,8 +195,8 @@ * } * * - *
One can also simply propagate the exception by setting the {@link WrapException#propagate()} - * to true: + *
Simple exception propagation is also possible by setting the {@link + * WrapException#propagate()} element to true: * *
* class Foo {
@@ -194,33 +214,34 @@
* {@link BuiltinMethod @BuiltinMethod}(type = "Foo", name = "create")
* public class CreateFooNode extends Node {
*
- * java.lang.Object execute(Foo _this, Object path) {
- * try {
- * return _this.create(path)
- * } catch (java.io.Exception e) {
- * Builtins builtins = Context.get(this).getBuiltins();
- * throw new PanicException(builtins.error().makePolyglotError(e), this);
+ * Object execute(Foo _this, Object path) {
+ * try {
+ * return _this.create(path)
+ * } catch (java.io.IOException e) {
+ * Builtins builtins = Context.get(this).getBuiltins();
+ * throw new PanicException(builtins.error().makePolyglotError(e), this);
+ * }
* }
* }
*
*/
@Repeatable(WrapExceptions.class)
@interface WrapException {
- /** @return Class of the potential exception to be caught during the execution of the method */
+ /** @return Class of the potential exception to be caught during the execution of the method. */
Class from();
- /** @return Class of Enso's builtin (error) type */
+ /** @return Class of Enso's builtin (error) type to throw instead. */
Class to();
/**
- * @return true, if only the original exception should be wrapped. Otherwise we pass provided
- * method params.
+ * @return true, if the original exception should only be wrapped. Otherwise we pass parameters
+ * from the method when creating the new exception.
*/
boolean propagate() default false;
}
/**
* Container for {@link WrapException} annotations. The annotation should not be used directly.
- * Instead use multiple {@link WrapException}:
+ * Instead, use multiple {@link WrapException}:
*
*
* {@link Builtin.WrapException @Builtin.WrapException}(from=FooException.class, to=PolyglotError.class, propagate=true)
@@ -235,11 +256,12 @@
}
/**
- * Annotation accepting `env.asGuestValue` translation done on the return object. The conversion
- * is generated automatically, depending on the type of the value.
+ * Annotation approving implicit {@link
+ * com.oracle.truffle.api.TruffleLanguage#asGuestValue(Object)} translation done on the return
+ * object. The conversion is generated automatically, depending on the type of the value.
*
* Note that while explicit translations to interop value are discouraged, we still want to
- * occasionally support it to easy the builtins-writing process. The presence of the {@link
+ * occasionally support it to easy builtins-writing process. The presence of the {@link
* ReturningGuestObject} only ensures that it is intentional.
*
*
Consider a method returning an {@link java.io.OutputStream} which is not an interop value,
@@ -250,12 +272,12 @@
* {@link Builtin.Method @Builtin.Method}
* {@link Builtin.ReturningGuestObject @Builtin.ReturningGuestObject}
* java.lang.OutputStream foo(Object item) {
- * // ...
+ * return // ...
* }
* }
*
*
- * The processor will detect the return type of method {@link foo} and perform an automatic
+ * The processor will detect the return type of method {@code foo} and perform an automatic
* conversion:
*
*
@@ -269,9 +291,10 @@
* }
*
*
+ * Without converting the object to the guest language value, it would crash during runtime.
* Without the presence of the annotation, the processor would detect the potential value
* requiring {@link com.oracle.truffle.api.TruffleLanguage#asGuestValue(Object)} translation but
- * crash since it didn't seem to be intended by the user.
+ * stop and report the error since it didn't seem to be intended by the user.
*/
@interface ReturningGuestObject {}
@@ -284,12 +307,12 @@
* Builtin.Method @Builtin.Method} can also be specialized, resulting in an abstract class.
* Additionally, specialized methods may use parameters that involve Truffle's {@link
* com.oracle.truffle.api.dsl DSL}, Enso's {@link org.enso.interpreter.dsl DSL} or {@link
- * org.enso.interpreter.runtime.Context}.
+ * org.enso.interpreter.runtime.Context} values.
*
- * Consider method Foo that makes use of the language's context and a String parameter. Notice - * that Enso uses {@link org.enso.interpreter.runtime.data.text.Text} instead of String and one - * should typically pass it through {@link - * enso.interpreter.node.expression.builtin.text.util.ExpectStringNode} to retrieve its value. + *
Consider method {@code foo} that makes use of the language's context and a String parameter. + * Notice that Enso uses {@link org.enso.interpreter.runtime.data.text.Text} instead of {@code + * String} and one should typically pass it through {@link + * enso.interpreter.node.expression.builtin.text.util.ExpectStringNode} to retrieve its value: * *
* class Foo extends TruffleObject {
@@ -301,7 +324,8 @@
* }
*
*
- * The processor detects types of parameters and generates a specialized node class accordingly:
+ * The processor detects types of parameters and generates a specialized {@code Node} class
+ * accordingly:
*
*
* {@link BuiltinMethod @BuiltinMethod}(type = "Foo", name = "create")
@@ -321,20 +345,21 @@
* }
*
*
- * Notice how the processor - infers the correct signature of {@link execute} method, omitting
- * unnecessary parameters from the original signature, and inferring the signature of the
- * specialized method that will be accepted by Truffle's DSL - injects {@link
- * org.enso.interpreter.runtime.Context} value
+ * Notice how the processor infers the {@code execute} method:
*
- * Parameters having type {@link org.enso.interpreter.runtime.error.WithWarnings} will - * automatically add {@link org.enso.interpreter.dsl.AcceptsWarning} annotation to the - * corresponding + *
Overloaded method scenario The processor infers the parameter on which we specialize. - * Overloaded methods can only differ by a single parameter's type at the moment and the inference - * is based solely on the position of the parameter. + *
Overloaded method scenario For overloaded, specialized, methods the processor infers + * the parameter on which we should specialize on. Overloaded methods can only differ by a single + * parameter's type at the moment and the inference is based solely on the position of the + * parameter. * - *
As an example consider overloaded method bar in class Foo: + *
As an example consider overloaded method bar in class {@code Foo}: * *
* class Foo extends TruffleObject {
@@ -353,7 +378,7 @@
*
*
* The processor infers the right order of specializations, takes into account the types of
- * parameters and infers a single specialized method Node class:
+ * parameters and generates a single Node class with multiple specializations:
*
*
* {@link BuiltinMethod @BuiltinMethod}(type = "Foo", name = "resolve", description = "")
@@ -376,13 +401,17 @@
* }
*
*
- * Parameters having type {@link org.enso.interpreter.runtime.error.WithWarnings} will
- * automatically add {@link org.enso.interpreter.dsl.AcceptsWarning} annotation to the
- * corresponding parameter in {@link execute} method declaration.
+ * Special treatment of {@link org.enso.interpreter.runtime.error.WithWarnings} + * parameters For such parameters the processor automatically adds {@link + * org.enso.interpreter.dsl.AcceptsWarning} annotation to the corresponding parameter in the + * execute method, thus indicating that further processors should allow for the possibility of + * {@code Warnings} being passed around as arguments. + * + *
Fallback specialization * - *
Fallback specialization If the {@link Specialize#fallback()} element is true, the - * corresponding overloaded method will lead to generating a specialization with {@link - * Fallback @Fallback} annotation instead of {@link Specilization @Specialization}. + *
If the {@link Specialize#fallback()} element is true, the corresponding overloaded method + * will lead to generating a specialization with {@link Fallback @Fallback} annotation instead of + * {@link Specilization @Specialization}. */ @interface Specialize { /**