Merge pull request #202 from sahrens/docs

Docs

docs/NativeModulesIOS.md

@@ -4,7 +4,7 @@ title: Native Modules (iOS)
 layout: docs
 category: Guides
 permalink: docs/nativemodulesios.html
-next: activityindicatorios
+next: testing
 ---
 
 Sometimes an app needs access to platform API, and React Native doesn't have a corresponding wrapper yet. Maybe you want to reuse some existing Objective-C or C++ code without having to reimplement it in JavaScript. Or write some high performance, multi-threaded code such as image processing, network stack, database or rendering.
@@ -197,4 +197,3 @@ var subscription = DeviceEventEmitter.addListener(
 subscription.remove();
 ```
 For more examples of sending events to JavaScript, see [`RCTLocationObserver`](https://github.com/facebook/react-native/blob/master/Libraries/Geolocation/RCTLocationObserver.m).
-

docs/Testing.md

@@ -0,0 +1,24 @@
+---
+id: testing
+title: Testing
+layout: docs
+category: Guides
+permalink: docs/testing.html
+next: activityindicatorios
+---
+
+## Running Tests and Contributing
+
+The React Native repo has several tests you can run to verify you haven't caused a regression with your PR.  These tests are run with the [Travis](http://docs.travis-ci.com/) continuous integration system, and will automatically post the results to your PR.  You can also run them locally with cmd+U in the IntegrationTest and UIExplorer apps in Xcode.  You can run the jest tests via `npm test` on the command line.  We don't have great test coverage yet, however, so most changes will still require significant manual verification, but we would love it if you want to help us increase our test coverage!
+
+## Jest Tests
+
+[Jest](http://facebook.github.io/jest/) tests are JS-only tests run on the command line with node.  The tests themselves live in the `__tests__` directories of the files they test, and there is a large emphasis on aggressively mocking out functionality that is not under test for failure isolation and maximum speed.  You can run the existing React Native jest tests with `npm test` from the react-native root, and we encourage you to add your own tests for any components you want to contribute to.  See [`getImageSource-test.js`](https://github.com/facebook/react-native/blob/master/Examples/Movies/__tests__/getImageSource-test.js) for a basic example.
+
+## Integration Tests.
+
+React Native provides facilities to make it easier to test integrated components that require both native and JS components to communicate across the bridge.  The two main components are `RCTTestRunner` and `RCTTestModule`.  `RCTTestRunner` sets up the ReactNative environment and provides facilities to run the tests as `XCTestCase`s in Xcode (`runTest:module` is the simplest method).  `RCTTestModule` is exported to JS via `NativeModules` as `TestModule`.  The tests themselves are written in JS, and must call `TestModule.markTestCompleted()` when they are done, otherwise the test will timeout and fail.  Test failures are primarily indicated by throwing an exception.  It is also possible to test error conditions with `runTest:module:initialProps:expectErrorRegex:` or `runTest:module:initialProps:expectErrorBlock:` which will expect an error to be thrown and verify the error matches the provided criteria.  See [`IntegrationTestHarnessTest.js`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestHarnessTest.js) and [`IntegrationTestsTests.m`](https://github.com/facebook/react-native/blob/master/IntegrationTests/IntegrationTestsTests/IntegrationTestsTests.m) for example usage.
+
+## Snapshot Tests
+
+A common type of integration test is the snapshot test.  These tests render a component, and verify snapshots of the screen against reference images using `TestModule.verifySnapshot()`, using the [`FBSnapshotTestCase`](https://github.com/facebook/ios-snapshot-test-case) library behind the scenes.  Reference images are recorded by setting `recordMode = YES` on the `RCTTestRunner`, then running the tests.  Snapshots will differ slightly between 32 and 64 bit, and various OS versions, so it's recommended that you enforce tests are run with the correct configuration.  It's also highly recommended that all network data be mocked out, along with other potentially troublesome dependencies.  See [`SimpleSnapshotTest`](https://github.com/facebook/react-native/blob/master/IntegrationTests/SimpleSnapshotTest.js) for a basic example.

website/src/react-native/_index.js

@@ -32,7 +32,9 @@ var index = React.createClass({
           </section>
 
           <h2>Native iOS Components</h2>
-          <p>With React Native, you can use the platform components such as iOS UITabBar and UINavigationController.</p>
+          <p>
+            With React Native, you can use the standard platform components such as UITabBar and UINavigationController on iOS.  This gives your app a consistent look and feel with the rest of the platform ecosystem, and keeps the quality bar high.  These components are easily incorporated into your app using their React component counterparts, such as TabBarIOS and NavigatorIOS.
+          </p>
           <Prism>
 {`var React = require('react-native');
 var { TabBarIOS, NavigatorIOS } = React;
@@ -49,13 +51,16 @@ module.exports = React.createClass({
 });`}
           </Prism>
 
-          <h2>Async</h2>
-
-          <p>Decoding images off of the main thread... Asynchronous bridge, Chrome Dev Tools...</p>
-
+          <h2>Asynchronous</h2>
+          <p>
+            All operations between the JavaScript application code and the native platform are performed asynchronously, and the native modules can also make use of additional threads as well.  This means we can decode images off of the main thread, save to disk in the background, measure text and compute layouts without blocking the UI, and more.  As a result, React Native apps are naturally fluid and responsive.  The communication is also fully serializable, which allows us to leverage Chrome Developer Tools to debug JS while running the app in the full app environment, in the sim or on a real device.
+          </p>
+          <img src="/react-native/img/chrome_breakpoint.png" width="800"/>
           <h2>Touch Handling</h2>
-          <p>iOS has a very powerful system called Responder to handle touches which the web lacks. React Native implements iOS responder system and provides high level components such as TouchableHighlight that work well right off the bat.</p>
 
+          <p>
+            iOS has a very powerful system called the Responder Chain to negotiate touches in complex view hierarchies which does not have a universal analog on the web. React Native implements a similar responder system and provides high level components such as TouchableHighlight that integrate properly with scroll views and other elements without any additional configutation.
+          </p>
           <Prism>
 {`var React = require('react-native');
 var { ScrollView, TouchableHighlight, Text } = React;
@@ -63,7 +68,7 @@ module.exports = React.createClass({
   render: function() {
     return (
       <ScrollView>
-        <TouchableHighlight underlayColor="#cccccc">
+        <TouchableHighlight onPress={() => console.log('pressed')}>
           <Text>Proper Touch Handling</Text>
         </TouchableHighlight>
       </ScrollView>
@@ -72,9 +77,10 @@ module.exports = React.createClass({
 });`}
           </Prism>
 
-          <h2>Flexbox</h2>
-          <p>Laying out views should be easy</p>
-
+          <h2>Flexbox and Styling</h2>
+          <p>
+            Laying out views should be easy, which is why we brought the flexbox layout model from the web to React Native.  Flexbox makes it easy to build the most common UI layouts, such as stacked and nested boxes with margin and padding.  React Native also supports common web syles, such as fontWeight, and the StyleSheet abstraction makes it easy to declare all your styles and layout right along with the components that use them and used inline.
+          </p>
           <Prism>
 {`var React = require('react-native');
 var { Image, StyleSheet, Text, View } = React;
@@ -87,8 +93,12 @@ module.exports = React.createClass({
           style={styles.image}
         />
         <View style={styles.text}>
-          <Text style={styles.title}>React Native</Text>
-          <Text style={styles.subtitle}>Build high quality mobile apps using React</Text>
+          <Text style={styles.title}>
+            React Native
+          </Text>
+          <Text style={styles.subtitle}>
+            Build high quality mobile apps using React
+          </Text>
         </View>
       </View>
     );
@@ -104,8 +114,33 @@ var styles = StyleSheet.create({
           </Prism>
 
           <h2>Polyfills</h2>
-          <p>React Native attempts to innovate on the view layer, for the rest, it polyfills web standards. You can use npm to install JavaScript dependencies, XMLHttpRequest, requestAnimationFrame, navigator.geolocation...</p>
-
+          <p>
+            React Native is focused on changing the way view code is written.  For the rest, we look to the web for universal standards and polyfill those APIs where appropriate. You can use npm to install JavaScript libraries that work on top of the functionality baked into React Native, such as XMLHttpRequest, requestAnimationFrame, and navigator.geolocation.  We are working on expanding the available APIs, and are excited for the Open Source community to contribute as well.
+          </p>
+          <Prism>
+{`var React = require('react-native');
+var { Text } = React;
+module.exports = React.createClass({
+  getInitialState: function() {
+    return {
+      position: 'unknown',
+    };
+  },
+  componentDidMount: function() {
+    navigator.geolocation.getCurrentPosition(
+      (position) => this.setState({position}),
+      (error) => console.error(error)
+    );
+  },
+  render: function() {
+    return (
+      <Text>
+        Position: {JSON.stringify(this.state.position)}
+      </Text>
+    );
+  },
+});`}
+          </Prism>
         </section>
       </Site>
     );