Update Text Component

Summary:
This updates the documentation for the `Text` component itself and the embedded `Text.md` that goes with it.

- React Native Web Player
- Document all props
  - NOTE: I actually added a new prop to `Text` called `accessible` since it was set by default and thus shown in the Props list
    in the original documentation (but with an empty description).
- Stylistic fixes
Closes facebook#8445

Differential Revision: D3493112

Pulled By: JoelMarcey

fbshipit-source-id: b428d4eb09065db5c6cb1ae5524ad22084fd2a82

Libraries/Text/Text.js

@@ -37,49 +37,82 @@ const viewConfig = {
 };
 
 /**
- * A React component for displaying text which supports nesting,
- * styling, and touch handling.  In the following example, the nested title and
- * body text will inherit the `fontFamily` from `styles.baseText`, but the title
- * provides its own additional styles.  The title and body will stack on top of
- * each other on account of the literal newlines:
+ * A React component for displaying text.
  *
- * ```
- * renderText: function() {
- *   return (
- *     <Text style={styles.baseText}>
- *       <Text style={styles.titleText} onPress={this.onPressTitle}>
- *         {this.state.titleText + '\n\n'}
- *       </Text>
- *       <Text numberOfLines={5}>
- *         {this.state.bodyText}
+ * `Text` supports nesting, styling, and touch handling.
+ *
+ * In the following example, the nested title and body text will inherit the `fontFamily` from
+ *`styles.baseText`, but the title provides its own additional styles.  The title and body will
+ * stack on top of each other on account of the literal newlines:
+ *
+ * ```ReactNativeWebPlayer
+ * import React, { Component } from 'react';
+ * import { AppRegistry, Text, StyleSheet } from 'react-native';
+ *
+ * class TextInANest extends Component {
+ *   constructor(props) {
+ *     super(props);
+ *     this.state = {
+ *       titleText: "Bird's Nest",
+ *       bodyText: 'This is not really a bird nest.'
+ *     };
+ *   }
+ *
+ *   render() {
+ *     return (
+ *       <Text style={styles.baseText}>
+ *         <Text style={styles.titleText} onPress={this.onPressTitle}>
+ *           {this.state.titleText}<br /><br />
+ *         </Text>
+ *         <Text numberOfLines={5}>
+ *           {this.state.bodyText}
+ *         </Text>
  *       </Text>
- *     </Text>
- *   );
- * },
- * ...
- * var styles = StyleSheet.create({
+ *     );
+ *   }
+ * }
+ *
+ * const styles = StyleSheet.create({
  *   baseText: {
  *     fontFamily: 'Cochin',
  *   },
  *   titleText: {
  *     fontSize: 20,
  *     fontWeight: 'bold',
  *   },
- * };
+ * });
+ *
+ * // App registration and rendering
+ * AppRegistry.registerComponent('TextInANest', () => TextInANest);
  * ```
  */
 
 const Text = React.createClass({
   propTypes: {
     /**
-     * Line Break mode. Works only with numberOfLines.
-     * clip is working only for iOS
+     * Line Break mode. This can be one of the following values:
+     *
+     * - `head` - The line is displayed so that the end fits in the container and the missing text
+     * at the beginning of the line is indicated by an ellipsis glyph. e.g., "...wxyz"
+     * - `middle` - The line is displayed so that the beginning and end fit in the container and the
+     * missing text in the middle is indicated by an ellipsis glyph. "ab...yz"
+     * - `tail` - The line is displayed so that the beginning fits in the container and the
+     * missing text at the end of the line is indicated by an ellipsis glyph. e.g., "abcd..."
+     * - `clip` - Lines are not drawn past the edge of the text container.
+     *
+     * The default is `tail`.
+     *
+     * `numberOfLines` must be set in conjunction with this prop.
+     *
+     * > `clip` is working only for iOS
      */
     lineBreakMode: React.PropTypes.oneOf(['head', 'middle', 'tail', 'clip']),
     /**
      * Used to truncate the text with an ellipsis after computing the text
      * layout, including line wrapping, such that the total number of lines
      * does not exceed this number.
+     *
+     * This prop is commonly used with `lineBreakMode`.
      */
     numberOfLines: React.PropTypes.number,
     /**
@@ -90,20 +123,26 @@ const Text = React.createClass({
     onLayout: React.PropTypes.func,
     /**
      * This function is called on press.
+     *
+     * e.g., `onPress={() => console.log('1st')}``
      */
     onPress: React.PropTypes.func,
     /**
      * This function is called on long press.
+     *
+     * e.g., `onLongPress={this.increaseSize}>``
      */
     onLongPress: React.PropTypes.func,
     /**
      * Lets the user select text, to use the native copy and paste functionality.
+     *
      * @platform android
      */
     selectable: React.PropTypes.bool,
     /**
-     * When true, no visual change is made when text is pressed down. By
+     * When `true`, no visual change is made when text is pressed down. By
      * default, a gray oval highlights the text on press down.
+     *
      * @platform ios
      */
     suppressHighlighting: React.PropTypes.bool,
@@ -113,10 +152,21 @@ const Text = React.createClass({
      */
     testID: React.PropTypes.string,
     /**
-     * Specifies should fonts scale to respect Text Size accessibility setting on iOS.
+     * Specifies whether fonts should scale to respect Text Size accessibility setting on iOS. The
+     * default is `true`.
+     *
      * @platform ios
      */
     allowFontScaling: React.PropTypes.bool,
+    /**
+     * When set to `true`, indicates that the view is an accessibility element. The default value
+     * for a `Text` element is `true`.
+     *
+     * See the
+     * [Accessibility guide](/react-native/docs/accessibility.html#accessible-ios-android)
+     * for more information.
+     */
+     accessible: React.PropTypes.bool,
   },
   getDefaultProps(): Object {
     return {

docs/Text.md

@@ -4,13 +4,24 @@
 
 Both iOS and Android allow you to display formatted text by annotating ranges of a string with specific formatting like bold or colored text (`NSAttributedString` on iOS, `SpannableString` on Android). In practice, this is very tedious. For React Native, we decided to use web paradigm for this where you can nest text to achieve the same effect.
 
-```javascript
-<Text style={{fontWeight: 'bold'}}>
-  I am bold
-  <Text style={{color: 'red'}}>
-    and red
-  </Text>
-</Text>
+```ReactNativeWebPlayer
+import React, { Component } from 'react';
+import { AppRegistry, Text } from 'react-native';
+
+class BoldAndBeautiful extends Component {
+  render() {
+    return (
+      <Text style={{fontWeight: 'bold'}}>
+        I am bold
+        <Text style={{color: 'red'}}>
+          and red
+        </Text>
+      </Text>
+    );
+  }
+}
+
+AppRegistry.registerComponent('BoldAndBeautiful', () => BoldAndBeautiful);
 ```
 
 Behind the scenes, React Native converts this to a flat `NSAttributedString` or `SpannableString` that contains the following information:
@@ -25,15 +36,26 @@ Behind the scenes, React Native converts this to a flat `NSAttributedString` or
 
 On iOS, you can nest views within your Text component. Here's an example:
 
-```javascript
-<Text>
-  There is a blue square
-  <View style={{width: 50, height: 50, backgroundColor: 'steelblue'}} />
-  in between my text.
-</Text>
+```ReactNativeWebPlayer
+import React, { Component } from 'react';
+import { AppRegistry, Text, View } from 'react-native';
+
+class BlueIsCool extends Component {
+  render() {
+    return (
+      <Text>
+        There is a blue square
+        <View style={{width: 50, height: 50, backgroundColor: 'steelblue'}} />
+        in between my text.
+      </Text>
+    );
+  }
+}
+
+AppRegistry.registerComponent('BlueIsCool', () => BlueIsCool);
 ```
 
-In order to use this feature, you must give the view a `width` and a `height`.
+> In order to use this feature, you must give the view a `width` and a `height`.
 
 ## Containers