doc(annotation): added documentation to annotations library.

mhevery · mhevery · commit 45bb8c63ecb7 · 2014-04-09T20:57:22.000-07:00
diff --git a/lib/core/annotation.dart b/lib/core/annotation.dart
diff --git a/lib/core/annotation_src.dart b/lib/core/annotation_src.dart
diff --git a/lib/core/registry_dynamic.dart b/lib/core/registry_dynamic.dart
@@ -1,13 +1,13 @@
 library angular.core_dynamic;
 
 import 'dart:mirrors';
-import 'package:angular/core/annotation.dart';
+import 'package:angular/core/annotation_src.dart';
 import 'package:angular/core/registry.dart';
 
 export 'package:angular/core/registry.dart' show
     MetadataExtractor;
 
-var _fieldMetadataCache = new Map<Type, Map<String, AttrFieldAnnotation>>();
+var _fieldMetadataCache = new Map<Type, Map<String, AbstractNgFieldAnnotation>>();
 
 class DynamicMetadataExtractor implements MetadataExtractor {
   final _fieldAnnotations = [
@@ -30,38 +30,38 @@ class DynamicMetadataExtractor implements MetadataExtractor {
   }
 
   map(Type type, obj) {
-    if (obj is NgAnnotation) {
+    if (obj is AbstractNgAnnotation) {
       return mapDirectiveAnnotation(type, obj);
     } else {
       return obj;
     }
   }
 
-  NgAnnotation mapDirectiveAnnotation(Type type, NgAnnotation annotation) {
+  AbstractNgAnnotation mapDirectiveAnnotation(Type type, AbstractNgAnnotation annotation) {
     var match;
     var fieldMetadata = fieldMetadataExtractor(type);
     if (fieldMetadata.isNotEmpty) {
       var newMap = annotation.map == null ? {} : new Map.from(annotation.map);
-      fieldMetadata.forEach((String fieldName, AttrFieldAnnotation ann) {
+      fieldMetadata.forEach((String fieldName, AbstractNgFieldAnnotation ann) {
         var attrName = ann.attrName;
         if (newMap.containsKey(attrName)) {
           throw 'Mapping for attribute $attrName is already defined (while '
           'processing annottation for field $fieldName of $type)';
         }
-        newMap[attrName] = '${ann.mappingSpec}$fieldName';
+        newMap[attrName] = '${mappingSpec(ann)}$fieldName';
       });
-      annotation = annotation.cloneWithNewMap(newMap);
+      annotation = cloneWithNewMap(annotation, newMap);
     }
     return annotation;
   }
 
 
-  Map<String, AttrFieldAnnotation> fieldMetadataExtractor(Type type) =>
+  Map<String, AbstractNgFieldAnnotation> fieldMetadataExtractor(Type type) =>
       _fieldMetadataCache.putIfAbsent(type, () => _fieldMetadataExtractor(type));
 
-  Map<String, AttrFieldAnnotation> _fieldMetadataExtractor(Type type) {
+  Map<String, AbstractNgFieldAnnotation> _fieldMetadataExtractor(Type type) {
     ClassMirror cm = reflectType(type);
-    final fields = <String, AttrFieldAnnotation>{};
+    final fields = <String, AbstractNgFieldAnnotation>{};
     cm.declarations.forEach((Symbol name, DeclarationMirror decl) {
       if (decl is VariableMirror ||
       decl is MethodMirror && (decl.isGetter || decl.isSetter)) {
@@ -76,7 +76,7 @@ class DynamicMetadataExtractor implements MetadataExtractor {
               throw 'Attribute annotation for $fieldName is defined more '
               'than once in $type';
             }
-            fields[fieldName] = meta.reflectee as AttrFieldAnnotation;
+            fields[fieldName] = meta.reflectee as AbstractNgFieldAnnotation;
           }
         });
       }
diff --git a/lib/core_dom/common.dart b/lib/core_dom/common.dart
@@ -16,7 +16,7 @@ class MappingParts {
 class DirectiveRef {
   final dom.Node element;
   final Type type;
-  final NgAnnotation annotation;
+  final AbstractNgAnnotation annotation;
   final String value;
   final mappings = new List<MappingParts>();
 
diff --git a/lib/core_dom/directive_map.dart b/lib/core_dom/directive_map.dart
@@ -1,7 +1,7 @@
 part of angular.core.dom_internal;
 
 @NgInjectableService()
-class DirectiveMap extends AnnotationsMap<NgAnnotation> {
+class DirectiveMap extends AnnotationsMap<AbstractNgAnnotation> {
   DirectiveSelectorFactory _directiveSelectorFactory;
   DirectiveSelector _selector;
   DirectiveSelector get selector {
diff --git a/lib/core_dom/element_binder.dart b/lib/core_dom/element_binder.dart
@@ -58,7 +58,7 @@ class ElementBinder {
   final bool hasTemplate = false;
 
   bool get shouldCompileChildren =>
-      childMode == NgAnnotation.COMPILE_CHILDREN;
+      childMode == AbstractNgAnnotation.COMPILE_CHILDREN;
 
   var _directiveCache;
   List<DirectiveRef> get _usableDirectiveRefs {
@@ -269,7 +269,7 @@ class ElementBinder {
           ..factory(ElementProbe, (_) => probe);
 
       directiveRefs.forEach((DirectiveRef ref) {
-        NgAnnotation annotation = ref.annotation;
+        AbstractNgAnnotation annotation = ref.annotation;
         var visibility = ref.annotation.visibility;
         if (ref.annotation is NgController) {
           scope = scope.createChild(new PrototypeMap(scope.context));
diff --git a/lib/core_dom/element_binder_builder.dart b/lib/core_dom/element_binder_builder.dart
@@ -38,23 +38,23 @@ class ElementBinderBuilder {
   DirectiveRef component;
 
   // Can be either COMPILE_CHILDREN or IGNORE_CHILDREN
-  String childMode = NgAnnotation.COMPILE_CHILDREN;
+  String childMode = AbstractNgAnnotation.COMPILE_CHILDREN;
 
   ElementBinderBuilder(this._factory);
 
   addDirective(DirectiveRef ref) {
     var annotation = ref.annotation;
     var children = annotation.children;
 
-    if (annotation.children == NgAnnotation.TRANSCLUDE_CHILDREN) {
+    if (annotation.children == AbstractNgAnnotation.TRANSCLUDE_CHILDREN) {
       template = ref;
     } else if (annotation is NgComponent) {
       component = ref;
     } else {
       decorators.add(ref);
     }
 
-    if (annotation.children == NgAnnotation.IGNORE_CHILDREN) {
+    if (annotation.children == AbstractNgAnnotation.IGNORE_CHILDREN) {
       childMode = annotation.children;
     }
 
diff --git a/lib/core_dom/module_internal.dart b/lib/core_dom/module_internal.dart
@@ -7,7 +7,7 @@ import 'dart:html' as dom;
 import 'package:di/di.dart';
 import 'package:perf_api/perf_api.dart';
 
-import 'package:angular/core/annotation.dart';
+import 'package:angular/core/annotation_src.dart';
 import 'package:angular/core/module_internal.dart';
 import 'package:angular/core/parser/parser.dart';
 import 'package:angular/core_dom/dom_util.dart' as util;
diff --git a/lib/core_dom/selector.dart b/lib/core_dom/selector.dart
@@ -29,7 +29,7 @@ part of angular.core.dom_internal;
  */
 class _Directive {
   final Type type;
-  final NgAnnotation annotation;
+  final AbstractNgAnnotation annotation;
 
   _Directive(this.type, this.annotation);
 
@@ -38,7 +38,7 @@ class _Directive {
 
 
 class _ContainsSelector {
-  final NgAnnotation annotation;
+  final AbstractNgAnnotation annotation;
   final RegExp regexp;
 
   _ContainsSelector(this.annotation, String regexp)
@@ -252,7 +252,7 @@ class DirectiveSelector {
     elementSelector = new _ElementSelector('');
     attrSelector = <_ContainsSelector>[];
     textSelector = <_ContainsSelector>[];
-    _directives.forEach((NgAnnotation annotation, Type type) {
+    _directives.forEach((AbstractNgAnnotation annotation, Type type) {
       var match;
       var selector = annotation.selector;
       List<_SelectorPart> selectorParts;
diff --git a/lib/directive/ng_if.dart b/lib/directive/ng_if.dart
@@ -90,7 +90,7 @@ abstract class _NgUnlessIfAttrDirectiveBase {
  *     </div>
  */
 @NgDirective(
-    children: NgAnnotation.TRANSCLUDE_CHILDREN,
+    children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN,
     selector:'[ng-if]',
     map: const {'.': '=>condition'})
 class NgIf extends _NgUnlessIfAttrDirectiveBase {
@@ -151,7 +151,7 @@ class NgIf extends _NgUnlessIfAttrDirectiveBase {
  *     </div>
  */
 @NgDirective(
-    children: NgAnnotation.TRANSCLUDE_CHILDREN,
+    children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN,
     selector:'[ng-unless]',
     map: const {'.': '=>condition'})
 class NgUnless extends _NgUnlessIfAttrDirectiveBase {
diff --git a/lib/directive/ng_non_bindable.dart b/lib/directive/ng_non_bindable.dart
@@ -20,5 +20,5 @@ part of angular.directive;
  */
 @NgDirective(
     selector: '[ng-non-bindable]',
-    children: NgAnnotation.IGNORE_CHILDREN)
+    children: AbstractNgAnnotation.IGNORE_CHILDREN)
 class NgNonBindable {}
diff --git a/lib/directive/ng_repeat.dart b/lib/directive/ng_repeat.dart
@@ -66,7 +66,7 @@ part of angular.directive;
  */
 
 @NgDirective(
-    children: NgAnnotation.TRANSCLUDE_CHILDREN,
+    children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN,
     selector: '[ng-repeat]',
     map: const {'.': '@expression'})
 class NgRepeat {
diff --git a/lib/directive/ng_switch.dart b/lib/directive/ng_switch.dart
@@ -111,7 +111,7 @@ class _Case {
 
 @NgDirective(
     selector: '[ng-switch-when]',
-    children: NgAnnotation.TRANSCLUDE_CHILDREN,
+    children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN,
     map: const {'.': '@value'})
 class NgSwitchWhen {
   final NgSwitch ngSwitch;
@@ -125,7 +125,7 @@ class NgSwitchWhen {
 }
 
 @NgDirective(
-    children: NgAnnotation.TRANSCLUDE_CHILDREN,
+    children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN,
     selector: '[ng-switch-default]')
 class NgSwitchDefault {
 
diff --git a/lib/directive/ng_template.dart b/lib/directive/ng_template.dart
@@ -23,7 +23,7 @@ part of angular.directive;
   map: const {'id': '@templateUrl'})
 @NgDirective(
   selector: 'script[type=text/ng-template]',
-  children: NgAnnotation.IGNORE_CHILDREN,
+  children: AbstractNgAnnotation.IGNORE_CHILDREN,
   map: const {'id': '@templateUrl'})
 class NgTemplate {
   final dom.Element element;
diff --git a/lib/tools/transformer/metadata_extractor.dart b/lib/tools/transformer/metadata_extractor.dart
@@ -199,11 +199,11 @@ class AnnotationExtractor {
   final AssetId outputId;
 
   static const List<String> _angularAnnotationNames = const [
-    'angular.core.annotation.NgAttr',
-    'angular.core.annotation.NgOneWay',
-    'angular.core.annotation.NgOneWayOneTime',
-    'angular.core.annotation.NgTwoWay',
-    'angular.core.annotation.NgCallback'
+    'angular.core.annotation_src.NgAttr',
+    'angular.core.annotation_src.NgOneWay',
+    'angular.core.annotation_src.NgOneWayOneTime',
+    'angular.core.annotation_src.NgTwoWay',
+    'angular.core.annotation_src.NgCallback'
   ];
 
   static const Map<String, String> _annotationToMapping = const {
@@ -228,9 +228,9 @@ class AnnotationExtractor {
       }
       _annotationElements.add(type.unnamedConstructor);
     }
-    ngAnnotationType = resolver.getType('angular.core.annotation.NgAnnotation');
+    ngAnnotationType = resolver.getType('angular.core.annotation_src.AbstractNgAnnotation');
     if (ngAnnotationType == null) {
-      logger.warning('Unable to resolve NgAnnotation, '
+      logger.warning('Unable to resolve AbstractNgAnnotation, '
           'skipping member annotations.');
     }
   }
@@ -296,11 +296,11 @@ class AnnotationExtractor {
     return type;
   }
 
-  /// Folds all AttrFieldAnnotations into the NgAnnotation annotation on the
+  /// Folds all AttrFieldAnnotations into the AbstractNgAnnotation annotation on the
   /// class.
   void _foldMemberAnnotations(Map<String, Annotation> memberAnnotations,
       AnnotatedType type) {
-    // Filter down to NgAnnotation constructors.
+    // Filter down to AbstractNgAnnotation constructors.
     var ngAnnotations = type.annotations.where((a) {
       var element = a.element;
       if (element is! ConstructorElement) return false;
diff --git a/lib/tools/transformer/referenced_uris.dart b/lib/tools/transformer/referenced_uris.dart
@@ -32,7 +32,7 @@ class _Processor {
 
   static const String cacheAnnotationName =
     'angular.template_cache_annotation.NgTemplateCache';
-  static const String componentAnnotationName = 'angular.core.annotation.NgComponent';
+  static const String componentAnnotationName = 'angular.core.annotation_src.NgComponent';
 
   _Processor(this.transform, this.resolver, this.options, this.skipNonCached,
       this.templatesOnly) {
diff --git a/lib/transformer.dart b/lib/transformer.dart
@@ -33,11 +33,11 @@ class AngularTransformerGroup implements TransformerGroup {
 TransformOptions _parseSettings(Map args) {
   // Default angular annotations for injectable types
   var annotations = [
-      'angular.core.annotation.NgInjectableService',
-      'angular.core.annotation.NgDirective',
-      'angular.core.annotation.NgController',
-      'angular.core.annotation.NgComponent',
-      'angular.core.annotation.NgFilter'];
+      'angular.core.annotation_src.NgInjectableService',
+      'angular.core.annotation_src.NgDirective',
+      'angular.core.annotation_src.NgController',
+      'angular.core.annotation_src.NgComponent',
+      'angular.core.annotation_src.NgFilter'];
   annotations.addAll(_readStringListValue(args, 'injectable_annotations'));
 
   // List of types which are otherwise not indicated as being injectable.
diff --git a/test/angular_spec.dart b/test/angular_spec.dart
@@ -123,12 +123,12 @@ main() {
       var ALLOWED_NAMES = [
         "angular.app.Application",
         "angular.app.AngularModule",
-        "angular.core.annotation.NgAttachAware",
-        "angular.core.annotation.NgComponent",
-        "angular.core.annotation.NgController",
-        "angular.core.annotation.NgDetachAware",
-        "angular.core.annotation.NgDirective",
-        "angular.core.annotation.NgInjectableService",
+        "angular.core.annotation_src.NgAttachAware",
+        "angular.core.annotation_src.NgComponent",
+        "angular.core.annotation_src.NgController",
+        "angular.core.annotation_src.NgDetachAware",
+        "angular.core.annotation_src.NgDirective",
+        "angular.core.annotation_src.NgInjectableService",
         "angular.core_internal.CacheStats",
         "angular.core_internal.ExceptionHandler",
         "angular.core_internal.Interpolate",
diff --git a/test/core_dom/compiler_spec.dart b/test/core_dom/compiler_spec.dart
@@ -680,7 +680,7 @@ class LocalAttrDirective {
 
 @NgDirective(
     selector: '[simple-transclude-in-attach]',
-    visibility: NgDirective.CHILDREN_VISIBILITY, children: NgAnnotation.TRANSCLUDE_CHILDREN)
+    visibility: NgDirective.CHILDREN_VISIBILITY, children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN)
 class SimpleTranscludeInAttachAttrDirective {
   SimpleTranscludeInAttachAttrDirective(ViewPort viewPort, BoundViewFactory boundViewFactory, Logger log, RootScope scope) {
     scope.runAsync(() {
@@ -714,7 +714,7 @@ class TwoOfTwoDirectives {
 
 @NgDirective(
     selector: '[ignore-children]',
-    children: NgAnnotation.IGNORE_CHILDREN
+    children: AbstractNgAnnotation.IGNORE_CHILDREN
 )
 class IgnoreChildrenDirective {
   IgnoreChildrenDirective(Logger log) {
diff --git a/test/core_dom/element_binder_builder_spec.dart b/test/core_dom/element_binder_builder_spec.dart
@@ -5,10 +5,10 @@ import 'dart:mirrors';
 
 @NgComponent(selector:'component')            class _Component{}
 @NgDirective(selector:'[ignore-children]',
-             children: NgAnnotation.IGNORE_CHILDREN)
+             children: AbstractNgAnnotation.IGNORE_CHILDREN)
                                               class _IgnoreChildren{}
 @NgDirective(selector:'[structural]',
-             children: NgAnnotation.TRANSCLUDE_CHILDREN)
+             children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN)
                                               class _Structural{}
 @NgDirective(selector:'[directive]')          class _DirectiveAttr{}
 
@@ -36,7 +36,7 @@ main() => describe('ElementBinderBuilder', () {
   });
 
   addDirective(selector) {
-    directives.forEach((NgAnnotation annotation, Type type) {
+    directives.forEach((AbstractNgAnnotation annotation, Type type) {
       if (annotation.selector == selector)
         b.addDirective(new DirectiveRef(node, type, annotation, null));
     });
@@ -50,7 +50,7 @@ main() => describe('ElementBinderBuilder', () {
 
     expect(b.decorators.length).toEqual(1);
     expect(b.component).toBeNull();
-    expect(b.childMode).toEqual(NgAnnotation.COMPILE_CHILDREN);
+    expect(b.childMode).toEqual(AbstractNgAnnotation.COMPILE_CHILDREN);
 
   });
 
@@ -72,6 +72,6 @@ main() => describe('ElementBinderBuilder', () {
 
     expect(b.decorators.length).toEqual(1);
     expect(b.component).toBeNull();
-    expect(b.childMode).toEqual(NgAnnotation.IGNORE_CHILDREN);
+    expect(b.childMode).toEqual(AbstractNgAnnotation.IGNORE_CHILDREN);
   });
 });
diff --git a/test/core_dom/selector_spec.dart b/test/core_dom/selector_spec.dart
@@ -16,11 +16,11 @@ import '../_specs.dart';
 @NgComponent(selector:'component')            class _Component{}
 @NgDirective(selector:'[attribute]')          class _Attribute{}
 @NgDirective(selector:'[structural]',
-             children: NgAnnotation.TRANSCLUDE_CHILDREN)
+             children: AbstractNgAnnotation.TRANSCLUDE_CHILDREN)
                                               class _Structural{}
 
 @NgDirective(selector:'[ignore-children]',
-             children: NgAnnotation.IGNORE_CHILDREN)
+             children: AbstractNgAnnotation.IGNORE_CHILDREN)
                                               class _IgnoreChildren{}
 
 @NgDirective(selector: '[my-model][required]')
diff --git a/test/core_dom/view_spec.dart b/test/core_dom/view_spec.dart
diff --git a/test/directive/ng_if_spec.dart b/test/directive/ng_if_spec.dart
diff --git a/test/io/test_files/main.dart b/test/io/test_files/main.dart
diff --git a/test/tools/transformer/metadata_generator_spec.dart b/test/tools/transformer/metadata_generator_spec.dart
