From ddb90073c5d377baf4b5ce991241a473b93b950e Mon Sep 17 00:00:00 2001
From: "Scott J. Miles" <sjmiles@google.com>
Date: Thu, 29 Aug 2013 23:14:18 -0700
Subject: [PATCH] more doc work on polymer-layout

---
 polymer-layout/polymer-layout.html | 154 +++++++++++++++--------------
 1 file changed, 81 insertions(+), 73 deletions(-)

diff --git a/polymer-layout/polymer-layout.html b/polymer-layout/polymer-layout.html
index 0a8acf6..5dfc643 100644
--- a/polymer-layout/polymer-layout.html
+++ b/polymer-layout/polymer-layout.html
@@ -11,104 +11,112 @@
  * `<polymer-layout>` arranges nodes horizontally via absolution positioning.
  * Set the `vertical` attribute (boolean) to arrange vertically instead.
  * 
+ * `<polymer-layout>` arranges it's <b>sibling elements</b>, not
+ * it's children.
+ *
  * One arranged node may be marked as elastic by giving it a `flex`
  * attribute (boolean).
- 
- * `<polymer-layout>` arranges it's sibling elements, not
- * it's children.
  *
- * Padding on the parent node is ignored.
- * Margin on arranged nodes is ignored.
+ * You may remove a node from layout by giving it a `nolayout`
+ * attribute (boolean).
+ * 
+ * CSS Notes:
  *
- * Example:
+ *  * `padding` is ignored on the parent node.
+ *  * `margin` is ignored on arranged nodes.
+ *  * `min-width` is ignored on arranged nodes, use `min-width` on the parent node
+ *    instead.
  *
- *     // arrange divs into columns
- *     // `flex` attribute on Column Two
- *     // makes that column elastic
+ * Example: 
  *
- *     <polymer-layout><polymer-layout>
- *     <div>Column One</div>
- *     <div flex>Column Two</div>
- *     <div>Column Three</div>
+ * Arrange three `div` into columns. `flex` attribute on Column Two makes that
+ * column elastic.
  *
- *      ----------------------------------------------------
- *      |--------------------------------------------------|
- *      ||Column One|-------Column Two-------|Column Three||
- *      |--------------------------------------------------|
- *      ----------------------------------------------------
+ *      <polymer-layout></polymer-layout>
+ *      <div>Column One</div>
+ *      <div flex>Column Two</div>
+ *      <div>Column Three</div>
+ *
+ *  Remember that `<polymer-layout>` arranges it's sibling elements, not it's children.
  *
  * If body has width 52 device pixels (in this case, ascii characters), call that 52px.
  * Column One has it's natural width of 12px (including border), Column Three has it's
  * natural width of 14px, body border uses 2px, and Column Two automatically uses the
  * remaining space: 24px.
  *
+ *      |-                    52px                        -| 
+ *      ----------------------------------------------------
+ *      ||Column One||      Column Two      ||Column Three||
+ *      ----------------------------------------------------
+ *       |-  12px  -||-     (24px)         -||    14px   -|
+ *
  * As the parent node resizes, the elastic column reacts via CSS to adjust it's size.
- * No javascript is used so the performance is generally ideal.
+ * No javascript is used during parent resizing, for best performance. 
+ *
+ * Changes in content or sibling size is not handled automatically. 
  *
  *      --------------------------------------------------------------------------
- *      |------------------------------------------------------------------------|
- *      ||Column One|------------------Column Two------------------|Column Three||
- *      |------------------------------------------------------------------------|
+ *      ||Column One|                  Column Two                  |Column Three||
  *      --------------------------------------------------------------------------
  *
- *      ----------------------------------- ----
- *      |--------------------------------------|
- *      ||Column One|-Column Two-|Column Three||
- *      |--------------------------------------|
- *      ----------------------------------------
+ *      --------------------------------------
+ *      ||Column One|Column Two|Column Three||
+ *      --------------------------------------
  *
  * Arrange in rows by adding the `vertical` attribute.
  *
  * Example:
  *
- *     // arrange divs into rows
- *
- *     <polymer-layout vertical><polymer-layout>
- *     <div>Row One</div>
- *     <div flex>Row Two</div>
- *     <div>Row Three</div>
- *
- *     -------------                 -------------
- *     ||---------||                 ||---------||
- *     ||Row One  ||                 ||Row One  ||
- *     ||---------||                 ||---------||
- *     ||Row Two  ||                 ||Row Two  ||
- *     ||---------||                 ||         ||
- *     ||Row Three||                 ||         ||
- *     ||---------||                 ||         ||
- *     -------------                 ||         ||
- *                                   ||         ||
- *                                   ||         ||
- *                                   ||---------||
- *                                   ||Row Three||
- *                                   ||---------||
- *                                   -------------
+ *      <polymer-layout vertical></polymer-layout>
+ *      <div>Row One</div>
+ *      <div flex>Row Two</div>
+ *      <div>Row Three</div>
+ *
+ * This setup will cause Row Two to stretch to fill the container.
+ *
+ *      -----------             -----------
+ *      |---------|             |---------|
+ *      |         |             |         |
+ *      |Row One  |             |Row One  |
+ *      |         |             |         |
+ *      |---------|             |---------|
+ *      |         |             |         |
+ *      |Row Two  |             |Row Two  |
+ *      |         |             |         |
+ *      |---------|             |         |
+ *      |         |             |         |
+ *      |Row Three|             |         |
+ *      |         |             |---------|
+ *      |---------|             |         |
+ *      -----------             |Row Three|
+ *                              |         |
+ *                              |---------|
+ *                              |---------|
  *
  * Layouts can be nested arbitrarily.
  *
- *     <polymer-layout><polymer-layout>
- *     <div>Menu</div>
- *     <div flex>
- *      <polymer-layout vertical><polymer-layout>
- *      <div>Title</div>
- *      <div>Toolbar</div>
- *      <div>Main</div>
- *      <div>Footer</div>
- *     </div>
- *
- *     --------------------------------
- *     |-----------------------------||
- *     ||Menu     ||Title            ||
- *     ||         ||-----------------||
- *     ||         ||Toolbar          ||
- *     ||         ||-----------------||
- *     ||         ||Main             ||
- *     ||         ||                 ||
- *     ||         ||                 ||
- *     ||         ||-----------------||
- *     ||         ||Footer           ||
- *     ||         ||-----------------||
- *     --------------------------------
+ *      <polymer-layout></polymer-layout>
+ *      <div>Menu</div>
+ *      <div flex>
+ *         <polymer-layout vertical></polymer-layout>
+ *         <div>Title</div>
+ *         <div>Toolbar</div>
+ *         <div flex>Main</div>
+ *         <div>Footer</div>
+ *      </div>
+ *
+ * Renders something like this
+ *
+ *      --------------------------------
+ *      ||Menu     ||Title            ||
+ *      ||         ||-----------------||
+ *      ||         ||Toolbar          ||
+ *      ||         ||-----------------||
+ *      ||         ||Main             ||
+ *      ||         ||                 ||
+ *      ||         ||-----------------||
+ *      ||         ||Footer           ||
+ *      --------------------------------
  *
  * @class polymer-layout
  *
@@ -143,7 +151,7 @@
         if (cs.position === 'static') {
           parent.style.position = 'relative';
         }
-        parent.style.overflow = 'hidden';
+        //parent.style.overflow = 'hidden';
         // changes will cause another recalc at next validation step
         var vertical;
         this.parentNode.childNodes.forEach(function(c, i) {