Correct/consistent docs for Touchable components

Summary:
I ran into confusion (#12581) because the docs for TouchableOpacity stated that it doesn't change the view hierarchy, but in fact it does, and the docs are just out of date.

- [20 Feb 2015](efae175a8e/Libraries/Components/Touchable/TouchableOpacity.js (L21)) Docs correctly reflected that the component was cloned so didn't affect hierarchy
- [25 Jul 2015](725053acfe) Component was changed to being wrapped but docs weren't updated.

Went to correct this in the docs and noticed they were a bit inconsistent with each other, so have made them more unified.  Each one now clearly warns about:

- If it adds a view to the hierarchy, which will affect layout.
- If it can only accept a single child.
Closes https://github.com/facebook/react-native/pull/12583

Differential Revision: D4619837

Pulled By: ericvicenti

fbshipit-source-id: 4d1becd9f290cefcb4548a5ea2878be2d2c315fa

Libraries/Components/Touchable/TouchableHighlight.js

@@ -40,10 +40,15 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30};
 /**
  * A wrapper for making views respond properly to touches.
  * On press down, the opacity of the wrapped view is decreased, which allows
- * the underlay color to show through, darkening or tinting the view.  The
- * underlay comes from adding a view to the view hierarchy, which can sometimes
- * cause unwanted visual artifacts if not used correctly, for example if the
- * backgroundColor of the wrapped view isn't explicitly set to an opaque color.
+ * the underlay color to show through, darkening or tinting the view.
+ *
+ * The underlay comes from wrapping the child in a new View, which can affect
+ * layout, and sometimes cause unwanted visual artifacts if not used correctly,
+ * for example if the backgroundColor of the wrapped view isn't explicitly set
+ * to an opaque color.
+ *
+ * TouchableHighlight must have one child (not zero or more than one).
+ * If you wish to have several child components, wrap them in a View.
  *
  * Example:
  *
@@ -59,9 +64,6 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30};
  *   );
  * },
  * ```
- * > **NOTE**: TouchableHighlight must have one child (not zero or more than one)
- * >
- * > If you wish to have several child components, wrap them in a View.
  */
 
 var TouchableHighlight = React.createClass({

Libraries/Components/Touchable/TouchableNativeFeedback.android.js

@@ -45,9 +45,11 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30};
 /**
  * A wrapper for making views respond properly to touches (Android only).
  * On Android this component uses native state drawable to display touch
- * feedback. At the moment it only supports having a single View instance as a
- * child node, as it's implemented by replacing that View with another instance
- * of RCTView node with some additional properties set.
+ * feedback.
+ *
+ * At the moment it only supports having a single View instance as a child
+ * node, as it's implemented by replacing that View with another instance of
+ * RCTView node with some additional properties set.
  *
  * Background drawable of native feedback touchable can be customized with
  * `background` property.

Libraries/Components/Touchable/TouchableOpacity.js

@@ -31,8 +31,9 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30};
 /**
  * A wrapper for making views respond properly to touches.
  * On press down, the opacity of the wrapped view is decreased, dimming it.
- * This is done without actually changing the view hierarchy, and in general is
- * easy to add to an app without weird side-effects.
+ *
+ * Opacity is controlled by wrapping the children in an Animated.View, which is
+ * added to the view hiearchy.  Be aware that this can affect layout.
  *
  * Example:
  *

Libraries/Components/Touchable/TouchableWithoutFeedback.js

@@ -28,9 +28,8 @@ const PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30};
  * Do not use unless you have a very good reason. All the elements that
  * respond to press should have a visual feedback when touched.
  *
- * > **NOTE**: TouchableWithoutFeedback supports only one child
- * >
- * > If you wish to have several child components, wrap them in a View.
+ * TouchableWithoutFeedback supports only one child.
+ * If you wish to have several child components, wrap them in a View.
  */
 const TouchableWithoutFeedback = React.createClass({
   mixins: [TimerMixin, Touchable.Mixin],