From a7a735fb2a5d56e5ec7ca2f65cb14e29e3793f3c Mon Sep 17 00:00:00 2001
From: Adam Powell <adamp@google.com>
Date: Thu, 9 Oct 2014 12:54:52 -0700
Subject: [PATCH] Document that MarginLayoutParams margins should be positive.

Negative margins can cause all sorts of other problematic assumptions,
subtle errors and unexpected behavior. While they technically work
developers should steer clear of them.

Change-Id: Ia1f7d9a33e25444ebdc3c32679ae1179210558e1
---
 core/java/android/view/ViewGroup.java | 19 ++++++++++---------
 core/res/res/values/attrs.xml         | 21 ++++++++++++++-------
 2 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/core/java/android/view/ViewGroup.java b/core/java/android/view/ViewGroup.java
index 3a183ed6707b1..0e9048b3c2e52 100644
--- a/core/java/android/view/ViewGroup.java
+++ b/core/java/android/view/ViewGroup.java
@@ -6491,7 +6491,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.
          */
@@ -6499,7 +6499,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.
          */
@@ -6507,7 +6507,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.
          */
@@ -6515,7 +6515,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.
          */
@@ -6523,7 +6523,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.
          */
@@ -6531,7 +6531,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.
          */
@@ -6712,6 +6712,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
@@ -6741,7 +6742,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
@@ -6764,7 +6765,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
          *
@@ -6797,7 +6798,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>