Migrate to new documentation format

Summary:
Now that the Component and API docs are no longer auto-generated, we need to consolidate on a new format for our jsdoc comments. Any help from the community will be appreciated.

In this initial pull request, we'll be tackling the following docs:

- `AccessibilityInfo`, an API doc.
- `ActivityIndicator`, a Component doc.
- `View`, a Component doc.

This top comment will serve as a style guide, and when in doubt, please refer to the individual commits in this PR.

Each commit should update a single component or API, along with any relevant markdown files.

- Documentation in the JavaScript source files should be succinct. Any verbosity should be moved over to the markdown docs in the website...
- ...by adding a link to the relevant method/prop on the website to every comment block.
- Avoid markdown style links in JavaScript source files, opt for plain old URIs.

Let code document itself:

- If a method is Flow typed, the comment block does not need to repeat this information.
- If a param can be one of several values, and the type definition is easily determined from the code, the values should not be repeated in the comment block. Again, move this to the markdown doc if not present already.
Closes #16790

Differential Revision: D6353840

Pulled By: hramos

fbshipit-source-id: 9712c459acc33092aae9909f3dd0b58a00b26afc

Libraries/Components/AccessibilityInfo/AccessibilityInfo.android.js

@@ -24,6 +24,16 @@ type ChangeEventName = $Enum<{
 
 var _subscriptions = new Map();
 
+/**
+ * Sometimes it's useful to know whether or not the device has a screen reader
+ * that is currently active. The `AccessibilityInfo` API is designed for this
+ * purpose. You can use it to query the current state of the screen reader as 
+ * well as to register to be notified when the state of the screen reader 
+ * changes.
+ *
+ * See http://facebook.github.io/react-native/docs/accessibilityinfo.html
+ */
+
 var AccessibilityInfo = {
 
   fetch: function(): Promise {

Libraries/Components/AccessibilityInfo/AccessibilityInfo.ios.js

@@ -28,61 +28,23 @@ type ChangeEventName = $Enum<{
 var _subscriptions = new Map();
 
 /**
- * Sometimes it's useful to know whether or not the device has a screen reader that is currently active. The
- * `AccessibilityInfo` API is designed for this purpose. You can use it to query the current state of the
- * screen reader as well as to register to be notified when the state of the screen reader changes.
+ * Sometimes it's useful to know whether or not the device has a screen reader
+ * that is currently active. The `AccessibilityInfo` API is designed for this
+ * purpose. You can use it to query the current state of the screen reader as 
+ * well as to register to be notified when the state of the screen reader 
+ * changes.
  *
- * Here's a small example illustrating how to use `AccessibilityInfo`:
- *
- * ```javascript
- * class ScreenReaderStatusExample extends React.Component {
- *   state = {
- *     screenReaderEnabled: false,
- *   }
- *
- *   componentDidMount() {
- *     AccessibilityInfo.addEventListener(
- *       'change',
- *       this._handleScreenReaderToggled
- *     );
- *     AccessibilityInfo.fetch().done((isEnabled) => {
- *       this.setState({
- *         screenReaderEnabled: isEnabled
- *       });
- *     });
- *   }
- *
- *   componentWillUnmount() {
- *     AccessibilityInfo.removeEventListener(
- *       'change',
- *       this._handleScreenReaderToggled
- *     );
- *   }
- *
- *   _handleScreenReaderToggled = (isEnabled) => {
- *     this.setState({
- *       screenReaderEnabled: isEnabled,
- *     });
- *   }
- *
- *   render() {
- *     return (
- *       <View>
- *         <Text>
- *           The screen reader is {this.state.screenReaderEnabled ? 'enabled' : 'disabled'}.
- *         </Text>
- *       </View>
- *     );
- *   }
- * }
- * ```
+ * See http://facebook.github.io/react-native/docs/accessibilityinfo.html
  */
 var AccessibilityInfo = {
 
   /**
-   * Query whether a screen reader is currently enabled. Returns a promise which
-   * resolves to a boolean. The result is `true` when a screen reader is enabled
-   * and `false` otherwise.
+   * Query whether a screen reader is currently enabled. 
+   * 
+   * Returns a promise which resolves to a boolean. 
+   * The result is `true` when a screen reader is enabledand `false` otherwise.
+   * 
+   * See http://facebook.github.io/react-native/docs/accessibilityinfo.html#fetch
    */
   fetch: function(): Promise {
     return new Promise((resolve, reject) => {
@@ -100,10 +62,13 @@ var AccessibilityInfo = {
    *   to the event handler is a boolean. The boolean is `true` when a screen
    *   reader is enabled and `false` otherwise.
    * - `announcementFinished`: iOS-only event. Fires when the screen reader has
-   *   finished making an announcement. The argument to the event handler is a dictionary
-   *   with these keys:
+   *   finished making an announcement. The argument to the event handler is a
+   *   dictionary with these keys:
    *     - `announcement`: The string announced by the screen reader.
-   *     - `success`: A boolean indicating whether the announcement was successfully made.
+   *     - `success`: A boolean indicating whether the announcement was
+   *       successfully made.
+   * 
+   * See http://facebook.github.io/react-native/docs/accessibilityinfo.html#addeventlistener
    */
   addEventListener: function (
     eventName: ChangeEventName,
@@ -130,7 +95,11 @@ var AccessibilityInfo = {
   },
 
   /**
-   * iOS-Only. Set accessibility focus to a react component.
+   * Set accessibility focus to a react component.
+   * 
+   * @platform ios
+   * 
+   * See http://facebook.github.io/react-native/docs/accessibilityinfo.html#setaccessibilityfocus
    */
   setAccessibilityFocus: function(
     reactTag: number
@@ -139,7 +108,11 @@ var AccessibilityInfo = {
   },
 
   /**
-   * iOS-Only. Post a string to be announced by the screen reader.
+   * Post a string to be announced by the screen reader.
+   *
+   * @platform ios
+   * 
+   * See http://facebook.github.io/react-native/docs/accessibilityinfo.html#announceforaccessibility
    */
   announceForAccessibility: function(
     announcement: string
@@ -149,6 +122,8 @@ var AccessibilityInfo = {
 
   /**
    * Remove an event handler.
+   * 
+   * See http://facebook.github.io/react-native/docs/accessibilityinfo.html#removeeventlistener
    */
   removeEventListener: function(
     eventName: ChangeEventName,

Libraries/Components/ActivityIndicator/ActivityIndicator.js

@@ -38,45 +38,7 @@ type DefaultProps = {
 /**
  * Displays a circular loading indicator.
  *
- * ### Example
- *
- * ```ReactNativeWebPlayer
- * import React, { Component } from 'react'
- * import {
- *   ActivityIndicator,
- *   AppRegistry,
- *   StyleSheet,
- *   Text,
- *   View,
- * } from 'react-native'
- *
- * class App extends Component {
- *   render() {
- *     return (
- *       <View style={[styles.container, styles.horizontal]}>
- *         <ActivityIndicator size="large" color="#0000ff" />
- *         <ActivityIndicator size="small" color="#00ff00" />
- *         <ActivityIndicator size="large" color="#0000ff" />
- *         <ActivityIndicator size="small" color="#00ff00" />
- *       </View>
- *     )
- *   }
- * }
- *
- * const styles = StyleSheet.create({
- *   container: {
- *     flex: 1,
- *     justifyContent: 'center'
- *   },
- *   horizontal: {
- *     flexDirection: 'row',
- *     justifyContent: 'space-around',
- *     padding: 10
- *   }
- * })
- *
- * AppRegistry.registerComponent('App', () => App)
- * ```
+ * See http://facebook.github.io/react-native/docs/activityindicator.html
  */
 const ActivityIndicator = createReactClass({
   displayName: 'ActivityIndicator',
@@ -86,15 +48,21 @@ const ActivityIndicator = createReactClass({
     ...ViewPropTypes,
     /**
      * Whether to show the indicator (true, the default) or hide it (false).
+     * 
+     * See http://facebook.github.io/react-native/docs/activityindicator.html#animating
      */
     animating: PropTypes.bool,
     /**
      * The foreground color of the spinner (default is gray).
+     * 
+     * See http://facebook.github.io/react-native/docs/activityindicator.html#color
      */
     color: ColorPropType,
     /**
      * Size of the indicator (default is 'small').
      * Passing a number to the size prop is only supported on Android.
+     * 
+     * See http://facebook.github.io/react-native/docs/activityindicator.html#size
      */
     size: PropTypes.oneOfType([
       PropTypes.oneOf([ 'small', 'large' ]),
@@ -104,6 +72,8 @@ const ActivityIndicator = createReactClass({
      * Whether the indicator should hide when not animating (true by default).
      *
      * @platform ios
+     * 
+     * See http://facebook.github.io/react-native/docs/activityindicator.html#hideswhenstopped
      */
     hidesWhenStopped: PropTypes.bool,
   },

Libraries/Components/View/View.js

@@ -28,50 +28,9 @@ import type {ViewProps} from 'ViewPropTypes';
 export type Props = ViewProps;
 
 /**
- * The most fundamental component for building a UI, `View` is a container that supports layout with
- * [flexbox](docs/flexbox.html), [style](docs/style.html),
- * [some touch handling](docs/handling-touches.html), and
- * [accessibility](docs/accessibility.html) controls. `View` maps directly to the
- * native view equivalent on whatever platform React Native is running on, whether that is a
- * `UIView`, `<div>`, `android.view`, etc.
+ * The most fundamental component for building a UI.
  *
- * `View` is designed to be nested inside other views and can have 0 to many children of any type.
- *
- * This example creates a `View` that wraps two colored boxes and a text component in a row with
- * padding.
- *
- * ```javascript
- * class ViewColoredBoxesWithText extends Component {
- *   render() {
- *     return (
- *       <View style={{flexDirection: 'row', height: 100, padding: 20}}>
- *         <View style={{backgroundColor: 'blue', flex: 0.3}} />
- *         <View style={{backgroundColor: 'red', flex: 0.5}} />
- *         <Text>Hello World!</Text>
- *       </View>
- *     );
- *   }
- * }
- * ```
- *
- * > `View`s are designed to be used with [`StyleSheet`](docs/style.html) for clarity
- * > and performance, although inline styles are also supported.
- *
- * ### Synthetic Touch Events
- *
- * For `View` responder props (e.g., `onResponderMove`), the synthetic touch event passed to them
- * are of the following form:
- *
- * - `nativeEvent`
- *   - `changedTouches` - Array of all touch events that have changed since the last event.
- *   - `identifier` - The ID of the touch.
- *   - `locationX` - The X position of the touch, relative to the element.
- *   - `locationY` - The Y position of the touch, relative to the element.
- *   - `pageX` - The X position of the touch, relative to the root element.
- *   - `pageY` - The Y position of the touch, relative to the root element.
- *   - `target` - The node id of the element receiving the touch event.
- *   - `timestamp` - A time identifier for the touch, useful for velocity calculation.
- *   - `touches` - Array of all current touches on the screen.
+ * See http://facebook.github.io/react-native/docs/view.html
  */
 const View = createReactClass({
   displayName: 'View',