simplify comment style, update README.md

Author: Scott J. Miles

README.md

@@ -1,4 +1,4 @@
 core-icon
 =========
 
-See //polymer.github.io/core-icon
+See the [component page](http://polymer.github.io/core-icon) for more information.

core-icon.html

@@ -7,80 +7,76 @@
 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
 -->
 <!--
-/**
- *
- * @group Polymer Core Elements
- *
- * The `core-icon` element displays an icon using CSS background image. By default an icon renders as 24px square.
- *
- *
- * Example using src:
- *
- *     <core-icon src="star.png"></core-icon>
- *
- * Example setting size to 32px x 32px:
- *
- *     <core-icon src="big_star.png" size="32"></core-icon>
- *
- * Example using icon from default iconset:
- *
- *     <core-icon icon="menu"></core-icon>
- *
- * Example using icon `cherry` from custom iconset `fruit`:
- *
- *     <core-icon icon="fruit:cherry"></core-icon>
- *
- * See <a href="#core-iconset">core-iconset</a> for more information about 
- * how to use a custom iconset.
- *
- * The default set of includes these icons:
- *
- * <div theme="core-light-theme">
- * <core-icon icon="drawer"></core-icon> drawer,
- * <core-icon icon="menu"></core-icon> menu,
- * <core-icon icon="search"></core-icon> search,
- * <core-icon icon="dropdown"></core-icon> dropdown,
- * <core-icon icon="close"></core-icon> close,
- * <core-icon icon="add"></core-icon> add,
- * <core-icon icon="trash"></core-icon> trash,
- * <core-icon icon="refresh"></core-icon> refresh,
- * <core-icon icon="settings"></core-icon> settings,
- * <core-icon icon="dialoga"></core-icon> dialoga,
- * <core-icon icon="left"></core-icon> left,
- * <core-icon icon="right"></core-icon> right,
- * <core-icon icon="down"></core-icon> down,
- * <core-icon icon="up"></core-icon> up,
- * <core-icon icon="grid"></core-icon> grid,
- * <core-icon icon="contact"></core-icon> contact,
- * <core-icon icon="account"></core-icon> account,
- * <core-icon icon="plus"></core-icon> plus,
- * <core-icon icon="time"></core-icon> time,
- * <core-icon icon="marker"></core-icon> marker,
- * <core-icon icon="briefcase"></core-icon> briefcase,
- * <core-icon icon="array"></core-icon> array,
- * <core-icon icon="columns"></core-icon> columns,
- * <core-icon icon="list"></core-icon> list,
- * <core-icon icon="modules"></core-icon> modules,
- * <core-icon icon="quilt"></core-icon> quilt,
- * <core-icon icon="stream"></core-icon> stream,
- * <core-icon icon="maximize"></core-icon> maximize,
- * <core-icon icon="shrink"></core-icon> shrink,
- * <core-icon icon="sort"></core-icon> sort,
- * <core-icon icon="shortcut"></core-icon> shortcut,
- * <core-icon icon="dialog"></core-icon> dialog,
- * <core-icon icon="twitter"></core-icon> twitter,
- * <core-icon icon="facebook"></core-icon> facebook,
- * <core-icon icon="favorite"></core-icon> favorite,
- * <core-icon icon="gplus"></core-icon> gplus,
- * <core-icon icon="filter"></core-icon> filter,
- * <core-icon icon="tag"></core-icon> tag,
- * <core-icon icon="plusone"></core-icon> plusone,
- * <core-icon icon="dots"></core-icon> dots,
- * </div>
- *
- * @element core-icon
- * @homepage github.io
- */
+
+The `core-icon` element displays an icon using CSS background image. By default an icon renders as 24px square.
+
+Example using src:
+
+    <core-icon src="star.png"></core-icon>
+
+Example setting size to 32px x 32px:
+
+    <core-icon src="big_star.png" size="32"></core-icon>
+
+Example using icon from default iconset:
+
+    <core-icon icon="menu"></core-icon>
+
+Example using icon `cherry` from custom iconset `fruit`:
+
+    <core-icon icon="fruit:cherry"></core-icon>
+
+See <a href="#core-iconset">core-iconset</a> for more information about 
+how to use a custom iconset.
+
+The default set of includes these icons:
+
+<div theme="core-light-theme">
+  <core-icon icon="drawer"></core-icon> drawer,
+  <core-icon icon="menu"></core-icon> menu,
+  <core-icon icon="search"></core-icon> search,
+  <core-icon icon="dropdown"></core-icon> dropdown,
+  <core-icon icon="close"></core-icon> close,
+  <core-icon icon="add"></core-icon> add,
+  <core-icon icon="trash"></core-icon> trash,
+  <core-icon icon="refresh"></core-icon> refresh,
+  <core-icon icon="settings"></core-icon> settings,
+  <core-icon icon="dialoga"></core-icon> dialoga,
+  <core-icon icon="left"></core-icon> left,
+  <core-icon icon="right"></core-icon> right,
+  <core-icon icon="down"></core-icon> down,
+  <core-icon icon="up"></core-icon> up,
+  <core-icon icon="grid"></core-icon> grid,
+  <core-icon icon="contact"></core-icon> contact,
+  <core-icon icon="account"></core-icon> account,
+  <core-icon icon="plus"></core-icon> plus,
+  <core-icon icon="time"></core-icon> time,
+  <core-icon icon="marker"></core-icon> marker,
+  <core-icon icon="briefcase"></core-icon> briefcase,
+  <core-icon icon="array"></core-icon> array,
+  <core-icon icon="columns"></core-icon> columns,
+  <core-icon icon="list"></core-icon> list,
+  <core-icon icon="modules"></core-icon> modules,
+  <core-icon icon="quilt"></core-icon> quilt,
+  <core-icon icon="stream"></core-icon> stream,
+  <core-icon icon="maximize"></core-icon> maximize,
+  <core-icon icon="shrink"></core-icon> shrink,
+  <core-icon icon="sort"></core-icon> sort,
+  <core-icon icon="shortcut"></core-icon> shortcut,
+  <core-icon icon="dialog"></core-icon> dialog,
+  <core-icon icon="twitter"></core-icon> twitter,
+  <core-icon icon="facebook"></core-icon> facebook,
+  <core-icon icon="favorite"></core-icon> favorite,
+  <core-icon icon="gplus"></core-icon> gplus,
+  <core-icon icon="filter"></core-icon> filter,
+  <core-icon icon="tag"></core-icon> tag,
+  <core-icon icon="plusone"></core-icon> plusone,
+  <core-icon icon="dots"></core-icon> dots,
+</div>
+
+@group Polymer Core Elements
+@element core-icon
+@homepage github.io
 -->
 
 <link rel="import" href="../core-theme-aware/core-theme-aware.html">