docs: Update ScrollView JavaDoc comments

- reworded introduction for clarity
- crosslink to nestedscrollview
- simplify language around the “don’ts”
- crosslink to the material design guidelines for scrolling techniques

Test: docs only change. Tested with doc build
Change-Id: Ia6d1e5ce0f9abd3db2c1988537bd42013851596f

1 files changed, 20 insertions, 18 deletions

diff --git a/core/java/android/widget/ScrollView.java b/core/java/android/widget/ScrollView.java
index 8fc4f5044261..97d32f1266af 100644
--- a/core/java/android/widget/ScrollView.java
+++ b/core/java/android/widget/ScrollView.java
@@ -50,25 +50,27 @@ import com.android.internal.R;
 import java.util.List;
 
 /**
- * Layout container for a view hierarchy that can be scrolled by the user,
- * allowing it to be larger than the physical display.  A ScrollView
- * is a {@link FrameLayout}, meaning you should place one child in it
- * containing the entire contents to scroll; this child may itself be a layout
- * manager with a complex hierarchy of objects.  A child that is often used
- * is a {@link LinearLayout} in a vertical orientation, presenting a vertical
- * array of top-level items that the user can scroll through.
- * <p>You should never use a ScrollView with a {@link ListView}, because
- * ListView takes care of its own vertical scrolling.  Most importantly, doing this
- * defeats all of the important optimizations in ListView for dealing with
- * large lists, since it effectively forces the ListView to display its entire
- * list of items to fill up the infinite container supplied by ScrollView.
- * <p>The {@link TextView} class also
- * takes care of its own scrolling, so does not require a ScrollView, but
- * using the two together is possible to achieve the effect of a text view
- * within a larger container.
+ * A view group that allows the view hierarchy placed within it to be scrolled.
+ * Scroll view may have only one direct child placed within it.
+ * To add multiple views within the scroll view, make
+ * the direct child you add a view group, for example {@link LinearLayout}, and
+ * place additional views within that LinearLayout.
  *
- * <p>ScrollView only supports vertical scrolling. For horizontal scrolling,
- * use {@link HorizontalScrollView}.
+ * <p>Scroll view supports vertical scrolling only. For horizontal scrolling,
+ * use {@link HorizontalScrollView} instead.</p>
+ *
+ * <p>Never add a {@link android.support.v7.widget.RecyclerView} or {@link ListView} to
+ * a scroll view. Doing so results in poor user interface performance and a poor user
+ * experience.</p>
+ *
+ * <p class="note">
+ * For vertical scrolling, consider {@link android.support.v4.widget.NestedScrollView}
+ * instead of scroll view which offers greater user interface flexibility and
+ * support for the material design scrolling patterns.</p>
+ *
+ * <p>To learn more about material design patterns for handling scrolling, see
+ * <a href="https://material.io/guidelines/patterns/scrolling-techniques.html#">
+ * Scrolling techniques</a>.</p>
  *
  * @attr ref android.R.styleable#ScrollView_fillViewport
  */