Add documentation for the navigation

Author: Matthieu Napoli

App/Containers/Root/RootScreen.js

@@ -16,12 +16,14 @@ import StartupActions from 'App/Stores/Startup/Actions'
 const AppNav = createStackNavigator(
   {
     // Create the application routes here (the key is the route name, the value is the target screen)
+    // See https://reactnavigation.org/docs/en/stack-navigator.html#routeconfigs
     SplashScreen: SplashScreen,
     MainScreen: ExampleScreen,
   },
   {
     // By default the application will show the splash screen
     initialRouteName: 'SplashScreen',
+    // See https://reactnavigation.org/docs/en/stack-navigator.html#stacknavigatorconfig
     headerMode: 'none',
   }
 )
@@ -36,6 +38,7 @@ class RootScreen extends Component {
     return (
       <View style={styles.container}>
         <AppNav
+          // Initialize the NavigationService (see https://reactnavigation.org/docs/en/navigating-without-navigation-prop.html)
           ref={(navigatorRef) => {
             NavigationService.setTopLevelNavigator(navigatorRef)
           }}

App/Services/NavigationService.js

@@ -1,22 +1,46 @@
 import { NavigationActions, StackActions } from 'react-navigation'
 
-let _navigator
+/**
+ * The navigation is implemented as a service so that it can be used outside of components, for example in sagas.
+ *
+ * @see https://reactnavigation.org/docs/en/navigating-without-navigation-prop.html
+ */
 
+let navigator
+
+/**
+ * This function is called when the RootScreen is created to set the navigator instance to use.
+ */
 function setTopLevelNavigator(navigatorRef) {
-  _navigator = navigatorRef
+  navigator = navigatorRef
 }
 
+/**
+ * Call this function when you want to navigate to a specific route.
+ *
+ * @param routeName The name of the route to navigate to. Routes are defined in RootScreen using createStackNavigator()
+ * @param params Route parameters.
+ */
 function navigate(routeName, params) {
-  _navigator.dispatch(
+  navigator.dispatch(
     NavigationActions.navigate({
       routeName,
       params,
     })
   )
 }
 
+/**
+ * Call this function when you want to navigate to a specific route AND reset the navigation history.
+ *
+ * That means the user cannot go back. This is useful for example to redirect from a splashscreen to
+ * the main screen: the user should not be able to go back to the splashscreen.
+ *
+ * @param routeName The name of the route to navigate to. Routes are defined in RootScreen using createStackNavigator()
+ * @param params Route parameters.
+ */
 function navigateAndReset(routeName, params) {
-  _navigator.dispatch(
+  navigator.dispatch(
     StackActions.reset({
       index: 0,
       key: null,
@@ -30,7 +54,6 @@ function navigateAndReset(routeName, params) {
   )
 }
 
-// add other navigation functions that you need and export them
 export default {
   navigate,
   navigateAndReset,

App/Services/README.md

@@ -1 +1 @@
-This directory contains services that are meant to connect the application to other APIs, for example an API client for Yahoo's weather service.
+This directory contains application services, for example services to connect the application to APIs.

README.md

@@ -16,7 +16,7 @@ The boilerplate contains:
 - [reduxsauce](https://github.com/infinitered/reduxsauce) (v0.7) to facilitate using Redux
 - [apisauce](https://github.com/infinitered/apisauce) (v0.15) to make [axios](https://github.com/axios/axios) even better
 - [prettier](https://prettier.io/) and [eslint](https://eslint.org/) preconfigured for React Native
-- [react-native-navigation](https://reactnavigation.org) (v2.12) for the application's navigation
+- [react-native-navigation](https://reactnavigation.org) (v2.12) with a [`NavigationService`](App/Services/NavigationService.js) for the application's navigation
 
 ## Updates