Merge "docs: fix document issue 27549" into jb-dev

Author: scottamain

core/java/android/widget/HorizontalScrollView.java

@@ -47,18 +47,13 @@
  * is a {@link LinearLayout} in a horizontal orientation, presenting a horizontal
  * array of top-level items that the user can scroll through.
  *
- * <p>You should never use a HorizontalScrollView with a {@link ListView}, since
- * ListView takes care of its own 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 HorizontalScrollView.
- *
  * <p>The {@link TextView} class also
- * takes care of its own scrolling, so does not require a ScrollView, but
+ * takes care of its own scrolling, so does not require a HorizontalScrollView, but
  * using the two together is possible to achieve the effect of a text view
  * within a larger container.
  *
- * <p>HorizontalScrollView only supports horizontal scrolling.
+ * <p>HorizontalScrollView only supports horizontal scrolling. For vertical scrolling,
+ * use either {@link ScrollView} or {@link ListView}.
  *
  * @attr ref android.R.styleable#HorizontalScrollView_fillViewport
  */

core/java/android/widget/ScrollView.java

@@ -49,13 +49,18 @@
  * 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.
  *
- * <p>ScrollView only supports vertical scrolling.
+ * <p>ScrollView only supports vertical scrolling. For horizontal scrolling,
+ * use {@link HorizontalScrollView}.
  *
  * @attr ref android.R.styleable#ScrollView_fillViewport
  */