diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index d658aac5215ef..02ce2be97e7f1 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -8711,7 +8711,12 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
 
     /**
      * Change the view's z order in the tree, so it's on top of other sibling
-     * views
+     * views. This ordering change may affect layout, if the parent container
+     * uses an order-dependent layout scheme (e.g., LinearLayout). This
+     * method should be followed by calls to {@link #requestLayout()} and
+     * {@link View#invalidate()} on the parent.
+     *
+     * @see ViewGroup#bringChildToFront(View)
      */
     public void bringToFront() {
         if (mParent != null) {
diff --git a/core/java/android/view/ViewParent.java b/core/java/android/view/ViewParent.java
index 4b70bc0c7e370..d79aa7efad4d9 100644
--- a/core/java/android/view/ViewParent.java
+++ b/core/java/android/view/ViewParent.java
@@ -146,9 +146,13 @@ public interface ViewParent {
     public View focusSearch(View v, int direction);
 
     /**
-     * Change the z order of the child so it's on top of all other children
+     * Change the z order of the child so it's on top of all other children.
+     * This ordering change may affect layout, if this container
+     * uses an order-dependent layout scheme (e.g., LinearLayout). This
+     * method should be followed by calls to {@link #requestLayout()} and
+     * {@link View#invalidate()} on this parent.
      * 
-     * @param child
+     * @param child The child to bring to the top of the z order
      */
     public void bringChildToFront(View child);