[ReactNative][docs] LinkingIOS

Libraries/LinkingIOS/LinkingIOS.js

@@ -21,8 +21,72 @@ 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'
@@ -33,7 +97,10 @@ class LinkingIOS {
     );
   }
 
-  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'
@@ -45,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'
@@ -53,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'
@@ -65,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;