update docs

Author: xvik

CHANGELOG.md

@@ -1,28 +1,27 @@
-* Add constructor generics support (ConstructorGenericsContext)
-* Inlying contexts: generics context building for type "inside" known hierarchy: 
-    "Drill down" case, when new generics context must be build for some type, using generics of current context. 
-    For example, we have some generics context and analyzing class fields. Some field is MyType<T\> - generified with
-    current class's generic. Inlying context is building new hierarchy with extra known generics (for example for class MyType<String\>).
+### 3.0.0 (2018-06-19)
+* Add constructor generics support
+* Add inlying contexts support: generics context building for type "inside" of known hierarchy (field, method parameter etc): 
+    "Drill down" case, when target type could contain generics known in current hierarchy (e.g. field type MyType<T>)     
     Context methods:          
-    - inlyingType(Type) = GenericsContext - universal inlying context builder (the same as GenericsResolver.resolve(class) if class does not have generics)
+    - context.inlyingType(Type) = GenericsContext - universal inlying context builder (the same as GenericsResolver.resolve(class) if class does not have generics)
     - context.fieldType(Field) - shortcut for fields (guarantee correct base type or error if type not in hierarchy)
     - method(Method).returnType() - shortcut for method return type (guarantee correct base type)
     - method(Method).parameterType(pos) - shortcut for method parameter type (guarantee correct base type)
+    - constructor(Constructor).parameterType(pos) - shortcut fot constructor parameter
     - returned context have reference to root context: GenericsContext.rootContext()
-* Inlying context building for sub type: it's like inlying context (knowing type's root generics), but target type is 
-    a subtype for current. Very special case, required for instance analysis: useful when not just type declarations, but
-    also actual instance is used for analysis:
+* Inlying context building for higher type then declared (e.g. in field or method). Very special case, required for 
+    instance analysis when not just type declarations, but also actual instance is used for analysis:
     Suppose we have field MyType<String\> inside class. But we know that actual instance is MySpecificType<T, K\> extends MyType<T\>.
     We need to build generics context for actual class (MySpecificType), but as we know base class type, we can track class generics
     as MySpecificType<String, Object\> (partially tracked) 
-    - inlyingTypeAs(Type, Class) = GenericsContext - universal inlying context building for target class
+    - context.inlyingTypeAs(Type, Class) = GenericsContext - universal inlying context building for higher target class
     - Shortcuts, by analogy with simple inlying contexts: fieldTypeAs(Field, Class), returnTypeAs(Class), parameterTypeAs(pos, Class)
-    - Tracks root type generics from known middle generics (e.g. Root<T\> extends Base<T\> when known Base<String\> will resolve to Root<String\>).
+    - Target type generics tracking from known declared type generics (e.g. Root<T\> extends Base<T\> when known Base<String\> will resolve to Root<String\>).
        Support composite generic declarations (and any hierarchy depth). 
 * Internal analysis logic opened as utilities (for low level usage without GenericsResolver) 
     - GenericsResolutionUtils - generics analysis logic (with access to analyzed type)
-    - GenericsTrackingUtils - root generics tracking from middle class's known generics (with access to analyzed types)
-    - TypeUtils - generic utilities on types (ignoring unknown generics)
+    - GenericsTrackingUtils - root generics tracking from middle class's known generics 
+    - TypeUtils - generic utilities for types (ignoring unknown generics)
 * Types deep comparison api: TypesWalker.walk(Type, Type, Visitor) could walk on two types side by side to check or compare actual classes on each level
     Usages:
     - TypeUtils.isCompatible(Type, Type) - deep types compatibility check
@@ -35,12 +34,12 @@
     - Now all exceptions extend base type GenericsException (runtime) to simplify generic analysis errors interception (catch(GenericException ex))
     - General tracking exception: GenericsTrackingException - thrown on generics tracking problems
     - General resolution exception: GenericsResolutionException - thrown on type hierarchy generics analysis problems
-    - WrongGenericsContextException thrown when supplied type contains generics incompatible with current class 
+    - WrongGenericsContextException thrown when supplied type contains generics incompatible with current hierarchy 
         (not reachable from current context) 
     - More informative error messages
     - (breaking) UnknownGenericException moved to different package
     - (breaking) NoGenericException removed. Was thrown for resolveGenericsOf(Type) methods when class does not declare generics.
