[polymer] switch comment style

pkg/polymer/lib/src/declaration.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of polymer;
 
-/**
- * **Warning**: this class is experiental and subject to change.
- *
- * The implementation for the `polymer-element` element.
- *
- * Normally you do not need to use this class directly, see [PolymerElement].
- */
+/// **Warning**: this class is experiental and subject to change.
+///
+/// The implementation for the `polymer-element` element.
+///
+/// Normally you do not need to use this class directly, see [PolymerElement].
 class PolymerDeclaration extends HtmlElement {
   static const _TAG = 'polymer-element';
 
   factory PolymerDeclaration() => new Element.tag(_TAG);
   // Fully ported from revision:
   // https://github.com/Polymer/polymer/blob/b7200854b2441a22ce89f6563963f36c50f5150d
   //
   //   src/declaration/attributes.js
   //   src/declaration/events.js
   //   src/declaration/polymer-element.js
@@ skipping 15 matching lines @@
   // TODO(jmesserly): this is also a cache, since we can't store .element on
   // each level of the __proto__ like JS does.
   PolymerDeclaration _super;
   PolymerDeclaration get superDeclaration => _super;
 
   String _extendsName;
 
   String _name;
   String get name => _name;
 
-  /**
-   * Map of publish properties. Can be a field or a property getter, but if this
-   * map contains a getter, is because it also has a corresponding setter.
-   *
-   * Note: technically these are always single properties, so we could use a
-   * Symbol instead of a PropertyPath. However there are lookups between this
-   * map and [_observe] so it is easier to just track paths.
-   */
+  /// Map of publish properties. Can be a field or a property getter, but if
+  /// this map contains a getter, is because it also has a corresponding setter.
+  ///
+  /// Note: technically these are always single properties, so we could use a
+  /// Symbol instead of a PropertyPath. However there are lookups between this
+  /// map and [_observe] so it is easier to just track paths.
   Map<PropertyPath, smoke.Declaration> _publish;
 
-  /** The names of published properties for this polymer-element. */
+  /// The names of published properties for this polymer-element.
   Iterable<String> get publishedProperties =>
       _publish != null ? _publish.keys.map((p) => '$p') : const [];
 
-  /** Same as [_publish] but with lower case names. */
+  /// Same as [_publish] but with lower case names.
   Map<String, smoke.Declaration> _publishLC;
 
   Map<PropertyPath, List<Symbol>> _observe;
 
   Map<String, Object> _instanceAttributes;
 
   List<Element> _sheets;
   List<Element> get sheets => _sheets;
 
   List<Element> _styles;
   List<Element> get styles => _styles;
 
   DocumentFragment get templateContent {
     final template = this.querySelector('template');
     return template != null ? templateBind(template).content : null;
   }
 
-  /** Maps event names and their associated method in the element class. */
+  /// Maps event names and their associated method in the element class.
   final Map<String, String> _eventDelegates = {};
 
-  /** Expected events per element node. */
+  /// Expected events per element node.
   // TODO(sigmund): investigate whether we need more than 1 set of local events
   // per element (why does the js implementation stores 1 per template node?)
   Expando<Set<String>> _templateDelegates;
 
   PolymerDeclaration.created() : super.created() {
     // fetch the element name
     _name = attributes['name'];
     // fetch our extendee name
     _extendsName = attributes['extends'];
     // install element definition, if ready
@@ skipping 72 matching lines @@
     // more declarative features
     desugar(name, extendee);
     // register our custom element
     registerType(name);
 
     // NOTE: skip in Dart because we don't have mutable global scope.
     // reference constructor in a global named by 'constructor' attribute
     // publishConstructor();
   }
 
-  /**
-   * Gets the Dart type registered for this name, and sets up declarative
-   * features. Fills in the [type] and [supertype] fields.
-   *
-   * *Note*: unlike the JavaScript version, we do not have to metaprogram the
-   * prototype, which simplifies this method.
-   */
+  /// Gets the Dart type registered for this name, and sets up declarative
+  /// features. Fills in the [type] and [supertype] fields.
+  ///
+  /// *Note*: unlike the JavaScript version, we do not have to metaprogram the
+  /// prototype, which simplifies this method.
   void buildType(String name, String extendee) {
     // get our custom type
     _type = _getRegisteredType(name);
 
     // get basal prototype
     _supertype = _getRegisteredType(extendee);
     if (_supertype != null) _super = _getDeclaration(extendee);
 
     // transcribe `attributes` declarations onto own prototype's `publish`
     publishAttributes(_super);
 
     publishProperties();
 
     inferObservers();
 
     // desugar compound observer syntax, e.g. @ObserveProperty('a b c')
     explodeObservers();
 
     // Skip the rest in Dart:
     // chain various meta-data objects to inherited versions
     // chain custom api to inherited
     // build side-chained lists to optimize iterations
     // inherit publishing meta-data
     // x-platform fixup
   }
 
-  /** Implement various declarative features. */
+  /// Implement various declarative features.
   void desugar(name, extendee) {
     // compile list of attributes to copy to instances
     accumulateInstanceAttributes();
     // parse on-* delegates declared on `this` element
     parseHostEvents();
     // install external stylesheets as if they are inline
     installSheets();
 
     adjustShadowElement();
 
@@ skipping 100 matching lines @@
 
   static bool isInstanceAttribute(name) {
     // do not clone these attributes onto instances
     final blackList = const {
         'name': 1, 'extends': 1, 'constructor': 1, 'noscript': 1,
         'attributes': 1};
 
     return !blackList.containsKey(name) && !name.startsWith('on-');
   }
 
-  /** Extracts events from the element tag attributes. */
+  /// Extracts events from the element tag attributes.
   void parseHostEvents() {
     addAttributeDelegates(_eventDelegates);
   }
 
   void addAttributeDelegates(Map<String, String> delegates) {
     attributes.forEach((name, value) {
       if (_hasEventPrefix(name)) {
         var start = value.indexOf('{{');
         var end = value.lastIndexOf('}}');
         if (start >= 0 && end >= 0) {
           delegates[_removeEventPrefix(name)] =
               value.substring(start + 2, end).trim();
         }
       }
     });
   }
 
   String urlToPath(String url) {
     if (url == null) return '';
     return (url.split('/')..removeLast()..add('')).join('/');
   }
 
-  /**
-   * Install external stylesheets loaded in <element> elements into the
-   * element's template.
-   */
+  /// Install external stylesheets loaded in <element> elements into the
+  /// element's template.
   void installSheets() {
     cacheSheets();
     cacheStyles();
     installLocalSheets();
     installGlobalStyles();
   }
 
   void cacheSheets() {
     _sheets = findNodes(_SHEET_SELECTOR);
     for (var s in sheets) s.remove();
   }
 
   void cacheStyles() {
     _styles = findNodes('$_STYLE_SELECTOR[$_SCOPE_ATTR]');
     for (var s in styles) s.remove();
   }
 
-  /**
-   * Takes external stylesheets loaded in an `<element>` element and moves
-   * their content into a style element inside the `<element>`'s template.
-   * The sheet is then removed from the `<element>`. This is done only so
-   * that if the element is loaded in the main document, the sheet does
-   * not become active.
-   * Note, ignores sheets with the attribute 'polymer-scope'.
-   */
+  /// Takes external stylesheets loaded in an `<element>` element and moves
+  /// their content into a style element inside the `<element>`'s template.
+  /// The sheet is then removed from the `<element>`. This is done only so
+  /// that if the element is loaded in the main document, the sheet does
+  /// not become active.
+  /// Note, ignores sheets with the attribute 'polymer-scope'.
   void installLocalSheets() {
     var sheets = this.sheets.where(
         (s) => !s.attributes.containsKey(_SCOPE_ATTR));
     var content = templateContent;
     if (content != null) {
       var cssText = new StringBuffer();
       for (var sheet in sheets) {
         cssText..write(_cssTextFromSheet(sheet))..write('\n');
       }
       if (cssText.length > 0) {
         content.insertBefore(
             new StyleElement()..text = '$cssText',
             content.firstChild);
       }
     }
   }
 
   List<Element> findNodes(String selector, [bool matcher(Element e)]) {
     var nodes = this.querySelectorAll(selector).toList();
     var content = templateContent;
     if (content != null) {
       nodes = nodes..addAll(content.querySelectorAll(selector));
     }
     if (matcher != null) return nodes.where(matcher).toList();
     return nodes;
   }
 
-  /**
-   * Promotes external stylesheets and style elements with the attribute
-   * polymer-scope='global' into global scope.
-   * This is particularly useful for defining @keyframe rules which
-   * currently do not function in scoped or shadow style elements.
-   * (See wkb.ug/72462)
-   */
+  /// Promotes external stylesheets and style elements with the attribute
+  /// polymer-scope='global' into global scope.
+  /// This is particularly useful for defining @keyframe rules which
+  /// currently do not function in scoped or shadow style elements.
+  /// (See wkb.ug/72462)
   // TODO(sorvell): remove when wkb.ug/72462 is addressed.
   void installGlobalStyles() {
     var style = styleForScope(_STYLE_GLOBAL_SCOPE);
     Polymer.applyStyleToScope(style, document.head);
   }
 
   String cssTextForScope(String scopeDescriptor) {
     var cssText = new StringBuffer();
     // handle stylesheets
     var selector = '[$_SCOPE_ATTR=$scopeDescriptor]';
@@ skipping 15 matching lines @@
   }
 
   StyleElement cssTextToScopeStyle(String cssText, String scopeDescriptor) {
     if (cssText == '') return null;
 
     return new StyleElement()
         ..text = cssText
         ..attributes[_STYLE_SCOPE_ATTRIBUTE] = '$name-$scopeDescriptor';
   }
 
-  /**
-   * Fetch a list of all *Changed methods so we can observe the associated
-   * properties.
-   */
+  /// Fetch a list of all *Changed methods so we can observe the associated
+  /// properties.
   void inferObservers() {
     var options = const smoke.QueryOptions(includeFields: false,
         includeProperties: false, includeMethods: true, includeInherited: true);
     for (var decl in smoke.query(_type, options)) {
       String name = smoke.symbolToName(decl.name);
       if (name.endsWith(_OBSERVE_SUFFIX) && name != 'attributeChanged') {
         // TODO(jmesserly): now that we have a better system, should we
         // deprecate *Changed methods?
         if (_observe == null) _observe = new HashMap();
         name = name.substring(0, name.length - 7);
         _observe[new PropertyPath(name)] = [decl.name];
       }
     }
   }
 
-  /**
-   * Fetch a list of all methods annotated with [ObserveProperty] so we can
-   * observe the associated properties.
-   */
+  /// Fetch a list of all methods annotated with [ObserveProperty] so we can
+  /// observe the associated properties.
   void explodeObservers() {
     var options = const smoke.QueryOptions(includeFields: false,
         includeProperties: false, includeMethods: true, includeInherited: true,
         withAnnotations: const [ObserveProperty]);
     for (var decl in smoke.query(_type, options)) {
       for (var meta in decl.annotations) {
         if (meta is! ObserveProperty) continue;
         if (_observe == null) _observe = new HashMap();
         for (String name in meta.names) {
           _observe.putIfAbsent(new PropertyPath(name), () => []).add(decl.name);
@@ skipping 52 matching lines @@
   var options = const smoke.QueryOptions(includeInherited: true,
       withAnnotations: const [PublishedProperty]);
   for (var decl in smoke.query(type, options)) {
     if (decl.isFinal) continue;
     if (props == null) props = {};
     props[new PropertyPath([decl.name])] = decl;
   }
   return props;
 }
 
-/** Attribute prefix used for declarative event handlers. */
+/// Attribute prefix used for declarative event handlers.
 const _EVENT_PREFIX = 'on-';
 
-/** Whether an attribute declares an event. */
+/// Whether an attribute declares an event.
 bool _hasEventPrefix(String attr) => attr.startsWith(_EVENT_PREFIX);
 
 String _removeEventPrefix(String name) => name.substring(_EVENT_PREFIX.length);
 
-/**
- * Using Polymer's platform/src/ShadowCSS.js passing the style tag's content.
- */
+/// Using Polymer's platform/src/ShadowCSS.js passing the style tag's content.
 void _shimShadowDomStyling(DocumentFragment template, String name,
     String extendee) {
   if (template == null || !_hasShadowDomPolyfill) return;
 
   var platform = js.context['Platform'];
   if (platform == null) return;
   var shadowCss = platform['ShadowCSS'];
   if (shadowCss == null) return;
   shadowCss.callMethod('shimStyling', [template, name, extendee]);
 }
@@ skipping 76 matching lines @@
 
 // Dart note: we need this function because we have additional renames JS does
 // not have. The JS renames are simply case differences, whereas we have ones
 // like doubleclick -> dblclick and stripping the webkit prefix.
 String _eventNameFromType(String eventType) {
   final result = _reverseEventTranslations[eventType];
   return result != null ? result : eventType;
 }
 
 final _ATTRIBUTES_REGEX = new RegExp(r'\s|,');