diff --git a/core/java/android/view/ViewGroup.java b/core/java/android/view/ViewGroup.java
index 2921cfaa03b46..10b2bf4f52501 100644
--- a/core/java/android/view/ViewGroup.java
+++ b/core/java/android/view/ViewGroup.java
@@ -6501,7 +6501,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
      */
     public static class MarginLayoutParams extends ViewGroup.LayoutParams {
         /**
-         * The left margin in pixels of the child.
+         * The left margin in pixels of the child. Margin values should be positive.
          * Call {@link ViewGroup#setLayoutParams(LayoutParams)} after reassigning a new value
          * to this field.
          */
@@ -6509,7 +6509,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         public int leftMargin;
 
         /**
-         * The top margin in pixels of the child.
+         * The top margin in pixels of the child. Margin values should be positive.
          * Call {@link ViewGroup#setLayoutParams(LayoutParams)} after reassigning a new value
          * to this field.
          */
@@ -6517,7 +6517,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         public int topMargin;
 
         /**
-         * The right margin in pixels of the child.
+         * The right margin in pixels of the child. Margin values should be positive.
          * Call {@link ViewGroup#setLayoutParams(LayoutParams)} after reassigning a new value
          * to this field.
          */
@@ -6525,7 +6525,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         public int rightMargin;
 
         /**
-         * The bottom margin in pixels of the child.
+         * The bottom margin in pixels of the child. Margin values should be positive.
          * Call {@link ViewGroup#setLayoutParams(LayoutParams)} after reassigning a new value
          * to this field.
          */
@@ -6533,7 +6533,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         public int bottomMargin;
 
         /**
-         * The start margin in pixels of the child.
+         * The start margin in pixels of the child. Margin values should be positive.
          * Call {@link ViewGroup#setLayoutParams(LayoutParams)} after reassigning a new value
          * to this field.
          */
@@ -6541,7 +6541,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         private int startMargin = DEFAULT_MARGIN_RELATIVE;
 
         /**
-         * The end margin in pixels of the child.
+         * The end margin in pixels of the child. Margin values should be positive.
          * Call {@link ViewGroup#setLayoutParams(LayoutParams)} after reassigning a new value
          * to this field.
          */
@@ -6722,6 +6722,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
          * Sets the margins, in pixels. A call to {@link android.view.View#requestLayout()} needs
          * to be done so that the new margins are taken into account. Left and right margins may be
          * overriden by {@link android.view.View#requestLayout()} depending on layout direction.
+         * Margin values should be positive.
          *
          * @param left the left margin size
          * @param top the top margin size
@@ -6751,7 +6752,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
          * Sets the relative margins, in pixels. A call to {@link android.view.View#requestLayout()}
          * needs to be done so that the new relative margins are taken into account. Left and right
          * margins may be overriden by {@link android.view.View#requestLayout()} depending on layout
-         * direction.
+         * direction. Margin values should be positive.
          *
          * @param start the start margin size
          * @param top the top margin size
@@ -6774,7 +6775,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         }
 
         /**
-         * Sets the relative start margin.
+         * Sets the relative start margin. Margin values should be positive.
          *
          * @param start the start margin size
          *
@@ -6807,7 +6808,7 @@ public abstract class ViewGroup extends View implements ViewParent, ViewManager
         }
 
         /**
-         * Sets the relative end margin.
+         * Sets the relative end margin. Margin values should be positive.
          *
          * @param end the end margin size
          *
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 251652e204402..c75c0de2d704d 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -2772,25 +2772,32 @@
         <attr name="layout_width" />
         <attr name="layout_height" />
         <!--  Specifies extra space on the left, top, right and bottom
-              sides of this view. This space is outside this view's bounds. -->
+              sides of this view. This space is outside this view's bounds.
+              Margin values should be positive. -->
         <attr name="layout_margin" format="dimension"  />
         <!--  Specifies extra space on the left side of this view.
-              This space is outside this view's bounds. -->
+              This space is outside this view's bounds.
+              Margin values should be positive. -->
         <attr name="layout_marginLeft" format="dimension"  />
         <!--  Specifies extra space on the top side of this view.
-              This space is outside this view's bounds. -->
+              This space is outside this view's bounds.
+              Margin values should be positive.-->
         <attr name="layout_marginTop" format="dimension" />
         <!--  Specifies extra space on the right side of this view.
-              This space is outside this view's bounds. -->
+              This space is outside this view's bounds.
+              Margin values should be positive.-->
         <attr name="layout_marginRight" format="dimension"  />
         <!--  Specifies extra space on the bottom side of this view.
-              This space is outside this view's bounds. -->
+              This space is outside this view's bounds.
+              Margin values should be positive.-->
         <attr name="layout_marginBottom" format="dimension"  />
         <!--  Specifies extra space on the start side of this view.
-              This space is outside this view's bounds. -->
+              This space is outside this view's bounds.
+              Margin values should be positive.-->
         <attr name="layout_marginStart" format="dimension"  />
         <!--  Specifies extra space on the end side of this view.
-              This space is outside this view's bounds. -->
+              This space is outside this view's bounds.
+              Margin values should be positive.-->
         <attr name="layout_marginEnd" format="dimension"  />
     </declare-styleable>