From 8b9ed44f8d559be2590b25cb4b72d2aefd3b3784 Mon Sep 17 00:00:00 2001
From: Chet Haase <chet@google.com>
Date: Thu, 25 Aug 2016 15:35:53 -0700
Subject: [PATCH] Various doc cleanups

Issue #6439958  More R.attr breakage
Issue #918412  android.graphics.Paint.FontMetricsInt fields & methods need doc
Issue #917387  javadoc bug: Canvas.EdgeType has minimal documentation
Issue #18948460 [DAC-bug] LinearLayout xml layout_weight parameter is missing description

Change-Id: Idb289ca778b3f316923757405460031ce7a5e1e9
---
 core/java/android/widget/LinearLayout.java |  4 ++--
 core/res/res/values/attrs.xml              | 19 ++++++++++++-------
 core/res/res/values/attrs_manifest.xml     |  2 +-
 graphics/java/android/graphics/Canvas.java |  9 +++++++++
 graphics/java/android/graphics/Paint.java  | 17 +++++++++++++++++
 5 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/core/java/android/widget/LinearLayout.java b/core/java/android/widget/LinearLayout.java
index e2c535ca16953..6511de81b6cb1 100644
--- a/core/java/android/widget/LinearLayout.java
+++ b/core/java/android/widget/LinearLayout.java
@@ -1935,8 +1935,8 @@ public class LinearLayout extends ViewGroup {
             @ViewDebug.IntToString(from = Gravity.BOTTOM,            to = "BOTTOM"),
             @ViewDebug.IntToString(from = Gravity.LEFT,              to = "LEFT"),
             @ViewDebug.IntToString(from = Gravity.RIGHT,             to = "RIGHT"),
-            @ViewDebug.IntToString(from = Gravity.START,            to = "START"),
-            @ViewDebug.IntToString(from = Gravity.END,             to = "END"),
+            @ViewDebug.IntToString(from = Gravity.START,             to = "START"),
+            @ViewDebug.IntToString(from = Gravity.END,               to = "END"),
             @ViewDebug.IntToString(from = Gravity.CENTER_VERTICAL,   to = "CENTER_VERTICAL"),
             @ViewDebug.IntToString(from = Gravity.FILL_VERTICAL,     to = "FILL_VERTICAL"),
             @ViewDebug.IntToString(from = Gravity.CENTER_HORIZONTAL, to = "CENTER_HORIZONTAL"),
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 9a7fccc9d1354..fdea0450924ad 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -2334,8 +2334,8 @@ i
         <!-- Defines whether the vertical scrollbar track should always be drawn. -->
         <attr name="scrollbarAlwaysDrawVerticalTrack" format="boolean" />
 
-        <!-- This attribute is deprecated and will be ignored as of
-             API level 14 ({@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}).
+        <!-- This attribute is ignored in API level 14
+             ({@link android.os.Build.VERSION_CODES#ICE_CREAM_SANDWICH}) and higher.
              Using fading edges may introduce noticeable performance
              degradations and should be used only when required by the application's
              visual design. To request fading edges with API level 14 and above,
@@ -2571,7 +2571,7 @@ i
 
         <!-- Defines the direction of layout drawing. This typically is associated with writing
              direction of the language script used. The possible values are "ltr" for Left-to-Right,
-             "rtl" for Right-to-Left, "locale" and "inherit" from parent view. If there is nothing
+             "rtl" for Right-to-Left, "locale", and "inherit" from parent view. If there is nothing
              to inherit, "locale" is used. "locale" falls back to "en-US". "ltr" is the direction
              used in "en-US". The default for this attribute is "inherit". -->
         <attr name="layoutDirection">
@@ -2585,8 +2585,7 @@ i
             <enum name="locale" value="3" />
         </attr>
 
-        <!-- Defines the direction of the text. A heuristic is used to determine the resolved text
-              direction of paragraphs. -->
+        <!-- Defines the direction of the text. -->
          <attr name="textDirection" format="integer">
             <!-- Default -->
             <enum name="inherit" value="0" />
@@ -2612,8 +2611,7 @@ i
             <enum name="firstStrongRtl" value="7" />
         </attr>
 
-        <!-- Defines the alignment of the text. A heuristic is used to determine the resolved
-            text alignment. -->
+        <!-- Defines the alignment of the text. -->
         <attr name="textAlignment" format="integer">
             <!-- Default -->
             <enum name="inherit" value="0" />
@@ -4934,7 +4932,14 @@ i
     <declare-styleable name="LinearLayout_Layout">
         <attr name="layout_width" />
         <attr name="layout_height" />
+        <!-- Indicates how much of the extra space in the LinearLayout is
+        allocated to the view associated with these LayoutParams. Specify
+        0 if the view should not be stretched. Otherwise the extra pixels
+        will be pro-rated among all views whose weight is greater than 0. -->
         <attr name="layout_weight" format="float" />
+        <!-- Gravity specifies how a component should be placed in its group of cells.
+        The default is {@link android.view.Gravity#TOP}.
+        See {@link android.widget.LinearLayout#setGravity(int)}. -->
         <attr name="layout_gravity" />
     </declare-styleable>
     <declare-styleable name="GridLayout_Layout">
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 01cb64db1e8eb..cad58547f390f 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -1305,7 +1305,7 @@
         <attr name="cantSaveState" format="boolean" />
         <attr name="uiOptions" />
         <!-- Declare that your application will be able to deal with RTL (right to left) layouts.
-             If set to  false (default value), your application will not care about RTL layouts. -->
+             The default value is false. -->
         <attr name="supportsRtl" format="boolean" />
         <!-- Declare that this application requires access to restricted accounts of a certain
              type. The default value is null and restricted accounts won\'t be visible to this
diff --git a/graphics/java/android/graphics/Canvas.java b/graphics/java/android/graphics/Canvas.java
index 42579040f42ad..d29005cfcf0b5 100644
--- a/graphics/java/android/graphics/Canvas.java
+++ b/graphics/java/android/graphics/Canvas.java
@@ -857,6 +857,15 @@ public class Canvas {
         nativeSetDrawFilter(mNativeCanvasWrapper, nativeFilter);
     }
 
+    /**
+     * Constant values used as parameters to {@code quickReject()} calls. These values
+     * specify how much space around the shape should be accounted for, depending on whether
+     * the shaped area is antialiased or not.
+     *
+     * @see #quickReject(float, float, float, float, EdgeType)
+     * @see #quickReject(Path, EdgeType)
+     * @see #quickReject(RectF, EdgeType)
+     */
     public enum EdgeType {
 
         /**
diff --git a/graphics/java/android/graphics/Paint.java b/graphics/java/android/graphics/Paint.java
index 888bbc2abb752..3cbc4f071f3d2 100644
--- a/graphics/java/android/graphics/Paint.java
+++ b/graphics/java/android/graphics/Paint.java
@@ -1641,10 +1641,27 @@ public class Paint {
      * integers.
      */
     public static class FontMetricsInt {
+        /**
+         * The maximum distance above the baseline for the tallest glyph in
+         * the font at a given text size.
+         */
         public int   top;
+        /**
+         * The recommended distance above the baseline for singled spaced text.
+         */
         public int   ascent;
+        /**
+         * The recommended distance below the baseline for singled spaced text.
+         */
         public int   descent;
+        /**
+         * The maximum distance below the baseline for the lowest glyph in
+         * the font at a given text size.
+         */
         public int   bottom;
+        /**
+         * The recommended additional space to add between lines of text.
+         */
         public int   leading;
 
         @Override public String toString() {