diff --git a/paper-icon-button.html b/paper-icon-button.html
index 23a04a1..f1e54b5 100644
--- a/paper-icon-button.html
+++ b/paper-icon-button.html
@@ -8,29 +8,31 @@
 -->
 
 <!--
-/**
- * @group Paper Elements
- *
- * `paper-icon-button` is a button with an image placed at the center.
- *
- * Example:
- *
- *     <paper-icon-button src="star.png"></paper-icon-button>
- *
- * `paper-icon-button` includes a default icon set.  Use `icon` to specify 
- * which icon from the icon set to use.
- *
- * Example:
- *
- *     <paper-icon-button icon="menu"></paper-icon-button>
- *
- * See <a href="core-iconset.html">core-iconset</a> for more information about 
- * how to use a custom icon set.
- *
- * @element paper-icon-button
- * @extends paper-button
- * @homepage github.io
- */
+@group Paper Elements
+`paper-icon-button` is a button with an image placed at the center.
+
+Example:
+
+    <paper-icon-button src="star.png"></paper-icon-button>
+
+`paper-icon-button` includes a default icon set.  Use `icon` to specify 
+which icon from the icon set to use.
+
+Example:
+
+    <paper-icon-button icon="menu"></paper-icon-button>
+
+The icons provided by `core-icons` are SVG, and you can style them with CSS.
+
+Example:
+
+    <paper-icon-button icon="favorite" style="fill:red;"></paper-icon-button>
+
+See `core-iconset` for more information about how to use a custom icon set.
+
+@element paper-icon-button
+@extends paper-button
+@homepage github.io
 -->
 
 <link href="../core-icon/core-icon.html" rel="import">
@@ -53,7 +55,7 @@
       publish: {
 
         /**
-         * If true, the ripple expands to a square fill the containing box.
+         * If true, the ripple expands to a square to fill the containing box.
          *
          * @attribute fill
          * @type boolean