# HG changeset patch
# User Christian Humer <christian.humer@gmail.com>
# Date 1413843509 -7200
# Node ID 7b6a4ae58de4c0e9fd8204f37b627f608575fa6a
# Parent  7cefdad149ad71a0901d230cc9bd1fe8679d1491
Truffle-DSL: improve JavaDoc for @Fallback.

diff -r 7cefdad149ad -r 7b6a4ae58de4 graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java
--- a/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java	Mon Oct 20 23:11:40 2014 +0200
+++ b/graal/com.oracle.truffle.api.dsl/src/com/oracle/truffle/api/dsl/Fallback.java	Tue Oct 21 00:18:29 2014 +0200
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2014, 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
@@ -26,8 +26,51 @@
 
 import java.lang.annotation.*;
 
+import com.oracle.truffle.api.nodes.*;
+
 /**
+ * <p>
+ * A method annotated with {@link Fallback} is treated as a {@link Specialization} that implicitly
+ * links all the guards of all other declared {@link Specialization} annotated methods of the
+ * operation in a negated form. As a consequence it cannot declare any other guards. The expected
+ * signature of the method must match to the signature of a {@link Specialization} with the
+ * additional limitation that only generically executable argument types are allowed. A generically
+ * executable argument is a an argument hat can be executed from the child {@link Node} using an
+ * execute method without {@link UnsupportedOperationException}. In many cases the generically
+ * executable type is {@link Object}. An operation is limited to just one {@link Fallback}
+ * specialization which is always ordered at the end of the specialization chain.
+ * </p>
  *
+ * <p>
+ * A simple example showing the use of the {@link Fallback} annotation in a DSL operation:
+ * </p>
+ *
+ * <pre>
+ * &#064;Specialization int doInt(int a) {..}
+ * &#064;Specialization int doDouble(double a) {..}
+ * &#064;Fallback int orElse(Object a) {..}
+ * </pre>
+ *
+ * <p>
+ * The previous example could be redeclared just using {@link Specialization} annotated methods as
+ * follows:
+ * </p>
+ *
+ * <pre>
+ * &#064;Specialization int doInt(int a) {..}
+ * &#064;Specialization int doDouble(double a) {..}
+ * &#064;Specialization(guard={"!isInt(a)", "!isDouble(a)"})
+ * int orElse(Object a) {..}
+ * </pre>
+ *
+ * <p>
+ * <b>Performance note:</b> For operations with a lot of {@link Specialization} annotated methods
+ * the use of {@link Fallback} might generate a guard that is very big. Try to avoid the use of
+ * {@link Fallback} for specializations that are significantly important for peak performance.
+ * </p>
+ *
+ * @see Specialization
+ * @see NodeChild
  */
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.METHOD})