[polymer] switch comment style

pkg/polymer/lib/src/build/linter.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.
 
-/**
- * Logic to validate that developers are correctly using Polymer constructs.
- * This is mainly used to produce warnings for feedback in the editor.
- */
+/// Logic to validate that developers are correctly using Polymer constructs.
+/// This is mainly used to produce warnings for feedback in the editor.
 library polymer.src.build.linter;
 
 import 'dart:async';
 
 import 'package:barback/barback.dart';
 import 'package:html5lib/dom.dart';
 import 'package:html5lib/dom_parsing.dart';
 import 'package:source_maps/span.dart';
 
 import 'common.dart';
 import 'utils.dart';
 
-/**
- * A linter that checks for common Polymer errors and produces warnings to
- * show on the editor or the command line. Leaves sources unchanged, but creates
- * a new asset containing all the warnings.
- */
+/// A linter that checks for common Polymer errors and produces warnings to
+/// show on the editor or the command line. Leaves sources unchanged, but
+/// creates a new asset containing all the warnings.
 class Linter extends Transformer with PolymerTransformer {
   final TransformOptions options;
 
-  /** Only run on .html files. */
+  /// Only run on .html files.
   final String allowedExtensions = '.html';
 
   Linter(this.options);
 
   Future apply(Transform transform) {
     var seen = new Set<AssetId>();
     var primary = transform.primaryInput;
     var id = primary.id;
     transform.addOutput(primary); // this phase is analysis only
     seen.add(id);
     return readPrimaryAsHtml(transform).then((document) {
       return _collectElements(document, id, transform, seen).then((elements) {
         bool isEntrypoint = options.isHtmlEntryPoint(id);
         new _LinterVisitor(transform.logger, elements, isEntrypoint)
             .run(document);
       });
     });
   }
 
-  /**
-   * Collect into [elements] any data about each polymer-element defined in
-   * [document] or any of it's imports, unless they have already been [seen].
-   * Elements are added in the order they appear, transitive imports are added
-   * first.
-   */
+  /// Collect into [elements] any data about each polymer-element defined in
+  /// [document] or any of it's imports, unless they have already been [seen].
+  /// Elements are added in the order they appear, transitive imports are added
+  /// first.
   Future<Map<String, _ElementSummary>> _collectElements(
       Document document, AssetId sourceId, Transform transform,
       Set<AssetId> seen, [Map<String, _ElementSummary> elements]) {
     if (elements == null) elements = <String, _ElementSummary>{};
     return _getImportedIds(document, sourceId, transform)
         // Note: the import order is relevant, so we visit in that order.
         .then((ids) => Future.forEach(ids,
               (id) => _readAndCollectElements(id, transform, seen, elements)))
         .then((_) => _addElements(document, transform.logger, elements))
         .then((_) => elements);
@@ skipping 48 matching lines @@
           ' (second definition).', span: span);
         continue;
       }
 
       elements[name] = new _ElementSummary(name, extendsTag, tag.sourceSpan);
     }
   }
 }
 
 
-/**
- * Information needed about other polymer-element tags in order to validate
- * how they are used and extended.
- *
- * Note: these are only created for polymer-element, because pure custom
- * elements don't have a declarative form.
- */
+/// Information needed about other polymer-element tags in order to validate
+/// how they are used and extended.
+///
+/// Note: these are only created for polymer-element, because pure custom
+/// elements don't have a declarative form.
 class _ElementSummary {
   final String tagName;
   final String extendsTag;
   final Span span;
 
   _ElementSummary extendsType;
   bool hasConflict = false;
 
   String get baseExtendsTag => extendsType == null
       ? extendsTag : extendsType.baseExtendsTag;
@@ skipping 34 matching lines @@
   }
 
   void run(Document doc) {
     visit(doc);
 
     if (_isEntrypoint && !_dartTagSeen) {
       _logger.error(USE_INIT_DART, span: doc.body.sourceSpan);
     }
   }
 
-  /** Produce warnings for invalid link-rel tags. */
+  /// Produce warnings for invalid link-rel tags.
   void _validateLinkElement(Element node) {
     var rel = node.attributes['rel'];
     if (rel != 'import' && rel != 'stylesheet') return;
 
     if (rel == 'import' && _dartTagSeen) {
       _logger.warning(
           "Move HTML imports above your Dart script tag.",
           span: node.sourceSpan);
     }
 
     var href = node.attributes['href'];
     if (href != null && href != '') return;
 
     // TODO(sigmund): warn also if href can't be resolved.
     _logger.warning('link rel="$rel" missing href.', span: node.sourceSpan);
   }
 
-  /** Produce warnings if using `<element>` instead of `<polymer-element>`. */
+  /// Produce warnings if using `<element>` instead of `<polymer-element>`.
   void _validateElementElement(Element node) {
     _logger.warning('<element> elements are not supported, use'
         ' <polymer-element> instead', span: node.sourceSpan);
   }
 
-  /**
-   * Produce warnings if using `<polymer-element>` in the wrong place or if the
-   * definition is not complete.
-   */
+  /// Produce warnings if using `<polymer-element>` in the wrong place or if the
+  /// definition is not complete.
   void _validatePolymerElement(Element node) {
     if (_inPolymerElement) {
       _logger.error('Nested polymer element definitions are not allowed.',
           span: node.sourceSpan);
       return;
     }
 
     var tagName = node.attributes['name'];
     var extendsTag = node.attributes['extends'];
 
@@ skipping 25 matching lines @@
         if (!_validateCustomAttributeName(attr, attrsSpan)) break;
       }
     }
 
     var oldValue = _inPolymerElement;
     _inPolymerElement = true;
     super.visitElement(node);
     _inPolymerElement = oldValue;
   }
 
