Updates from Mon 30 Mar

- [ReactNative] Clean up no longer needed reference to NavigationBarClass | Philipp von Weitershausen
- [TextInput] returnKeyType, enablesReturnKeyAutomatically, secureTextEntry, more keyboardTypes | Tadeu Zagallo
- [ReactNative] PropTypes for NavigationBars | Philipp von Weitershausen
- Changed LayoutAnimation to use ms instead of seconds for consistency | Nick Lockwood
- Better date support | Nick Lockwood
- Renamed throttleScrollCallbackMS to scrollEventThrottle | Nick Lockwood
- Fixed threading issues in RCTImageDownloader | Nick Lockwood
- [iOS][Assets]: Cleaning up more 1x png from Libraries | Radu Marin
- [ReactNative][docs] LinkingIOS | Tadeu Zagallo
- Fixing TouchableOpacity and TouchableHighlight documentation | Ben Alpert
- [react-native] Add React.addons.createFragment | Ben Alpert

Libraries/LinkingIOS/LinkingIOS.js

@@ -21,21 +21,86 @@ var _initialURL = RCTLinkingManager &&
 
 var DEVICE_NOTIF_EVENT = 'openURL';
 
+/**
+ * `LinkingIOS` gives you a general interface to interact with both, incoming
+ * and outgoing app links.
+ *
+ * ### Basic Usage
+ *
+ * #### Handling deep links
+ *
+ * If your app was launched from a external url registered to your app you can
+ * access and handle it from any component you want with
+ *
+ * ```
+ * componentDidMount() {
+ *  var url = LinkingIOS.popInitialURL();
+ * }
+ * ```
+ *
+ * In case you also want to listen to incoming app links during your app's
+ * execution you'll need to add the following lines to you `*AppDelegate.m`:
+ *
+ * ```
+ * - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
+ *   return [RCTLinkingManager application:application openURL:url sourceApplication:sourceApplication annotation:annotation];
+ * }
+ * ```
+ *
+ * And then on your React component you'll be able to listen to the events on
+ * `LinkingIOS` as follows
+ *
+ * ```
+ * componentDidMount() {
+ *   LinkingIOS.addEventListener('url', this._handleOpenURL);
+ * },
+ * componentWillUnmount() {
+ *   LinkingIOS.removeEventListener('url', this._handleOpenURL);
+ * },
+ * _handleOpenURL(event) {
+ *   console.log(event.url);
+ * }
+ * ```
+ *
+ * #### Triggering App links
+ *
+ * To trigger an app link (browser, email or custom schemas) you call
+ *
+ * ```
+ * LinkingIOS.openURL(url)
+ * ```
+ *
+ * If you want to check if any installed app can handle a given url beforehand you can call
+ * ```
+ * LinkingIOS.canOpenURL(url, (supported) => {
+ *   if (!supported) {
+ *     AlertIOS.alert('Can\'t handle url: ' + url);
+ *   } else {
+ *     LinkingIOS.openURL(url);
+ *   }
+ * });
+ * ```
+ */
 class LinkingIOS {
-  static addEventListener(type, handler) {
+  /**
+   * Add a handler to LinkingIOS changes by listening to the `url` event type
+   * and providing the handler
+   */
+  static addEventListener(type: string, handler: Function) {
     invariant(
       type === 'url',
       'LinkingIOS only supports `url` events'
     );
     _notifHandlers[handler] = RCTDeviceEventEmitter.addListener(
       DEVICE_NOTIF_EVENT,
-      (notifData) => {
-        handler(new LinkingIOS(notifData));
-      }
+      handler
     );
   }
 
-  static removeEventListener(type, handler) {
+  /**
+   * Remove a handler by passing the `url` event type and the handler
+   */
+  static removeEventListener(type: string, handler: Function ) {
     invariant(
       type === 'url',
       'LinkingIOS only supports `url` events'
@@ -47,7 +112,10 @@ class LinkingIOS {
     _notifHandlers[handler] = null;
   }
 
-  static openURL(url) {
+  /**
+   * Try to open the given `url` with any of the installed apps.
+   */
+  static openURL(url: string) {
     invariant(
       typeof url === 'string',
       'Invalid url: should be a string'
@@ -55,7 +123,11 @@ class LinkingIOS {
     RCTLinkingManager.openURL(url);
   }
 
-  static canOpenURL(url, callback) {
+  /**
+   * Determine wether or not the an installed app can handle a given `url`
+   * The callback function will be called with `bool supported` as the only argument
+   */
+  static canOpenURL(url: string, callback: Function) {
     invariant(
       typeof url === 'string',
       'Invalid url: should be a string'
@@ -67,7 +139,11 @@ class LinkingIOS {
     RCTLinkingManager.canOpenURL(url, callback);
   }
 
-  static popInitialURL() {
+  /**
+   * If the app launch was triggered by an app link, it will pop the link url,
+   * otherwise it will return `null`
+   */
+  static popInitialURL(): ?string {
     var initialURL = _initialURL;
     _initialURL = null;
     return initialURL;