Addressing API Review docs bugs:

->Issue 3370313
->Issue 3370403
->Issue 3370328
->kthx, bye

Change-Id: I2d1962c27b3ba856a0b4632d335271300bab45eb

7 files changed, 106 insertions, 27 deletions

diff --git a/api/11.xml b/api/11.xml
index 7db0328247bf..70d37b4aa320 100644
--- a/api/11.xml
+++ b/api/11.xml
@@ -240630,6 +240630,17 @@
  visibility="public"
 >
 </method>
+<method name="fyiWillBeAdvancedByHostKThx"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
 <method name="getAdapter"
  return="android.widget.Adapter"
  abstract="false"
@@ -240885,17 +240896,6 @@
  visibility="public"
 >
 </method>
-<method name="willBeAdvancedByHost"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
 </class>
 <class name="AdapterViewFlipper"
  extends="android.widget.AdapterViewAnimator"
diff --git a/api/current.xml b/api/current.xml
index 613f0005ba66..0427a2e56d6a 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -240651,6 +240651,17 @@
  visibility="public"
 >
 </method>
+<method name="fyiWillBeAdvancedByHostKThx"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
 <method name="getAdapter"
  return="android.widget.Adapter"
  abstract="false"
@@ -240906,17 +240917,6 @@
  visibility="public"
 >
 </method>
-<method name="willBeAdvancedByHost"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
 </class>
 <class name="AdapterViewFlipper"
  extends="android.widget.AdapterViewAnimator"
@@ -260347,7 +260347,7 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="arg0" type="T">
+<parameter name="t" type="T">
 </parameter>
 </method>
 </interface>
diff --git a/core/java/android/widget/AdapterViewAnimator.java b/core/java/android/widget/AdapterViewAnimator.java
index c27082f928f9..4c1279ff1e0c 100644
--- a/core/java/android/widget/AdapterViewAnimator.java
+++ b/core/java/android/widget/AdapterViewAnimator.java
@@ -981,11 +981,21 @@ public abstract class AdapterViewAnimator extends AdapterView<Adapter>
         // items from the Adapter.
     }
 
+    /**
+     * Called by an {@link android.appwidget.AppWidgetHost} in order to advance the current view when
+     * it is being used within an app widget.
+     */
     public void advance() {
         showNext();
     }
 
-    public void willBeAdvancedByHost() {
+    /**
+     * Called by an {@link android.appwidget.AppWidgetHost} to indicate that it will be
+     * automatically advancing the views of this {@link AdapterViewAnimator} by calling
+     * {@link AdapterViewAnimator#advance()} at some point in the future. This allows subclasses to
+     * perform any required setup, for example, to stop automatically advancing their children.
+     */
+    public void fyiWillBeAdvancedByHostKThx() {
     }
 
     @Override
diff --git a/core/java/android/widget/AdapterViewFlipper.java b/core/java/android/widget/AdapterViewFlipper.java
index 772168863775..273c2588e90c 100644
--- a/core/java/android/widget/AdapterViewFlipper.java
+++ b/core/java/android/widget/AdapterViewFlipper.java
@@ -258,8 +258,14 @@ public class AdapterViewFlipper extends AdapterViewAnimator {
         }
     };
 
+    /**
+     * Called by an {@link android.appwidget.AppWidgetHost} to indicate that it will be
+     * automatically advancing the views of this {@link AdapterViewFlipper} by calling
+     * {@link AdapterViewFlipper#advance()} at some point in the future. This allows
+     * {@link AdapterViewFlipper} to prepare by no longer Advancing its children.
+     */
     @Override
