#37 javadoc: reflection

assira.core/src/main/java/net/ranides/assira/reflection/IAttribute.java

@@ -7,79 +7,224 @@
 package net.ranides.assira.reflection;
 
 /**
+ * This enum represents attributes of any IElement (class, field, method, etc)
+ *
+ * Each enum contains two int bitmasks: first one is used by IAttributes, second one is
+ * bitmask used by java reflection API.
+ *
+ * Most of the time we tried to use identical mask values for both fields.
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
+@SuppressWarnings("JavadocReference")
 public enum IAttribute {
-    
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#PUBLIC}
+     */
     PUBLIC          (0x0000_0001),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#PRIVATE}
+     */
     PRIVATE         (0x0000_0002),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#PROTECTED}
+     */
     PROTECTED       (0x0000_0004),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#STATIC}
+     */
     STATIC          (0x0000_0008),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#FINAL}
+     */
     FINAL           (0x0000_0010),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#SYNCHRONIZED}
+     */
     SYNCHRONIZED    (0x0000_0020),
 
-    VOLATILE        (0x0000_0040),   // special: must be field (conflict with BRIDGE)
-
-    TRANSIENT       (0x0000_0080),   // special: must be field (conflict with VARARGS)
-
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#VOLATILE}
+     *
+     * Warning: java reflection API uses the same value for BRIGDE.
+     * This attribute is allowed only for IField
+     */
+    VOLATILE        (0x0000_0040),
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#TRANSIENT}
+     *
+     * Warning: java reflection API uses the same value for VARARGS.
+     * This attribute is allowed only for IField
+     */
+    TRANSIENT       (0x0000_0080),
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#NATIVE}
+     */
     NATIVE          (0x0000_0100),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#INTERFACE}
+     */
     INTERFACE       (0x0000_0200),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#ABSTRACT}
+     */
     ABSTRACT        (0x0000_0400),
 
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#STRICT}
+     */
     STRICT          (0x0000_0800),
 
-    BRIDGE          (0x0100_0000, 0x0000_0040),   // special: must be method (conflict with VOLATILE)
-    
-    VARARGS         (0x0200_0000, 0x0000_0080),   // special: must be method (conflict with TRANSIENT)
-    
+    /**
+     *  This is standard reflective attribute: {@link java.lang.reflect.Modifier#BRIDGE}
+     *
+     *  Warning: java reflection API uses the same value for VOLATILE.
+     *  This attribute is allowed only for IMethod
+     */
+    BRIDGE          (0x0100_0000, 0x0000_0040),
+
+    /**
+     *  This is standard reflective attribute: {@link java.lang.reflect.Modifier#VARARGS}
+     *
+     *  Warning: java reflection API uses the same value for TRANSIENT.
+     *  This attribute is allowed only for IMethod
+     */
+    VARARGS         (0x0200_0000, 0x0000_0080),
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#SYNTHETIC}
+     */
     SYNTHETIC       (0x0000_1000),
-    
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#ANNOTATION}
+     */
     ANNOTATION      (0x0000_2000),
-    
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#ENUM}
+     */
     ENUM            (0x0000_4000),
-    
+
+    /**
+     * This is standard reflective attribute: {@link java.lang.reflect.Modifier#MANDATED}
+     */
     MANDATED        (0x0000_8000),
 
+    /**
+     * This is non standard attribute: it means that IElement has package scope
+     * Allowed for class, methods and fields.
+     */
     PACKAGE         (0x0400_0000, 0),   // special: !(public | protected | private)
-    
+
+    /**
+     * This non standard attribute: it means that IElement is generic
+     * Allowed for class, methods and fields.
+     */
     PARAMETERIZED   (0x1000_0000, 0),   // special: is generic class
-    
+
+    /**
+     * This is non standard attribute:
+     * it means that IElement is declared inside "this" class (not inherited from parent class).
+     * 
+     * Allowed for inner classes, methods and fields.
+     * Used by IHints to filter out inherited members.
+     */
     DECLARED        (0x4000_0000, 0),   // special: used in IClass to disable deep scan
-    
-    LAMBDA          (0x8000_0000, 0),   // special: used in IMethod
-    
-    ANY             (0x0020_0000, 0),   // special: used only by AHints for deep scan of declared fields/methods/classes
 
-    ARRAY           (0x0001_0000, 0),   // special: traits
+    /**
+     * This non standard attribute: it means that IMethod is labmda expression
+     */
+    LAMBDA          (0x8000_0000, 0),
+
+    /**
+     * This is non standard attribute:
+     * it means that IElement is declared or inherited.
+     * 
+     * Allowed for inner classes, methods and fields.
+     * Used by IHints to include inherited members.
+     */
+    ANY             (0x0020_0000, 0),   // special: used only by AHints for deep scan of declared fields/methods/classes
 