-        Now empty list or null will be returned.       
+        Now empty list or null is returned.       
 * Context api improvements:
     * Check all supplied types for compatibility with current class: throw exception when type contains generics
         belonging to other class (avoid usage errors)
@@ -50,39 +49,40 @@
         - ownerGenericsMap() - visible generics of outer class (if current is inner)
         - methodGenericsMap() - method generics
         - constructorGenericsMap() - constructor generics
-        - visibleGenericsMap() - all visible generics (type +owner +method)
+        - visibleGenericsMap() - all visible generics (type +owner +method/constructor)
     * Type resolution methods (return type with all generic variables replaced with known values): 
         - resolveType(Type) = Type
         - Shortcuts: 
             - resolveFieldType(Field) - field type without generic variables 
             - resolveParameterType(pos) - (method context) parameter type without generic variables 
             - resolveReturnType() - (method context) return type without generic variables
         - resolveTypeGenerics(Type) = Type[]    
-    * Shortcuts for Field's type resolution (with automatic context tracking to avoid silly mistakes):
+    * Shortcuts for common Field's resolutions:
         - resolveFieldClass(Field) - field class
         - resolveFieldGenerics(Field) - field's class generics (List<Class\>)
         - resolveFieldGeneric(Field) - field's class generic (Class) 
-    * More to string utilities:
-        - GenericsContext to string methods for context type: 
+    * More toString utilities:
+        - GenericsContext toString methods for context type: 
             - toStringCurrentClassDeclaration() - current with resolved generics ("MyClass<Integer>")
             - toStringCurrentClass() - current class with named generics ("MyClass<T>")
             - toStringMethod() - method string with resolved generics ("void do(MyType)")
             - toStringConstructor() - constructor string with resolved generics ("Some(Long)")
-    * (breaking) resolveGenericsOf() called on class will return upper bounds from generic declaration (previously returns empty map)                        
+    * (breaking) resolveGenericsOf() called on Class will return upper bounds from generic declaration (previously returns empty map)                        
 * Improved debugging support:
     - Core context could be printed as string (class hierarchy with resolved generics): context.getGenericsInfo().toString()
     - For customized context string rendering: context.getGenericsInfo().toStringHierarchy(TypeWriter) 
-    - Direct toString() on context (GenericsContext) prints entire hierarchy with current position marker "<-- current" marker.
-        In intellij idea you can use "view" value link inside debugger to quickly overview current context (with resolved generics) and position      
-* Inner classes support (Outer<T\>.Inner, not static): outer class generics are resolved to avoid UnknownGenericException 
-    - Used owner class (context.ownerClass()) generics: context.ownerGenericsMap() (empty map for not inner class)
-    - For inlying context building, root class may be used as generics source for inner class (if root class hierachy contains owner class).
+    - Direct toString() on context (GenericsContext) prints entire hierarchy with current position marker ("<-- current").
+        In intellij idea, current context (with resolved generics) and position could be seen by using "view value" link inside debugger       
+* Add inner classes support (Outer<T\>.Inner, not static) - outer class generics are resolved during hierarchy building: 
+    - GenericsInfo contains maps with both type generics and owner generics
+    - context.ownerClass() returns owner class, visible owner generics are accessible with context.ownerGenericsMap() (empty map for not inner class)
+    - For inlying context building, root class may be used as generics source for inner class (if root class hierarchy contains owner class).
         This is not always true, but, for most cases, inner class is used inside owner and so generics resolution will be correct
 * Improved bounds support:
     - Support multiple upper bounds declaration: My<T extends A & B\> now stored as wildcard (? extends A & B) and used
-    for more precise checks (compatibility, assignability). As before, resolveClass("T") will use first upper bound (A).
+        for more precise checks (e.g. compatibility, assignability checks). As before, resolveClass("T") will use first upper bound (A).
     - (breaking) avoid upper bound wildcards (transform <? extends Something\> -> Something) as only type matter at runtime
-        affects GenericsUtils.resolveTypeVariables()                                                
+        Affects hierarchy resolution: root generics will not contain Wildcards as before, but just type                                               
 
 Compatibility notes:  
 * API did not changed, only new methods were added.