diff --git a/lib/OpenLayers/Layer/Grid.js b/lib/OpenLayers/Layer/Grid.js
index 683b7f0fe9..4e04e4117d 100644
--- a/lib/OpenLayers/Layer/Grid.js
+++ b/lib/OpenLayers/Layer/Grid.js
@@ -94,13 +94,13 @@ OpenLayers.Layer.Grid = OpenLayers.Class(OpenLayers.Layer.HTTPRequest, {
     /**
      * APIProperty: transitionEffect
      * {String} The transition effect to use when the map is zoomed.
-     *
      * Two posible values:
-     *  - *null* No transition effect (the default).
-     *  - *resize*  Existing tiles are resized on zoom to provide a visual
-     *    effect of the zoom having taken place immediately.  As the
-     *    new tiles become available, they are drawn over top of the
-     *    resized tiles.
+     *
+     * null - No transition effect (the default).
+     * "resize" - Existing tiles are resized on zoom to provide a visual
+     * effect of the zoom having taken place immediately.  As the
+     * new tiles become available, they are drawn over top of the
+     * resized tiles.
      *
      * Using "resize" on non-opaque layers can cause undesired visual
      * effects. This is therefore discouraged.
@@ -201,15 +201,42 @@ OpenLayers.Layer.Grid = OpenLayers.Class(OpenLayers.Layer.HTTPRequest, {
      * {Number} Delay for removing the backbuffer when all tiles have finished
      *     loading. Can be set to 0 when no css opacity transitions for the
      *     olTileImage class are used. Default is 0 for <singleTile> layers,
-     *     2500 for tiled layers.
+     *     2500 for tiled layers. See <className> for more information on
+     *     tile animation.
      */
     removeBackBufferDelay: null,
 
     /**
      * APIProperty: className
-     * {String} Name of the class added to the layer div. Default is
-     *     "olLayerGridSingleTile" for <singleTile> layers, and
-     *     "olLayerGridTile" for non-<singleTile> layers.
+     * {String} Name of the class added to the layer div. If not set in the
+     *     options passed to the constructor then className defaults to
+     *     "olLayerGridSingleTile" for single tile layers (see <singleTile>),
+     *     and "olLayerGridTile" for non single tile layers.
+     *
+     * Note:
+     *
+     * The displaying of tiles is not animated by default for single tile
+     *     layers - OpenLayers' default theme (style.css) includes this:
+     * (code)
+     * .olLayerGridTile .olTileImage {
+     *     -webkit-transition: opacity 0.2s linear;
+     *     -moz-transition: opacity 0.2s linear;
+     *     -o-transition: opacity 0.2s linear;
+     *     transition: opacity 0.2s linear;
+     *  }
+     * (end)
+     * To animate tile displaying for any grid layer the following
+     *     CSS rule can be used:
+     * (code)
+     * .olTileImage {
+     *     -webkit-transition: opacity 0.2s linear;
+     *     -moz-transition: opacity 0.2s linear;
+     *     -o-transition: opacity 0.2s linear;
+     *     transition: opacity 0.2s linear;
+     * }
+     * (end)
+     * In that case, to avoid flash effects, <removeBackBufferDelay>
+     *     should not be zero.
      */
     className: null,