Some general Grid maintenance (JavaDocs mostly) (#13334)

Change-Id: I6724ae2433b742b620d43cb564798d59be805545

5 files changed, 130 insertions, 104 deletions

diff --git a/client/src/com/vaadin/client/ui/grid/Cell.java b/client/src/com/vaadin/client/ui/grid/Cell.java
index 45a7eef554..4e1fc0d56a 100644
--- a/client/src/com/vaadin/client/ui/grid/Cell.java
+++ b/client/src/com/vaadin/client/ui/grid/Cell.java
@@ -19,10 +19,12 @@ import com.google.gwt.dom.client.Element;
 
 /**
  * Describes a cell
- * 
- * TODO The description is still very vague since the content and naming of this
- * class is still under debate and the API is not final. Improve the description
- * when API has been finalized.
+ * <p>
+ * It's a representation of the element in a grid cell, and its row and column
+ * indices.
+ * <p>
+ * Unlike the {@link FlyweightRow}, an instance of {@link Cell} can be stored in
+ * a field.
  * 
  * @since
  * @author Vaadin Ltd
@@ -36,7 +38,7 @@ public class Cell {
     private final Element element;
 
     /**
-     * Constructs a new {@link Cell}
+     * Constructs a new {@link Cell}.
      * 
      * @param row
      *            The index of the row
@@ -53,7 +55,7 @@ public class Cell {
     }
 
     /**
-     * Returns the index of the row the cell resides on
+     * Returns the index of the row the cell resides in.
      * 
      * @return the row index
      * 
@@ -63,7 +65,7 @@ public class Cell {
     }
 
     /**
-     * Returns the index of the column the cell resides on
+     * Returns the index of the column the cell resides in.
      * 
      * @return the column index
      */
@@ -72,9 +74,9 @@ public class Cell {
     }
 
     /**
-     * Returns the element of the cell
+     * Returns the element of the cell.
      * 
-     * @return the element
+     * @return the cell element
      */
     public Element getElement() {
         return element;
diff --git a/client/src/com/vaadin/client/ui/grid/ColumnConfiguration.java b/client/src/com/vaadin/client/ui/grid/ColumnConfiguration.java
index e69b5e7a48..f523fdbbd4 100644
--- a/client/src/com/vaadin/client/ui/grid/ColumnConfiguration.java
+++ b/client/src/com/vaadin/client/ui/grid/ColumnConfiguration.java
@@ -26,7 +26,7 @@ package com.vaadin.client.ui.grid;
 public interface ColumnConfiguration {
 
     /**
-     * Removes columns at a certain index.
+     * Removes columns at certain indices.
      * <p>
      * If any of the removed columns were frozen, the number of frozen columns
      * will be reduced by the number of the removed columns that were frozen.
@@ -34,11 +34,10 @@ public interface ColumnConfiguration {
      * @param index
      *            the index of the first column to be removed
      * @param numberOfColumns
-     *            the number of rows to remove, starting from the index
+     *            the number of rows to remove, starting from {@code index}
      * @throws IndexOutOfBoundsException
-     *             if any integer in the range
-     *             <code>[index..(index+numberOfColumns)]</code> is not an
-     *             existing column index.
+     *             if the entire range of removed columns is not currently
+     *             present in the escalator
      * @throws IllegalArgumentException
      *             if <code>numberOfColumns</code> is less than 1.
      */
diff --git a/client/src/com/vaadin/client/ui/grid/ColumnGroup.java b/client/src/com/vaadin/client/ui/grid/ColumnGroup.java
index c58f90f10b..13468a0d8e 100644
--- a/client/src/com/vaadin/client/ui/grid/ColumnGroup.java
+++ b/client/src/com/vaadin/client/ui/grid/ColumnGroup.java
@@ -24,15 +24,15 @@ import java.util.List;
 import com.vaadin.client.ui.grid.renderers.TextRenderer;
 
 /**
- * Column groups are used to group columns together for adding common auxiliary
- * headers and footers. Columns groups are added to {@link ColumnGroupRow
- * ColumnGroupRows}.
+ * A column group is a horizontal grouping of columns in a header or footer.
+ * Columns groups are added to {@link ColumnGroupRow ColumnGroupRows}.
  * 
  * @param <T>
  *            The row type of the grid. The row type is the POJO type from where
  *            the data is retrieved into the column cells.
  * @since
  * @author Vaadin Ltd
+ * @see ColumnGroupRow#addGroup(ColumnGroup...)
  */
 public class ColumnGroup<T> {
 
@@ -81,7 +81,7 @@ public class ColumnGroup<T> {
     }
 
     /**
-     * Gets the header text.
+     * Gets the text shown in the header.
      * 
      * @return the header text
      */
@@ -92,61 +92,60 @@ public class ColumnGroup<T> {
     /**
      * Sets the text shown in the header.
      * 
-     * @param header
-     *            the header to set
+     * @param caption
+     *            the caption to set
      */
-    public void setHeaderCaption(String header) {
-        this.header = header;
+    public void setHeaderCaption(String caption) {
+        this.header = caption;
         grid.refreshHeader();
     }
 
     /**
      * Gets the text shown in the footer.
      * 
-     * @return the text in the footer
+     * @return the footer text
      */
     public String getFooterCaption() {
         return footer;
     }
 
     /**
-     * Sets the text displayed in the footer.
+     * Sets the text shown in the footer.
      * 
-     * @param footer
-     *            the footer to set
+     * @param caption
+     *            the caption to set
      */
-    public void setFooterCaption(String footer) {
-        this.footer = footer;
+    public void setFooterCaption(String caption) {
+        this.footer = caption;
         grid.refreshFooter();
     }
 
     /**
-     * Returns all column in this group. It includes the subgroups columns as
-     * well.
+     * Returns all columns in this group. This includes columns in all the
+     * sub-groups as well.
      * 
-     * @return unmodifiable list of columns
+     * @return an unmodifiable list of columns
      */
     public List<GridColumn<?, T>> getColumns() {
         return columns;
     }
 
     /**
-     * Returns the renderer used for rendering the header cells
+     * Returns the renderer for the header cells.
      * 
-     * @return a renderer that renders header cells
+     * @return the renderer for the header cells
      */
     public Renderer<String> getHeaderRenderer() {
         return headerRenderer;
     }
 
     /**
-     * Sets the renderer that renders header cells.
+     * Sets the renderer for the header cells.
      * 
      * @param renderer
-     *            The renderer to use for rendering header cells. Must not be
-     *            null.
+     *            a non-{@code null} renderer to use for the header cells.
      * @throws IllegalArgumentException
-     *             thrown when renderer is null
+     *             if {@code renderer} is {@code null}
      */
     public void setHeaderRenderer(Renderer<String> renderer) {
         if (renderer == null) {
@@ -157,9 +156,9 @@ public class ColumnGroup<T> {
     }
 
     /**
-     * Returns the renderer used for rendering the footer cells
+     * Returns the renderer for the footer cells.
      * 
-     * @return a renderer that renders footer cells
+     * @return the renderer for the footer cells
      */
     public Renderer<String> getFooterRenderer() {
         return footerRenderer;
@@ -169,10 +168,9 @@ public class ColumnGroup<T> {
      * Sets the renderer that renders footer cells.
      * 
      * @param renderer
-     *            The renderer to use for rendering footer cells. Must not be
-     *            null.
+     *            a non-{@code null} renderer for footer cells.
      * @throws IllegalArgumentException
-     *             thrown when renderer is null
+     *             if {@code renderer} is {@code null}
      */
     public void setFooterRenderer(Renderer<String> renderer) {
         if (renderer == null) {
diff --git a/client/src/com/vaadin/client/ui/grid/ColumnGroupRow.java b/client/src/com/vaadin/client/ui/grid/ColumnGroupRow.java
index 90e7c1f887..3c621fdd15 100644
--- a/client/src/com/vaadin/client/ui/grid/ColumnGroupRow.java
+++ b/client/src/com/vaadin/client/ui/grid/ColumnGroupRow.java
@@ -25,8 +25,8 @@ import java.util.List;
 import java.util.Set;
 
 /**
- * A column group row represents an auxiliary header or footer row added to the
- * grid. A column group row includes column groups that group columns together.
+ * A column group row represents an additional header or footer row in a
+ * {@link Grid}. A column group row contains {@link ColumnGroup ColumnGroups}.
  * 
  * @param <T>
  *            Row type
@@ -67,17 +67,28 @@ public class ColumnGroupRow<T> {
     }
 
     /**
-     * Add a new group to the row by using column instances.
+     * Adds a new group of columns to the column group row.
      * 
      * @param columns
-     *            The columns that should belong to the group
-     * @return a column group representing the collection of columns added to
-     *         the group.
+     *            The columns that should be added to the group
+     * @return the added columns as a column group
+     * @throws IllegalArgumentException
+     *             if any of {@code columns} already belongs to a group, or if
+     *             {@code columns} or any of its elements are {@code null}
      */
     public ColumnGroup<T> addGroup(GridColumn<?, T>... columns)
             throws IllegalArgumentException {
 
+        if (columns == null) {
+            throw new IllegalArgumentException("columns may not be null");
+        }
+
         for (GridColumn<?, T> column : columns) {
+            if (column == null) {
+                throw new IllegalArgumentException(
+                        "none of the given columns may be null");
+            }
+
             if (isColumnGrouped(column)) {
                 throw new IllegalArgumentException("Column "
                         + String.valueOf(column.getHeaderCaption())
@@ -141,20 +152,29 @@ public class ColumnGroupRow<T> {
     }
 
     /**
-     * Add a new group to the row by using other already greated groups
+     * Add a new group to the row by using other already created groups.
      * 
      * @param groups
-     *            The subgroups of the group.
-     * @return a column group representing the collection of columns added to
-     *         the group.
-     * 
+     *            the column groups to be further grouped together
+     * @return the added column groups as a new single group
+     * @throws IllegalArgumentException
+     *             if any column group already belongs to another group, or if
+     *             {@code groups} or any of its elements are null
      */
     public ColumnGroup<T> addGroup(ColumnGroup<T>... groups)
             throws IllegalArgumentException {
-        assert groups != null : "groups cannot be null";
+
+        if (groups == null) {
+            throw new IllegalArgumentException("groups may not be null");
+        }
 
         Set<GridColumn<?, T>> columns = new HashSet<GridColumn<?, T>>();
         for (ColumnGroup<T> group : groups) {
+            if (group == null) {
+                throw new IllegalArgumentException(
+                        "none of the given group may be null");
+            }
+
             columns.addAll(group.getColumns());
         }
 
@@ -169,39 +189,46 @@ public class ColumnGroupRow<T> {
 
     /**
      * Removes a group from the row.
+     * <p>
+     * <em>Note:</em> this removes only a group in the immediate hierarchy
+     * level, and does not search recursively.
      * 
      * @param group
      *            The group to remove
+     * @return {@code true} iff the group was successfully removed
      */
-    public void removeGroup(ColumnGroup<T> group) {
-        groups.remove(group);
-        grid.refreshHeader();
-        grid.refreshFooter();
+    public boolean removeGroup(ColumnGroup<T> group) {
+        boolean removed = groups.remove(group);
+        if (removed) {
+            grid.refreshHeader();
+            grid.refreshFooter();
+        }
+        return removed;
     }
 
     /**
-     * Get the groups in the row
+     * Gets the groups in this row.
      * 
-     * @return unmodifiable list of groups in this row
+     * @return an unmodifiable list of groups in this row
      */
     public List<ColumnGroup<T>> getGroups() {
         return Collections.unmodifiableList(groups);
     }
 
     /**
-     * Is the header visible for the row.
+     * Checks whether the header is visible for the row group or not.
      * 
-     * @return <code>true</code> if header is visible
+     * @return <code>true</code> iff the header is visible
      */
     public boolean isHeaderVisible() {
         return headerVisible;
     }
 
     /**
-     * Sets the header visible for the row.
+     * Sets the visibility of the row group's header.
      * 
      * @param visible
-     *            should the header be shown
+     *            {@code true} iff the header should be shown
      */
     public void setHeaderVisible(boolean visible) {
         headerVisible = visible;
@@ -209,19 +236,19 @@ public class ColumnGroupRow<T> {
     }
 
     /**
-     * Is the footer visible for the row.
+     * Checks whether the footer is visible for the row or not.
      * 
-     * @return <code>true</code> if footer is visible
+     * @return <code>true</code> iff footer is visible
      */
     public boolean isFooterVisible() {
         return footerVisible;
     }
 
     /**
-     * Sets the footer visible for the row.
+     * Sets the visibility of the row group's footer.
      * 
      * @param visible
-     *            should the footer be shown
+     *            {@code true} iff the footer should be shown
      */
     public void setFooterVisible(boolean visible) {
         footerVisible = visible;
@@ -229,8 +256,8 @@ public class ColumnGroupRow<T> {
     }
 
     /**
-     * Iterates all the column groups and checks if the columns alread has been
-     * added to a group.
+     * Iterates through all the column groups and checks if the columns already
+     * has been added to a group.
      */
     private boolean isColumnGrouped(GridColumn<?, T> column) {
         for (ColumnGroup<T> group : groups) {
diff --git a/client/src/com/vaadin/client/ui/grid/Escalator.java b/client/src/com/vaadin/client/ui/grid/Escalator.java
index 271e2509b7..0a237f3fca 100644
--- a/client/src/com/vaadin/client/ui/grid/Escalator.java
+++ b/client/src/com/vaadin/client/ui/grid/Escalator.java
@@ -63,6 +63,8 @@ import com.vaadin.shared.util.SharedUtil;
 /*-
 
  Maintenance Notes! Reading these might save your day.
+ (note for editors: line width is 80 chars, including the
+ one-space indentation)
 
 
  == Row Container Structure
@@ -71,7 +73,7 @@ import com.vaadin.shared.util.SharedUtil;
  |-- AbstractStaticRowContainer
  | |-- HeaderRowContainer
  | `-- FooterContainer
- `-- BodyRowContainer
+ `---- BodyRowContainer
 
  AbstractRowContainer is intended to contain all common logic
  between RowContainers. It manages the bookkeeping of row
@@ -134,15 +136,23 @@ import com.vaadin.shared.util.SharedUtil;
  element's visual index via the field
  BodyRowContainer.visualRowOrder.
 
+ Currently, the physical and visual indices are kept in sync
+ _most of the time_ by a deferred rearrangement of rows.
+ They become desynced when scrolling. This is to help screen
+ readers to read the contents from the DOM in a natural
+ order. See BodyRowContainer.DeferredDomSorter for more
+ about that.
+
  */
 
 /**
  * A workaround-class for GWT and JSNI.
  * <p>
  * GWT is unable to handle some method calls to Java methods in inner-classes
- * from within JSNI blocks. Having that inner class implement a non-inner-class
- * (or interface), makes it possible for JSNI to indirectly refer to the inner
- * class, by invoking methods and fields in the non-inner-class.
+ * from within JSNI blocks. Having that inner class extend a non-inner-class (or
+ * implement such an interface), makes it possible for JSNI to indirectly refer
+ * to the inner class, by invoking methods and fields in the non-inner-class
+ * API.
  * 
  * @see Escalator.Scroller
  */
@@ -248,10 +258,6 @@ public class Escalator extends Widget {
      * constant.
      */
     /*
-     * [[API]]: Implementing this suggestion would require a change in the
-     * public API. These suggestions usually don't come lightly.
-     */
-    /*
      * [[mpixscroll]]: This code will require alterations that are relevant for
      * supporting the scrolling through more pixels than some browsers normally
      * would support. (i.e. when we support more than "a million" pixels in the
@@ -4070,7 +4076,7 @@ public class Escalator extends Widget {
     }
 
     /**
-     * Returns the representation of this Escalator header.
+     * Returns the row container for the header in this Escalator.
      * 
      * @return the header. Never <code>null</code>
      */
@@ -4079,7 +4085,7 @@ public class Escalator extends Widget {
     }
 
     /**
-     * Returns the representation of this Escalator body.
+     * Returns the row container for the body in this Escalator.
      * 
      * @return the body. Never <code>null</code>
      */
@@ -4088,7 +4094,7 @@ public class Escalator extends Widget {
     }
 
     /**
-     * Returns the representation of this Escalator footer.
+     * Returns the row container for the footer in this Escalator.
      * 
      * @return the footer. Never <code>null</code>
      */
@@ -4148,7 +4154,7 @@ public class Escalator extends Widget {
 
     /**
      * Returns the vertical scroll offset. Note that this is not necessarily the
-     * same as the scroll top in the DOM
+     * same as the {@code scrollTop} attribute in the DOM.
      * 
      * @return the logical vertical scroll offset
      */
@@ -4157,8 +4163,8 @@ public class Escalator extends Widget {
     }
 
     /**
-     * Sets the vertical scroll offset. Note that this is not necessarily the
-     * same as the scroll top in the DOM
+     * Sets the vertical scroll offset. Note that this will not necessarily
+     * become the same as the {@code scrollTop} attribute in the DOM.
      * 
      * @param scrollTop
      *            the number of pixels to scroll vertically
@@ -4169,7 +4175,7 @@ public class Escalator extends Widget {
 
     /**
      * Returns the logical horizontal scroll offset. Note that this is not
-     * necessarily the same as the scroll left in the DOM.
+     * necessarily the same as the {@code scrollLeft} attribute in the DOM.
      * 
      * @return the logical horizontal scroll offset
      */
@@ -4178,8 +4184,8 @@ public class Escalator extends Widget {
     }
 
     /**
-     * Sets the logical horizontal scroll offset. Note that this is not
-     * necessarily the same as the scroll left in the DOM.
+     * Sets the logical horizontal scroll offset. Note that will not necessarily
+     * become the same as the {@code scrollLeft} attribute in the DOM.
      * 
      * @param scrollLeft
      *            the number of pixels to scroll horizontally
@@ -4190,8 +4196,8 @@ public class Escalator extends Widget {
 
     /**
      * Scrolls the body horizontally so that the column at the given index is
-     * visible and there is at least {@code padding} pixels to the given scroll
-     * destination.
+     * visible and there is at least {@code padding} pixels in the direction of
+     * the given scroll destination.
      * 
      * @param columnIndex
      *            the index of the column to scroll to
@@ -4205,9 +4211,7 @@ public class Escalator extends Widget {
      *             column
      * @throws IllegalArgumentException
      *             if {@code destination} is {@link ScrollDestination#MIDDLE}
-     *             and padding is nonzero, because having a padding on a
-     *             centered column is undefined behavior, or if the column is
-     *             frozen
+     *             and padding is nonzero, or if the indicated column is frozen
      */
     public void scrollToColumn(final int columnIndex,
             final ScrollDestination destination, final int padding)
@@ -4251,8 +4255,7 @@ public class Escalator extends Widget {
      *             if {@code rowIndex} is not a valid index for an existing row
      * @throws IllegalArgumentException
      *             if {@code destination} is {@link ScrollDestination#MIDDLE}
-     *             and padding is nonzero, because having a padding on a
-     *             centered row is undefined behavior
+     *             and padding is nonzero
      */
     public void scrollToRow(final int rowIndex,
             final ScrollDestination destination, final int padding)
@@ -4348,7 +4351,7 @@ public class Escalator extends Widget {
 
     /**
      * Adds an event handler that gets notified when the range of visible rows
-     * changes e.g. because of scrolling.
+     * changes e.g. because of scrolling or row resizing.
      * 
      * @param rowVisibilityChangeHandler
      *            the event handler
@@ -4376,14 +4379,14 @@ public class Escalator extends Widget {
     }
 
     /**
-     * Gets the range of currently visible rows
+     * Gets the range of currently visible rows.
      * 
      * @return range of visible rows
      */
     public Range getVisibleRowRange() {
-        return Range.between(
+        return Range.withLength(
                 body.getLogicalRowIndex(body.visualRowOrder.getFirst()),
-                body.getLogicalRowIndex(body.visualRowOrder.getLast()) + 1);
+                body.visualRowOrder.size());
     }
 
     /**
@@ -4473,12 +4476,9 @@ public class Escalator extends Widget {
      * @param rows
      *            the number of rows that should be visible in Escalator's body
      * @throws IllegalArgumentException
-     *             if {@code rows} is zero or less
-     * @throws IllegalArgumentException
-     *             if {@code rows} is {@link Double#isInifinite(double)
-     *             infinite}
-     * @throws IllegalArgumentException
-     *             if {@code rows} is {@link Double#isNaN(double) NaN}.
+     *             if {@code rows} is &leq; 0,
+     *             {@link Double#isInifinite(double) infinite} or
+     *             {@link Double#isNaN(double) NaN}.
      * @see #setHeightMode(HeightMode)
      */
     public void setHeightByRows(double rows) throws IllegalArgumentException {