Improve docs on Android Native Modules

Summary: Closes https://github.com/facebook/react-native/pull/5420

Reviewed By: svcscm

Differential Revision: D2844695

Pulled By: androidtrunkagent

fb-gh-sync-id: d23bd7ceb4ba34ec9f4368eda86730861560f0a8

docs/NativeModulesAndroid.md

@@ -221,7 +221,7 @@ public class UIManagerModule extends ReactContextBaseJavaModule {
 
       promise.resolve(map);
     } catch (IllegalViewOperationException e) {
-      promise.reject(e.getMessage());
+      promise.reject(e);
     }
   }
 
@@ -306,3 +306,122 @@ componentWillMount: function() {
 }
 ...
 ```
+
+### Getting activity result from `startActivityForResult`
+
+You'll need to listen to `onActivityResult` if you want to get results from an activity you started with `startActivityForResult`. To to do this, the module must implement `ActivityEventListener`. Then, you need to register a listener in the module's constructor,
+
+```java
+reactContext.addActivityEventListener(this);
+```
+
+Now you can listen to `onActivityResult` by implementing the following method:
+
+```java
+@Override
+public void onActivityResult(final int requestCode, final int resultCode, final Intent intent) {
+  // Your logic here
+}
+```
+
+We will implement a simple image picker to demonstrate this. The image picker will expose the method `pickImage` to JavaScript, which will return the path of the image when called.
+
+```java
+public class ImagePickerModule extends ReactContextBaseJavaModule implements ActivityEventListener {
+
+  private static final int IMAGE_PICKER_REQUEST = 467081;
+  private static final String E_ACTIVITY_DOES_NOT_EXIST = "E_ACTIVITY_DOES_NOT_EXIST";
+  private static final String E_PICKER_CANCELLED = "E_PICKER_CANCELLED";
+  private static final String E_FAILED_TO_SHOW_PICKER = "E_FAILED_TO_SHOW_PICKER";
+  private static final String E_NO_IMAGE_DATA_FOUND = "E_NO_IMAGE_DATA_FOUND";
+
+  private Promise mPickerPromise;
+
+  public ImagePickerModule(ReactApplicationContext reactContext) {
+    super(reactContext);
+
+    // Add the listener for `onActivityResult`
+    reactContext.addActivityEventListener(this);
+  }
+
+  @Override
+  public String getName() {
+    return "ImagePickerModule";
+  }
+
+  @ReactMethod
+  public void pickImage(final Promise promise) {
+    Activity currentActivity = getCurrentActivity();
+
+    if (currentActivity == null) {
+      promise.reject(E_ACTIVITY_DOES_NOT_EXIST, "Activity doesn't exist");
+      return;
+    }
+
+    // Store the promise to resolve/reject when picker returns data
+    mPickerPromise = promise;
+
+    try {
+      final Intent galleryIntent = new Intent(Intent.ACTION_PICK);
+
+      galleryIntent.setType("image/*");
+
+      final Intent chooserIntent = Intent.createChooser(galleryIntent, "Pick an image");
+
+      currentActivity.startActivityForResult(chooserIntent, PICK_IMAGE);
+    } catch (Exception e) {
+      mPickerPromise.reject(E_FAILED_TO_SHOW_PICKER, e);
+      mPickerPromise = null;
+    }
+  }
+
+  // You can get the result here
+  @Override
+  public void onActivityResult(final int requestCode, final int resultCode, final Intent intent) {
+    if (requestCode == IMAGE_PICKER_REQUEST) {
+      if (mPickerPromise != null) {
+        if (resultCode == Activity.RESULT_CANCELED) {
+          mPickerPromise.reject(E_PICKER_CANCELLED, "Image picker was cancelled");
+        } else if (resultCode == Activity.RESULT_OK) {
+          Uri uri = intent.getData();
+
+          if (uri == null) {
+            mPickerPromise.reject(E_NO_IMAGE_DATA_FOUND, "No image data found");
+          } else {
+            mPickerPromise.resolve(uri.toString());
+          }
+        }
+
+        mPickerPromise = null;
+      }
+    }
+  }
+}
+```
+
+### Listening to LifeCycle events
+
+Listening to the activity's LifeCycle events such as `onResume`, `onPause` etc. is very similar to how we implemented `ActivityEventListener`. The module must implement `ActivityEventListener`. Then, you need to register a listener in the module's constructor,
+
+```java
+reactContext.addLifecycleEventListener(this);
+```
+
+Now you can listen to the activity's LifeCycle events by implementing the following methods:
+
+```java
+@Override
+public void onHostResume() {
+    // Actvity `onResume`
+}
+
+@Override
+public void onHostPause() {
+    // Actvity `onPause`
+}
+
+@Override
+public void onHostDestroy() {
+    // Actvity `onDestroy`
+}
+```