-  /**
-   * Produces warnings for malformed script tags. In html5 leaving off type= is
-   * fine, but it defaults to text/javascript. Because this might be a common
-   * error, we warn about it when  src file ends in .dart, but the type is
-   * incorrect, or when users write code in an inline script tag of a custom
-   * element.
-   *
-   * The hope is that these cases shouldn't break existing valid code, but that
-   * they'll help Polymer authors avoid having their Dart code accidentally
-   * interpreted as JavaScript by the browser.
-   */
+  /// Produces warnings for malformed script tags. In html5 leaving off type= is
+  /// fine, but it defaults to text/javascript. Because this might be a common
+  /// error, we warn about it when  src file ends in .dart, but the type is
+  /// incorrect, or when users write code in an inline script tag of a custom
+  /// element.
+  ///
+  /// The hope is that these cases shouldn't break existing valid code, but that
+  /// they'll help Polymer authors avoid having their Dart code accidentally
+  /// interpreted as JavaScript by the browser.
   void _validateScriptElement(Element node) {
     var scriptType = node.attributes['type'];
     var isDart = scriptType == 'application/dart';
     var src = node.attributes['src'];
 
     if (scriptType == null) {
       if (src == null && _inPolymerElement) {
         // TODO(sigmund): revisit this check once we start interop with polymer
         // elements written in JS. Maybe we need to inspect the contents of the
         // script to find whether there is an import or something that indicates
@@ skipping 29 matching lines @@
           span: node.sourceSpan);
       return;
     }
 
     if (node.innerHtml.trim() != '') {
       _logger.warning('script tag has "src" attribute and also has script '
           'text.', span: node.sourceSpan);
     }
   }
 
-  /**
-   * Produces warnings for misuses of on-foo event handlers, and for instanting
-   * custom tags incorrectly.
-   */
+  /// Produces warnings for misuses of on-foo event handlers, and for instanting
+  /// custom tags incorrectly.
   void _validateNormalElement(Element node) {
     // Event handlers only allowed inside polymer-elements
     node.attributes.forEach((name, value) {
       if (name is String && name.startsWith('on')) {
         _validateEventHandler(node, name, value);
       }
     });
 
     // Validate uses of custom-tags
     var nodeTag = node.localName;
@@ skipping 42 matching lines @@
     }
 
     if (hasIsAttribute && baseTag != nodeTag) {
       _logger.warning(
           'custom element "$customTagName" extends from "$baseTag". '
           'Did you mean to write <$baseTag is="$customTagName">?',
           span: node.sourceSpan);
     }
   }
 
-  /**
-   * Validate an attribute on a custom-element. Returns true if valid.
-   */
+  /// Validate an attribute on a custom-element. Returns true if valid.
   bool _validateCustomAttributeName(String name, FileSpan span) {
     if (name.contains('-')) {
       var newName = toCamelCase(name);
       _logger.warning('PolymerElement no longer recognizes attribute names with '
           'dashes such as "$name". Use "$newName" or "${newName.toLowerCase()}" '
           'instead (both forms are equivalent in HTML).', span: span);
       return false;
     }
     return true;
   }
 
-  /** Validate event handlers are used correctly. */
+  /// Validate event handlers are used correctly.
   void _validateEventHandler(Element node, String name, String value) {
     if (!name.startsWith('on-')) {
       _logger.warning('Event handler "$name" will be interpreted as an inline'
           ' JavaScript event handler. Use the form '
           'on-event-name="handlerName" if you want a Dart handler '
           'that will automatically update the UI based on model changes.',
           span: node.attributeSpans[name]);
       return;
     }
 
@@ skipping 19 matching lines @@
   'annotation-xml': '',
   'color-profile': '',
   'font-face': '',
   'font-face-src': '',
   'font-face-uri': '',
   'font-face-format': '',
   'font-face-name': '',
   'missing-glyph': '',
 };
 
-/**
- * Returns true if this is a valid custom element name. See:
- * <https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/index.html#dfn-custom-element-name>
- */
+/// Returns true if this is a valid custom element name. See:
+/// <https://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/custom/index.html#dfn-custom-element-name>
 bool _isCustomTag(String name) {
   if (name == null || !name.contains('-')) return false;
   return !_invalidTagNames.containsKey(name);
 }
 
 const String USE_INIT_DART =
     'To run a polymer application, you need to call "initPolymer". You can '
     'either include a generic script tag that does this for you:'
     '\'<script type="application/dart">export "package:polymer/init.dart";'
     '</script>\' or add your own script tag and call that function. '
     'Make sure the script tag is placed after all HTML imports.';
 
 const String BOOT_JS_DEPRECATED =
     '"boot.js" is now deprecated. Instead, you can initialize your polymer '
     'application by calling "initPolymer()" in your main. If you don\'t have a '
     'main, then you can include our generic main by adding the following '
     'script tag to your page: \'<script type="application/dart">export '
     '"package:polymer/init.dart";</script>\'. Additionally you need to '
     'include: \'<script src="packages/browser/dart.js"></script>\' in the page '
     'too. Make sure these script tags come after all HTML imports.';