-    PRIMITIVE       (0x0002_0000, 0),   // special: traits
-    
+    /**
+     * This is type trait: it means that IClass is array
+     */
+    ARRAY           (0x0001_0000, 0),
+
+    /**
+     * This is type trait: it means that IClass is primitive type
+     *
+     * @see net.ranides.assira.reflection.util.ClassTraits#isPrimitive 
+     */
+    PRIMITIVE       (0x0002_0000, 0),
+
+    /**
+     * This is type trait: it means that IClass is numerical type
+     *
+     * @see net.ranides.assira.reflection.util.ClassTraits#isNumber
+     */
     NUMBER          (0x2000_0000, 0),   // special: traits
-    
+
+    /**
+     * This is type trait: it means that IClass is integer type
+     *
+     * @see net.ranides.assira.reflection.util.ClassTraits#isInteger
+     */
     INTEGER         (0x0040_0000, 0),   // special: traits
 
+    /**
+     * This is type trait: it means that IClass is boxed type
+     *
+     * @see net.ranides.assira.reflection.util.ClassTraits#isBoxed
+     */
     BOXED           (0x0004_0000, 0),   // special: traits
-    
+
+    /**
+     * This is type trait: it means that IClass is void type
+     *
+     * @see net.ranides.assira.reflection.util.ClassTraits#isVoid
+     */
     VOID            (0x0008_0000, 0),   // special: traits
-    
+
+    /**
+     * This is type trait: it means that IClass is boolean type
+     *
+     * @see net.ranides.assira.reflection.util.ClassTraits#isBool
+     */
     BOOLEAN         (0x0010_0000, 0),   // special: traits
-    
+
+    /**
+     * This is non standard attribute:
+     * it means that IElement does not represent "real reflective" object,
+     * but contains only information about name and signature (more or less)
+     *
+     * Allowed for classes and methods.
+     */
     SYMBOLIC        (0x0800_0000),
     
     //RESERVED        (0x00800000),
     
     ;
 
+    /**
+     * This field is bitmask used by IAttributes container
+     */
     final int mask;
 
