diff --git a/core/java/android/view/ViewGroup.java b/core/java/android/view/ViewGroup.java
index 006aff896223a..eca583f46b221 100644
--- a/core/java/android/view/ViewGroup.java
+++ b/core/java/android/view/ViewGroup.java
@@ -3457,11 +3457,11 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
      * The base LayoutParams class just describes how big the view wants to be
      * for both width and height. For each dimension, it can specify one of:
      * <ul>
-     * <li> an exact number
-     * <li>MATCH_PARENT, which means the view wants to be as big as its parent
-     * (minus padding)
+     * <li>FILL_PARENT (renamed MATCH_PARENT in API Level 8 and higher), which
+     * means that the view wants to be as big as its parent (minus padding)
      * <li> WRAP_CONTENT, which means that the view wants to be just big enough
      * to enclose its content (plus padding)
+     * <li> an exact number
      * </ul>
      * There are subclasses of LayoutParams for different subclasses of
      * ViewGroup. For example, AbsoluteLayout has its own subclass of
@@ -3472,8 +3472,10 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
      */
     public static class LayoutParams {
         /**
-         * This value has the same meaning as {@link #MATCH_PARENT} but has
-         * been deprecated.
+         * Special value for the height or width requested by a View.
+         * FILL_PARENT means that the view wants to be as big as its parent,
+         * minus the parent's padding, if any. This value is deprecated
+         * starting in API Level 8 and replaced by {@link #MATCH_PARENT}.
          */
         @SuppressWarnings({"UnusedDeclaration"})
         @Deprecated
@@ -3482,7 +3484,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         /**
          * Special value for the height or width requested by a View.
          * MATCH_PARENT means that the view wants to be as big as its parent,
-         * minus the parent's padding, if any.
+         * minus the parent's padding, if any. Introduced in API Level 8.
          */
         public static final int MATCH_PARENT = -1;
 
@@ -3494,8 +3496,9 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         public static final int WRAP_CONTENT = -2;
 
         /**
-         * Information about how wide the view wants to be. Can be an exact
-         * size, or one of the constants MATCH_PARENT or WRAP_CONTENT.
+         * Information about how wide the view wants to be. Can be one of the
+         * constants FILL_PARENT (replaced by MATCH_PARENT ,
+         * in API Level 8) or WRAP_CONTENT. or an exact size.
          */
         @ViewDebug.ExportedProperty(mapping = {
             @ViewDebug.IntToString(from = MATCH_PARENT, to = "MATCH_PARENT"),
@@ -3504,8 +3507,9 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         public int width;
 
         /**
-         * Information about how tall the view wants to be. Can be an exact
-         * size, or one of the constants MATCH_PARENT or WRAP_CONTENT.
+         * Information about how tall the view wants to be. Can be one of the
+         * constants FILL_PARENT (replaced by MATCH_PARENT ,
+         * in API Level 8) or WRAP_CONTENT. or an exact size.
          */
         @ViewDebug.ExportedProperty(mapping = {
             @ViewDebug.IntToString(from = MATCH_PARENT, to = "MATCH_PARENT"),
@@ -3525,9 +3529,11 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
          *
          * <ul>
          *   <li><code>layout_width</code>: the width, either an exact value,
-         *   {@link #WRAP_CONTENT} or {@link #MATCH_PARENT}</li>
+         *   {@link #WRAP_CONTENT}, or {@link #FILL_PARENT} (replaced by
+         *   {@link #MATCH_PARENT} in API Level 8)</li>
          *   <li><code>layout_height</code>: the height, either an exact value,
-         *   {@link #WRAP_CONTENT} or {@link #MATCH_PARENT}</li>
+         *   {@link #WRAP_CONTENT}, or {@link #FILL_PARENT} (replaced by
+         *   {@link #MATCH_PARENT} in API Level 8)</li>
          * </ul>
          *
          * @param c the application environment
@@ -3546,10 +3552,12 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
          * Creates a new set of layout parameters with the specified width
          * and height.
          *
-         * @param width the width, either {@link #MATCH_PARENT},
-         *        {@link #WRAP_CONTENT} or a fixed size in pixels
-         * @param height the height, either {@link #MATCH_PARENT},
-         *        {@link #WRAP_CONTENT} or a fixed size in pixels
+         * @param width the width, either {@link #WRAP_CONTENT},
+         *        {@link #FILL_PARENT} (replaced by {@link #MATCH_PARENT} in
+         *        API Level 8), or a fixed size in pixels
+         * @param height the height, either {@link #WRAP_CONTENT},
+         *        {@link #FILL_PARENT} (replaced by {@link #MATCH_PARENT} in
+         *        API Level 8), or a fixed size in pixels
          */
         public LayoutParams(int width, int height) {
             this.width = width;
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 24808ec7217ea..16b241bed7bd4 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -1396,9 +1396,12 @@
              be a dimension (such as "12dip") for a constant width or one of
              the special constants. -->
         <attr name="layout_width" format="dimension">
-            <!-- <strong>Deprecated.</strong> Use {@code match_parent} instead. -->
+            <!-- The view should be as big as its parent (minus padding).
+                 This constant is deprecated starting from API Level 8 and
+                 is replaced by {@code match_parent}. -->
             <enum name="fill_parent" value="-1" />
-            <!-- The view should be as big as its parent (minus padding). -->
+            <!-- The view should be as big as its parent (minus padding).
+                 Introduced in API Level 8. -->
             <enum name="match_parent" value="-1" />
             <!-- The view should be only big enough to enclose its content (plus padding). -->
             <enum name="wrap_content" value="-2" />
@@ -1409,9 +1412,12 @@
              be a dimension (such as "12dip") for a constant height or one of
              the special constants. -->
         <attr name="layout_height" format="dimension">
-            <!-- <strong>Deprecated.</strong> Use {@code match_parent} instead. -->
+            <!-- The view should be as big as its parent (minus padding).
+                 This constant is deprecated starting from API Level 8 and
+                 is replaced by {@code match_parent}. -->
             <enum name="fill_parent" value="-1" />
-            <!-- The view should be as big as its parent (minus padding). -->
+            <!-- The view should be as big as its parent (minus padding).
+                 Introduced in API Level 8. -->
             <enum name="match_parent" value="-1" />
             <!-- The view should be only big enough to enclose its content (plus padding). -->
             <enum name="wrap_content" value="-2" />
@@ -2128,27 +2134,35 @@
              is used. -->
         <attr name="dropDownAnchor" format="reference" />
         <!-- Specifies the basic width of the dropdown. Its value may
-             be a dimension (such as "12dip") for a constant width, match_parent
-             to match the width of the screen, or wrap_content to match the width
-             of the anchored view. -->
+             be a dimension (such as "12dip") for a constant width,
+             fill_parent or match_parent to match the width of the 
+             screen, or wrap_content to match the width of
+             the anchored view. -->
         <attr name="dropDownWidth" format="dimension">
-            <!-- <strong>Deprecated.</strong> Use {@code match_parent} instead. -->
+            <!-- The dropdown should fill the width of the screen.
+                 This constant is deprecated starting from API Level 8 and
+                 is replaced by {@code match_parent}. -->
             <enum name="fill_parent" value="-1" />
-            <!-- The dropdown should fit the width of the screen. -->
+            <!-- The dropdown should fit the width of the screen.
+                 Introduced in API Level 8. -->
             <enum name="match_parent" value="-1" />
             <!-- The dropdown should fit the width of its anchor. -->
             <enum name="wrap_content" value="-2" />
         </attr>
-        <!-- Specifies the basic width of the dropdown. Its value may
-             be a dimension (such as "12dip") for a constant width, match_parent
-             to fill the width of the screen, or wrap_content to match the height of
+        <!-- Specifies the basic height of the dropdown. Its value may
+             be a dimension (such as "12dip") for a constant height,
+             fill_parent or match_parent to fill the height of the
+             screen, or wrap_content to match the height of
              the content of the drop down. -->
         <attr name="dropDownHeight" format="dimension">
-            <!-- <strong>Deprecated.</strong> Use {@code match_parent} instead. -->
+            <!-- The dropdown should fit the height of the screen.
+                 This constant is deprecated starting from API Level 8 and
+                 is replaced by {@code match_parent}. -->
             <enum name="fill_parent" value="-1" />
-            <!-- The dropdown should fill the width of the screen. -->
+            <!-- The dropdown should fit the height of the screen.
+                 Introduced in API Level 8. -->
             <enum name="match_parent" value="-1" />
-            <!-- The dropdown should fit the width of its anchor. -->
+            <!-- The dropdown should fit the height of the content. -->
             <enum name="wrap_content" value="-2" />
         </attr>
         <attr name="inputType" />
diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd
index f114895c87a96..5c12db9f4ded8 100644
--- a/docs/html/guide/topics/ui/declaring-layout.jd
+++ b/docs/html/guide/topics/ui/declaring-layout.jd
@@ -200,15 +200,29 @@ view group defines layout parameters for each child view (including the child vi
 values. Each child element must define LayoutParams that are appropriate for its parent, 
 though it may also define different LayoutParams for its own children. </p>
 
-<p>All view groups include a width and height (<code>layout_width</code> and <code>layout_height</code>), 
-and each view is required to define them. 
-Many LayoutParams also include optional margins and
-borders. You can specify width and height with exact measurements, though you probably won't want
-to do this often. More often, you will tell your view to size itself either to
-the dimensions required by its content, or to become as big as its parent view group
-will allow (with the <var>wrap_content</var> and <var>fill_parent</var> values, respectively).
-The accepted measurement types are defined in the 
-<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Available Resources</a> document.</p>
+<p>All view groups include a width and height (<code>layout_width</code> and
+<code>layout_height</code>), and each view is required to define them. Many
+LayoutParams also include optional margins and borders. <p>
+
+<p>You can specify width and height with exact measurements, though you probably
+won't want to do this often. More often, you will use one of these constants to
+set the width or height: </p>
+
+<ul>
+  <li><var>wrap_content</var> tells your view to size itself to the dimensions
+required by its content</li>
+  <li><var>fill_parent</var> (renamed <var>match_parent</var> in API Level 8)
+tells your view to become as big as its parent view group will allow.</li>
+</ul>
+
+<p>In general, specifying a layout width and height using absolute units such as
+pixels is not recommended. Instead, using relative measurements such as
+density-independent pixel units (<var>dp</var>), <var>wrap_content</var>, or
+<var>fill_parent</var>, is a better approach, because it helps ensure that
+your application will display properly across a variety of device screen sizes.
+The accepted measurement types are defined in the
+<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">
+Available Resources</a> document.</p>
 
 
 <h2 id="Position">Layout Position</h2>