-    public void willBeAdvancedByHost() {
+    public void fyiWillBeAdvancedByHostKThx() {
         mAdvancedByHost = true;
         updateRunning(false);
     }
diff --git a/core/java/android/widget/Advanceable.java b/core/java/android/widget/Advanceable.java
index bb162de98a9e..dc13ebb7764f 100644
--- a/core/java/android/widget/Advanceable.java
+++ b/core/java/android/widget/Advanceable.java
@@ -34,5 +34,5 @@ public interface Advanceable {
      * Called by the AppWidgetHost once before it begins to call advance(), allowing the
      * collection to do any required setup.
      */
-    public void willBeAdvancedByHost();
+    public void fyiWillBeAdvancedByHostKThx();
 }
diff --git a/core/java/android/widget/RemoteViewsService.java b/core/java/android/widget/RemoteViewsService.java
index 16126aad1c94..e5a3de28ca62 100644
--- a/core/java/android/widget/RemoteViewsService.java
+++ b/core/java/android/widget/RemoteViewsService.java
@@ -42,7 +42,7 @@ public abstract class RemoteViewsService extends Service {
     /**
      * An interface for an adapter between a remote collection view (ListView, GridView, etc) and
      * the underlying data for that view.  The implementor is responsible for making a RemoteView
-     * for each item in the data set.
+     * for each item in the data set. This interface is a thin wrapper around {@link Adapter}.
      * 
      * @see android.widget.Adapter
      * @see android.appwidget.AppWidgetManager
@@ -53,24 +53,72 @@ public abstract class RemoteViewsService extends Service {
          * multiple RemoteViewAdapters depending on the intent passed.
          */
         public void onCreate();
+
         /**
          * Called when notifyDataSetChanged() is triggered on the remote adapter. This allows a
          * RemoteViewsFactory to respond to data changes by updating any internal references.
          *
+         * Note: expensive tasks can be safely performed synchronously within this method. In the
+         * interim, the old data will be displayed within the widget.
+         *
          * @see android.appwidget.AppWidgetManager#notifyAppWidgetViewDataChanged(int[], int)
          */
         public void onDataSetChanged();
+
         /**
          * Called when the last RemoteViewsAdapter that is associated with this factory is
          * unbound.
          */
         public void onDestroy();
 
+        /**
+         * See {@link Adapter#getCount()}
+         *
+         * @return Count of items.
+         */
         public int getCount();
+
+        /**
+         * See {@link Adapter#getView(int, android.view.View, android.view.ViewGroup)}.
+         *
+         * Note: expensive tasks can be safely performed synchronously within this method, and a
+         * loading view will be displayed in the interim. See {@link #getLoadingView()}.
+         *
+         * @param position The position of the item within the Factory's data set of the item whose
+         *        view we want.
+         * @return A RemoteViews object corresponding to the data at the specified position.
+         */
         public RemoteViews getViewAt(int position);
+
+        /**
+         * This allows for the use of a custom loading view which appears between the time that
+         * {@link #getViewAt(int)} is called and returns. If null is returned, a default loading
+         * view will be used.
+         *
+         * @return The RemoteViews representing the desired loading view.
+         */
         public RemoteViews getLoadingView();
+
+        /**
+         * See {@link Adapter#getViewTypeCount()}.
+         *
+         * @return The number of types of Views that will be returned by this factory.
+         */
         public int getViewTypeCount();
+
+        /**
+         * See {@link Adapter#getItemId(int)}.
+         *
+         * @param position The position of the item within the data set whose row id we want.
+         * @return The id of the item at the specified position.
+         */
         public long getItemId(int position);
+
+        /**
+         * See {@link Adapter#hasStableIds()}.
+         *
+         * @return True if the same id always refers to the same object.
+         */
         public boolean hasStableIds();
     }
 
diff --git a/core/java/android/widget/StackView.java b/core/java/android/widget/StackView.java
index 2c100773951c..22edf6d5f68f 100644
--- a/core/java/android/widget/StackView.java
+++ b/core/java/android/widget/StackView.java
@@ -347,6 +347,9 @@ public class StackView extends AdapterViewAnimator {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     @android.view.RemotableViewMethod
     public void showNext() {
@@ -362,6 +365,9 @@ public class StackView extends AdapterViewAnimator {
         super.showNext();
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     @android.view.RemotableViewMethod
     public void showPrevious() {
@@ -474,6 +480,9 @@ public class StackView extends AdapterViewAnimator {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean onInterceptTouchEvent(MotionEvent ev) {
         int action = ev.getAction();
@@ -561,6 +570,9 @@ public class StackView extends AdapterViewAnimator {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public boolean onTouchEvent(MotionEvent ev) {
         super.onTouchEvent(ev);
@@ -939,6 +951,9 @@ public class StackView extends AdapterViewAnimator {
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void onRemoteAdapterConnected() {
         super.onRemoteAdapterConnected();