svn commit: r1470250 - in /commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model: AnnotatedElements.java ScanResult.java

[mb...@apache.org]

Author: mbenson
Date: Sat Apr 20 23:12:28 2013
New Revision: 1470250

URL: http://svn.apache.org/r1470250
Log:
javadoc, fmt

Modified:
    commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/AnnotatedElements.java
    commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/ScanResult.java

Modified: commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/AnnotatedElements.java
URL: http://svn.apache.org/viewvc/commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/AnnotatedElements.java?rev=1470250&r1=1470249&r2=1470250&view=diff
==============================================================================
--- commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/AnnotatedElements.java (original)
+++ commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/AnnotatedElements.java Sat Apr 20 23:12:28 2013
@@ -19,8 +19,22 @@
 package org.apache.commons.weaver.model;
 
 import java.lang.annotation.Annotation;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.reflect.AnnotatedElement;
 
+/**
+ * Interface defining a means of iterating over a particular type of {@link AnnotatedElement} as well as filtering by
+ * annotation type (including annotations with {@link RetentionPolicy#CLASS} retention in addition to those with
+ * {@link RetentionPolicy#RUNTIME} retention.
+ * 
+ * @param <T>
+ */
 public interface AnnotatedElements<T extends AnnotatedElement> extends Iterable<T> {
+    /**
+     * Filter by annotation type.
+     * 
+     * @param annotationType
+     * @return {@link AnnotatedElements}, narrowed
+     */
     AnnotatedElements<T> with(Class<? extends Annotation> annotationType);
 }

Modified: commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/ScanResult.java
URL: http://svn.apache.org/viewvc/commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/ScanResult.java?rev=1470250&r1=1470249&r2=1470250&view=diff
==============================================================================
--- commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/ScanResult.java (original)
+++ commons/sandbox/weaver/trunk/processor/src/main/java/org/apache/commons/weaver/model/ScanResult.java Sat Apr 20 23:12:28 2013
@@ -29,12 +29,30 @@ import java.util.NoSuchElementException;
 import java.util.concurrent.ConcurrentNavigableMap;
 import java.util.concurrent.ConcurrentSkipListMap;
 
+import org.apache.commons.weaver.WeaveProcessor;
+import org.apache.commons.weaver.spi.Weaver;
+
 /**
- * Encapsulates the result of scanning based on a {@link ScanRequest}.
+ * Encapsulates the result of scanning based on a {@link ScanRequest}. The scan results are available in a structure
+ * corresponding to the Java class hierarchy; i.e.:
+ * 
+ * <pre>
+ *   package
+ *   |_class
+ *     |_field
+ *     |_method
+ *     | |_method parameter
+ *     |_constructor
+ *       |_constructor parameter
+ * </pre>
+ * 
+ * The tree of results can be iterated in this manner using {@link #getPackages()}. However, if a given {@link Weaver}
+ * is known not to handle packages but some other element, convenience methods are provided here giving direct access to
+ * the various elements that may have been discovered.
  */
 public class ScanResult {
     private static abstract class Projection<PARENT, CHILD extends AnnotatedElement> implements
-        AnnotatedElements<CHILD> {
+            AnnotatedElements<CHILD> {
         private final Iterable<PARENT> parents;
 
         Projection(Iterable<PARENT> parents) {
@@ -149,9 +167,14 @@ public class ScanResult {
 
     }
 
-    private final ConcurrentNavigableMap<String, WeavablePackage> packages =
-        new ConcurrentSkipListMap<String, WeavablePackage>();
+    private final ConcurrentNavigableMap<String, WeavablePackage> packages = new ConcurrentSkipListMap<String, WeavablePackage>();
 
+    /**
+     * Public for use by {@link WeaveProcessor}.
+     * 
+     * @param pkg
+     * @return {@link WeavablePackage}
+     */
     public WeavablePackage getWeavable(Package pkg) {
         final String key = pkg.getName();
         if (packages.containsKey(key)) {
@@ -162,18 +185,42 @@ public class ScanResult {
         return faster == null ? result : faster;
     }
 
+    /**
+     * Public for use by {@link WeaveProcessor}.
+     * 
+     * @param cls
+     * @return {@link WeavableClass}
+     */
     public <T> WeavableClass<T> getWeavable(Class<T> cls) {
         return getWeavable(cls.getPackage()).getWeavable(cls);
     }
 
+    /**
+     * Public for use by {@link WeaveProcessor}.
+     * 
+     * @param fld
+     * @return {@link WeavableField}
+     */
     public WeavableField<?> getWeavable(Field fld) {
         return getWeavable(fld.getDeclaringClass()).getWeavable(fld);
     }
 
+    /**
+     * Public for use by {@link WeaveProcessor}.
+     * 
+     * @param mt
+     * @return {@link WeavableMethod}
+     */
     public WeavableMethod<?> getWeavable(Method mt) {
         return getWeavable(mt.getDeclaringClass()).getWeavable(mt);
     }
 
+    /**
+     * Public for use by {@link WeaveProcessor}.
+     * 
+     * @param ctor
+     * @return {@link WeavableConstructor}
+     */
     public <T> WeavableConstructor<T> getWeavable(Constructor<T> ctor) {
         return getWeavable(ctor.getDeclaringClass()).getWeavable(ctor);
     }