Merge pull request #857 from garcia-jj/ot-interceptordocs

[docs] Adding docs to interceptor annotations

vraptor-core/src/main/java/br/com/caelum/vraptor/Accepts.java

@@ -21,6 +21,17 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Defines a method with a condition to intercept or not the current stack. The annotated method must return a
+ * {@code boolean} value and you can't have more than one accept strategy in the same class.
+ * 
+ * <code>
+ * \@Accepts
+ * public boolean accepts(ControllerMethod method) {
+ *     return method.containsAnnotation(Audit.class);
+ * }
+ * </code>
+ */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

vraptor-core/src/main/java/br/com/caelum/vraptor/AfterCall.java

@@ -21,6 +21,17 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Executes a method after the current call. The target method must have no parameters, and you can't have more than 
+ * one method annotated with {@link AfterCall} in the same class.
+ * 
+ * <code>
+ * \@AfterCall
+ * public void intercept() {
+ *     System.out.println("code executed after stack");
+ * }
+ * </code>
+ */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

vraptor-core/src/main/java/br/com/caelum/vraptor/AroundCall.java

@@ -21,6 +21,24 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import br.com.caelum.vraptor.core.InterceptorStack;
+import br.com.caelum.vraptor.interceptor.SimpleInterceptorStack;
+
+/**
+ * Executes a method in the current call. You should use the {@code SimpleInterceptorStack#next()} to execute
+ * the next interceptor stack. The target method must have only one parameter with {@link SimpleInterceptorStack} or 
+ * {@link InterceptorStack} type, and you can't have more than one method annotated with {@link AroundCall} 
+ * in the same class.
+ * 
+ * <code>
+ * \@AroundCall
+ * public void intercept(SimpleInterceptorStack stack) {
+ *     System.out.println("Executing before");
+ *     stack.next();
+ *     System.out.println("Executing after");
+ * }
+ * </code>
+ */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

vraptor-core/src/main/java/br/com/caelum/vraptor/BeforeCall.java

@@ -21,6 +21,18 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Executes a method before the current call, and you can't have more than one method annotated with {@link BeforeCall} 
+ * in the same class. The target method must have no parameters. The method 
+ * {@code br.com.caelum.vraptor.interceptor.SimpleInterceptorStack#next} will call implicity after the execution.
+ * 
+ * <code>
+ * \@BeforeCall
+ * public void intercept() {
+ *     System.out.println("code executed before stack");
+ * }
+ * </code>
+ */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)

vraptor-core/src/main/java/br/com/caelum/vraptor/interceptor/AcceptsForPackages.java

@@ -22,6 +22,15 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * A class level annotation to define that the stack will intercepted only for packages and subpackages. In 
+ * the example below all classes inside {@code com.myapp.controllers} will be intercepted, including subpackages.
+ * <code>
+ * \@AcceptsForPackages("com.myapp.controllers")
+ * public class AuditInterceptor {
+ * }
+ * </code>
+ */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)

vraptor-core/src/main/java/br/com/caelum/vraptor/interceptor/AcceptsWithAnnotations.java

@@ -23,6 +23,19 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * A class level annotation to define that the stack will intercepted when an annotation is present.
+ * <code>
+ * \@AcceptsWithAnnotations(Audit.class)
+ *  public class AuditInterceptor {
+ *  
+ *      \@AroundCall
+ *      public void around(SimpleInterceptorStack stack) {
+ *          stack.next();
+ *      }
+ *  }
+ * </code>
+ */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)