 import mx.layout.VerticalAlign;
 
 /**
- *  Documentation is not currently available.
+ *  TileLayout arranges the layout elements in columns and rows
+ *  of equally-sized cells.
+ *
+ *  There are a number of properties that control orientation,
+ *  count, size, gap and justification of the columns and the rows
+ *  as well as element alignment within the cells.
+ *
+ *  Per-element supported constraints are percentWidth, percentHeight.
+ *  Element's minimum and maximum sizes will always be respected and
+ *  where possible, element's size will be limited to less then or equal
+ *  of the cell size.
+ *
+ *  When not explicitly set, the columnWidth is calculated as the maximum
+ *  preferred bounds width of all elements and the columnHeight is calculated
+ *  as the maximum preferred bounds height of all elements.
+ *
+ *  When not explicitly set, the columnCount and rowCount are calculated from
+ *  any explicit width/height settings for the layout target and columnWidth
+ *  and columnHeight.  In case none is specified, the coulumnCount and rowCount
+ *  values are picked so that the resulting pixel area is as square as possible.
+ * 
+ *  The measured size is calculated from the columnCount, rowCount, 
+ *  columnWidth, rowHeight and the gap sizes.
+ *
+ *  The default measured size, when no properties were explicitly set, is
+ *  as square as possible area and is enough to fit all elements.
+ *
+ *  In other cases the measured size may not be big enough to fit all elements -
+ *  for example when both columnCount and rowCount are explicitly set to values
+ *  such that columnCount * rowCount < element count.
+ *
+ *  The minimum measured size is calculated the same way as the measured size but
+ *  it's guaranteed to encompass enough rows/columns along the minor axis to fit
+ *  all elements.
  */
 public class TileLayout extends LayoutBase
 {

        bounds.left = leftEdge(column);
        bounds.right = rightEdge(column);
        return bounds;
    } 

    /**
     *  @private 
     */    
    override protected function elementBoundsAboveScrollRect(scrollRect:Rectangle):Rectangle
    {
        var bounds:Rectangle = new Rectangle();

        updateActualValues(layoutTarget.explicitWidth, layoutTarget.explicitHeight);

        // For measure, any explicit overrides for rowCount and columnCount take precedence
        var columnCount:int = explicitColumnCount != -1 ? Math.max(1, explicitColumnCount) : _columnCount;
        var rowCount:int = explicitRowCount != -1 ? Math.max(1, explicitRowCount) : _rowCount;

        layoutTarget.measuredWidth = Math.round(columnCount * (_columnWidth + _horizontalGap) - _horizontalGap);
        layoutTarget.measuredHeight = Math.round(rowCount * (_rowHeight + _verticalGap) - _verticalGap);

        // measured min size is guaranteed to have enough rows/columns to fit all elements
        layoutTarget.measuredMinWidth = Math.round(_columnCount * (_columnWidth + _horizontalGap) - _horizontalGap);
        layoutTarget.measuredMinHeight = Math.round(_rowCount * (_rowHeight + _verticalGap) - _verticalGap);
    }

    /**