+    /**
+     * This field represents bitmask compatible with {@link java.lang.reflect.Modifier}
+     * Obviously returned mask does not contain non-standard attributes.
+     */
     final int reflective;
 
     IAttribute(int mask) {

assira.core/src/main/java/net/ranides/assira/reflection/IAttributes.java

@@ -9,6 +9,11 @@ import java.util.Objects;
 
 import static net.ranides.assira.reflection.IAttribute.*;
 
+/**
+ * This is container dedicated to store IAttribute values
+ *
+ * Internaly it uses MaskFactory and MaskSet configured to use IAttribute#mask
+ */
 public class IAttributes {
 
     private static final int M_BRIDGE   = 0x00000040;
@@ -19,6 +24,9 @@ public class IAttributes {
 
     private static final MaskFactory<IAttribute> MAP = new MaskFactory<>(IAttribute.values(), a -> a.mask);
 
+    /**
+     * Empty and immutable set of attributes
+     */
     public static final IAttributes EMPTY = new IAttributes(0,0).immutable();
 
     private int reflective;
@@ -35,6 +43,12 @@ public class IAttributes {
         this.values = MAP.collect(mask);
     }
 
+    /**
+     * Returns immutable copy of this collection
+     * If collection is already immutable, returns "this".
+     *
+     * @return IAttributes
+     */
     public IAttributes immutable() {
         return new CAttributes(this);
     }
@@ -61,38 +75,92 @@ public class IAttributes {
         return Objects.hash(reflective, values);
     }
 
+    /**
+     * Returns true if collection contains specified attribute
+     *
+     * @param attr attr
+     * @return boolean
+     */
     public boolean contains(IAttribute attr) {
         return values.contains(attr);
     }
 
+    /**
+     * Returns true if collection contains all specified attributes
+     *
+     * @param attrs attrs
+     * @return boolean
+     */
     public boolean containsAll(IAttributes attrs) {
         return values.containsAll(attrs.values);
     }
 
+    /**
+     * Returns true if collection contains specified attribute
+     *
+     * It is alias for "contains".
+     *
+     * @param attr attr
+     * @return boolean
+     */
     public boolean has(IAttribute attr) {
         return values.contains(attr);
     }
 
+    /**
+     * Returns true if collection contains all specified attributes
+     *
+     * It is alias for "containsAll".
+     *
+     * @param attrs attrs
+     * @return boolean
+     */
     public boolean has(IAttributes attrs) {
         return values.containsAll(attrs.values);
     }
 
+    /**
+     * Inserts attribute to this collection.
+     * If collection is immutable, does nothing (does not throw exception).
+     *
+     * @param attr attr
+     * @return this
+     */
     public IAttributes add(IAttribute attr) {
         values.add(attr);
         reflective |= attr.reflective;
         return this;
     }
 
+    /**
+     * Inserts all attributes to this collection.
+     * If collection is immutable, does nothing (does not throw exception).
+     *
+     * @param attrs attrs
+     * @return this
+     */
     public IAttributes add(IAttributes attrs) {
         values.addAll(attrs.values);
         reflective |= attrs.reflective;
         return this;
     }
 
+    /**
+     * Returns attributes as bitmask compatible with {@link java.lang.reflect.Modifier}
+     * Obviously returned mask does not contain non-standard attributes.
+     *
+     * @return int
+     */
     public int reflective() {
         return reflective;
     }
 
+    /**
+     * Creates new mutable collection with provided attributes
+     *
+     * @param attrs attrs
+     * @return IAttributes
+     */
     public static IAttributes of(IAttribute... attrs) {
         int reflective = 0;
         for(IAttribute a : attrs) {
@@ -101,6 +169,12 @@ public class IAttributes {
         return new IAttributes(reflective, MAP.collect(attrs));
     }
 
+    /**
+     * Creates new mutable collection with attributes deduced from field
+     *
+     * @param field field
+     * @return IAttributes
+     */
     public static IAttributes of(Field field) {
         int reflective = field.getModifiers();
         int mask = getModifiers(reflective);
@@ -110,6 +184,12 @@ public class IAttributes {
         return new IAttributes(reflective, mask);
     }
 
+    /**
+     * Creates new mutable collection with attributes deduced from method/constructor
+     *
+     * @param method method
+     * @return IAttributes
+     */
     public static IAttributes of(Executable method) {
         int reflective = method.getModifiers();
         int mask = getModifiers(reflective);
@@ -127,6 +207,12 @@ public class IAttributes {
         return new IAttributes(reflective, mask);
     }
 
+    /**
+     * Creates new mutable collection with attributes deduced from Parameter
+     *
+     * @param param param
+     * @return IAttributes
+     */
     public static IAttributes of(Parameter param) {
         int reflective = param.getModifiers();
         int mask = getModifiers(reflective);
@@ -136,6 +222,12 @@ public class IAttributes {
         return new IAttributes(reflective, mask);
     }
 
+    /**
+     * Creates new mutable collection with attributes deduced from Class
+     *
+     * @param type type
+     * @return IAttributes
+     */
     public static IAttributes of(Class<?> type) {
         int reflective = type.getModifiers();
         int mask = getModifiers(reflective);

assira.core/src/main/java/net/ranides/assira/reflection/ResolvePattern.java

@@ -17,7 +17,7 @@ import net.ranides.assira.text.StringUtils;
 
 /**
  *
- * Please note that there is special behaviour you format against ResolveContext:
+ * Please note that there is special behaviour when you format against ResolveContext:
  * if resolved value is of type ResolveFormat or ResolvePattern then
  * it is evaluated against context again.
  *

assira.core/src/main/java/net/ranides/assira/reflection/walker/rules/CollectRules.java

@@ -373,7 +373,7 @@ public class CollectRules<T> {
              *
              * Rule with more than one condition is executed if any condition is met
              *
-             * @param predicate
+             * @param predicate predicate
              * @return Rule
              */
             public MoreRule match(Predicate<WalkerContexts.ObjectContext<?>> predicate) {
@@ -487,7 +487,7 @@ public class CollectRules<T> {
              *
              * Rule with more than one condition is executed if any condition is met
              *
-             * @param predicate
+             * @param predicate predicate
              * @return Rule
              */
             public MoreRule match(Predicate<WalkerContexts.ObjectContext<?>> predicate) {
@@ -599,7 +599,7 @@ public class CollectRules<T> {
              *
              * Rule with more than one condition is executed if any condition is met
              *
-             * @param predicate
+             * @param predicate predicate
              * @return Rule
              */
             public MoreRule match(Predicate<WalkerContexts.ObjectContext<?>> predicate) {

assira.core/src/main/java/net/ranides/assira/reflection/walker/rules/PrintRules.java

@@ -388,7 +388,7 @@ public class PrintRules {
              *
              * Rule with more than one condition is executed if any condition is met
              *
-             * @param predicate
+             * @param predicate predicate
              * @return Rule
              */
             public MoreRule match(Predicate<WalkerContexts.ObjectContext<?>> predicate) {
@@ -497,7 +497,7 @@ public class PrintRules {
              *
              * Rule with more than one condition is executed if any condition is met
              *
-             * @param predicate
+             * @param predicate predicate
              * @return Rule
              */
             public MoreRule match(Predicate<WalkerContexts.ObjectContext<?>> predicate) {
@@ -606,7 +606,7 @@ public class PrintRules {
              *
              * Rule with more than one condition is executed if any condition is met
              *
-             * @param predicate
+             * @param predicate predicate
              * @return Rule
              */
             public MoreRule match(Predicate<WalkerContexts.ObjectContext<?>> predicate) {