Explanation of Modal's purpose in hybrid apps

Summary: Explained that Modal is for hybrid apps and suggest using a top-level Navigator in pure RN apps.
Closes https://github.com/facebook/react-native/pull/2663

Reviewed By: @​svcscm

Differential Revision: D2483626

Pulled By: @sahrens

Libraries/Modal/Modal.js

@@ -19,6 +19,18 @@ var View = require('View');
 var requireNativeComponent = require('requireNativeComponent');
 var RCTModalHostView = requireNativeComponent('RCTModalHostView', null);
 
+/**
+ * A Modal component covers the native view (e.g. UIViewController, Activity)
+ * that contains the React Native root.
+ *
+ * Use Modal in hybrid apps that embed React Native; Modal allows the portion of
+ * your app written in React Native to present content above the enclosing
+ * native view hierarchy.
+ *
+ * In apps written with React Native from the root view down, you should use
+ * Navigator instead of Modal. With a top-level Navigator, you have more control
+ * over how to present the modal scene over the rest of your app.
+ */
 class Modal extends React.Component {
   render(): ?ReactElement {
     if (this.props.visible === false) {