Refined types for most HtmlElement factory constructors

tools/dom/templates/html/impl/impl_Element.darttemplate

 // Copyright (c) 2012, 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 $LIBRARYNAME;
 
 class _ChildrenElementList extends ListBase<Element>
     implements NodeListWrapper {
   // Raw Element.
   final Element _element;
@@ skipping 384 matching lines @@
    *
    * This is similar to [Document.createElement].
    * [tag] should be a valid HTML tag name. If [tag] is an unknown tag then
    * this will create an [UnknownElement].
    *
    *     var divElement = new Element.tag('div');
    *     print(divElement is DivElement); // 'true'
    *     var myElement = new Element.tag('unknownTag');
    *     print(myElement is UnknownElement); // 'true'
    *
-   * For standard elements it is more preferable to use the type constructors:
+   * For standard elements it is better to use the element type constructors:
+   *
    *     var element = new DivElement();
    *
+   * It is better to use e.g `new CanvasElement()` because the type of the
+   * expression is `CanvasElement`, whereas the type of `Element.tag` is the
+   * less specific `Element`.
+   *
    * See also:
    *
    * * [isTagSupported]
    */
   factory $CLASSNAME.tag(String tag, [String typeExtention]) =>
       _$(CLASSNAME)FactoryProvider.createElement_tag(tag, typeExtention);
 
   /// Creates a new `<a>` element.
   ///
-  /// This is identical to calling `new Element.tag('a')`.
-  factory Element.a() => new Element.tag('a');
+  /// This is equivalent to calling `new Element.tag('a')`.
+  factory Element.a() => new AnchorElement();
 
   /// Creates a new `<article>` element.
   ///
-  /// This is identical to calling `new Element.tag('article')`.
+  /// This is equivalent to calling `new Element.tag('article')`.
   factory Element.article() => new Element.tag('article');
 
   /// Creates a new `<aside>` element.
   ///
-  /// This is identical to calling `new Element.tag('aside')`.
+  /// This is equivalent to calling `new Element.tag('aside')`.
   factory Element.aside() => new Element.tag('aside');
 
   /// Creates a new `<audio>` element.
   ///
-  /// This is identical to calling `new Element.tag('audio')`.
+  /// This is equivalent to calling `new Element.tag('audio')`.
   factory Element.audio() => new Element.tag('audio');
 
   /// Creates a new `<br>` element.
   ///
-  /// This is identical to calling `new Element.tag('br')`.
-  factory Element.br() => new Element.tag('br');
+  /// This is equivalent to calling `new Element.tag('br')`.
+  factory Element.br() => new BRElement();
 
   /// Creates a new `<canvas>` element.
   ///
-  /// This is identical to calling `new Element.tag('canvas')`.
-  factory Element.canvas() => new Element.tag('canvas');
+  /// This is equivalent to calling `new Element.tag('canvas')`.
+  factory Element.canvas() => new CanvasElement();
 
   /// Creates a new `<div>` element.
   ///
-  /// This is identical to calling `new Element.tag('div')`.
-  factory Element.div() => new Element.tag('div');
+  /// This is equivalent to calling `new Element.tag('div')`.
+  factory Element.div() => new DivElement();
 
   /// Creates a new `<footer>` element.
   ///
-  /// This is identical to calling `new Element.tag('footer')`.
+  /// This is equivalent to calling `new Element.tag('footer')`.
   factory Element.footer() => new Element.tag('footer');
 
   /// Creates a new `<header>` element.
   ///
-  /// This is identical to calling `new Element.tag('header')`.
+  /// This is equivalent to calling `new Element.tag('header')`.
   factory Element.header() => new Element.tag('header');
 
   /// Creates a new `<hr>` element.
   ///
-  /// This is identical to calling `new Element.tag('hr')`.
+  /// This is equivalent to calling `new Element.tag('hr')`.
   factory Element.hr() => new Element.tag('hr');
 
   /// Creates a new `<iframe>` element.
   ///
-  /// This is identical to calling `new Element.tag('iframe')`.
+  /// This is equivalent to calling `new Element.tag('iframe')`.
   factory Element.iframe() => new Element.tag('iframe');
 
   /// Creates a new `<img>` element.
   ///
-  /// This is identical to calling `new Element.tag('img')`.
+  /// This is equivalent to calling `new Element.tag('img')`.
   factory Element.img() => new Element.tag('img');
 
   /// Creates a new `<li>` element.
   ///
-  /// This is identical to calling `new Element.tag('li')`.
+  /// This is equivalent to calling `new Element.tag('li')`.
   factory Element.li() => new Element.tag('li');
 
   /// Creates a new `<nav>` element.
   ///
-  /// This is identical to calling `new Element.tag('nav')`.
+  /// This is equivalent to calling `new Element.tag('nav')`.
   factory Element.nav() => new Element.tag('nav');
 
   /// Creates a new `<ol>` element.
   ///
-  /// This is identical to calling `new Element.tag('ol')`.
+  /// This is equivalent to calling `new Element.tag('ol')`.
   factory Element.ol() => new Element.tag('ol');
 
   /// Creates a new `<option>` element.
   ///
-  /// This is identical to calling `new Element.tag('option')`.
+  /// This is equivalent to calling `new Element.tag('option')`.
   factory Element.option() => new Element.tag('option');
 
   /// Creates a new `<p>` element.
   ///
-  /// This is identical to calling `new Element.tag('p')`.
+  /// This is equivalent to calling `new Element.tag('p')`.
   factory Element.p() => new Element.tag('p');
 
   /// Creates a new `<pre>` element.
   ///
-  /// This is identical to calling `new Element.tag('pre')`.
+  /// This is equivalent to calling `new Element.tag('pre')`.
   factory Element.pre() => new Element.tag('pre');
 
   /// Creates a new `<section>` element.
   ///
-  /// This is identical to calling `new Element.tag('section')`.
+  /// This is equivalent to calling `new Element.tag('section')`.
   factory Element.section() => new Element.tag('section');
 
   /// Creates a new `<select>` element.
   ///
-  /// This is identical to calling `new Element.tag('select')`.
+  /// This is equivalent to calling `new Element.tag('select')`.
   factory Element.select() => new Element.tag('select');
 
   /// Creates a new `<span>` element.
   ///
-  /// This is identical to calling `new Element.tag('span')`.
+  /// This is equivalent to calling `new Element.tag('span')`.
   factory Element.span() => new Element.tag('span');
 
   /// Creates a new `<svg>` element.
   ///
-  /// This is identical to calling `new Element.tag('svg')`.
+  /// This is equivalent to calling `new Element.tag('svg')`.
   factory Element.svg() => new Element.tag('svg');
 
   /// Creates a new `<table>` element.
   ///
-  /// This is identical to calling `new Element.tag('table')`.
+  /// This is equivalent to calling `new Element.tag('table')`.
   factory Element.table() => new Element.tag('table');
 
   /// Creates a new `<td>` element.
   ///
-  /// This is identical to calling `new Element.tag('td')`.
+  /// This is equivalent to calling `new Element.tag('td')`.
   factory Element.td() => new Element.tag('td');
 
   /// Creates a new `<textarea>` element.
   ///
-  /// This is identical to calling `new Element.tag('textarea')`.
+  /// This is equivalent to calling `new Element.tag('textarea')`.
   factory Element.textarea() => new Element.tag('textarea');
 
   /// Creates a new `<th>` element.
   ///
-  /// This is identical to calling `new Element.tag('th')`.
+  /// This is equivalent to calling `new Element.tag('th')`.
   factory Element.th() => new Element.tag('th');
 
   /// Creates a new `<tr>` element.
   ///
-  /// This is identical to calling `new Element.tag('tr')`.
+  /// This is equivalent to calling `new Element.tag('tr')`.
   factory Element.tr() => new Element.tag('tr');
 
   /// Creates a new `<ul>` element.
   ///
-  /// This is identical to calling `new Element.tag('ul')`.
+  /// This is equivalent to calling `new Element.tag('ul')`.
   factory Element.ul() => new Element.tag('ul');
 
   /// Creates a new `<video>` element.
   ///
-  /// This is identical to calling `new Element.tag('video')`.
+  /// This is equivalent to calling `new Element.tag('video')`.
   factory Element.video() => new Element.tag('video');
 
   /**
    * All attributes on this element.
    *
    * Any modifications to the attribute map will automatically be applied to
    * this element.
    *
    * This only includes attributes which are not in a namespace
    * (such as 'xlink:href'), additional attributes can be accessed via
@@ skipping 1101 matching lines @@
   const ScrollAlignment._internal(this._value);
   toString() => 'ScrollAlignment.$_value';
 
   /// Attempt to align the element to the top of the scrollable area.
   static const TOP = const ScrollAlignment._internal('TOP');
   /// Attempt to center the element in the scrollable area.
   static const CENTER = const ScrollAlignment._internal('CENTER');
   /// Attempt to align the element to the bottom of the scrollable area.
   static const BOTTOM = const ScrollAlignment._internal('BOTTOM');
 }