LayoutAnimation: Document step to enable it on Android (#499)

Author: sgny

reason-react-native/src/apis/LayoutAnimation.md

@@ -3,24 +3,47 @@ id: apis/LayoutAnimation
 title: LayoutAnimation
 ---
 
-`LayoutAnimation` API offers a simpler alternative to `Animated` API. Instead of directly manipulating values for various style props, it suffices to specify the animation to be run before the next render. Specification of the animation should happen in the reducer, before `state` is updated.
+`LayoutAnimation` API offers a simpler alternative to `Animated` API. Instead of
+directly manipulating values for various style props, it suffices to specify the
+animation to be run before the next render. Specification of the animation
+should happen in the reducer, before `state` is updated.
+
+`LayoutAnimation` is still experimental on Android and needs to be explicitly
+enabled with the `UIManager` method `setLayoutAnimationEnabledExperimental`.
+However, as that method should be removed when `LayoutAnimation` is no longer
+experimental, the external declaration for it wraps its type in `option` to
+avoid runtime errors when that happens. `LayoutAnimation` may be enabled, if it
+is not already enabled by default, by means of a statement such as:
+
+```reason
+switch (UIManager.setLayoutAnimationEnabledExperimental) {
+| None => ()
+| Some(setEnabled) => setEnabled(true)
+};
+```
 
 ## Methods
 
-- `configureNext` is the method to specify the animation, takes an argument of type `layoutAnimationConfig`.
+- `configureNext` is the method to specify the animation, takes an argument of
+ type `layoutAnimationConfig`.
 
 ```reason
 configureNext(layoutAnimationConfig)
 ```
 
-- `configureNextWithEndCallback` is a convenience function, which allows specification of a callback function (of type `unit => unit`) to be run after the animation, in addition to `layoutAnimationConfig`.
+- `configureNextWithEndCallback` is a convenience function, which allows
+ specification of a callback function (of type `unit => unit`) to be run after
+ the animation, in addition to `layoutAnimationConfig`.
+
 ```reason
 configureNextWithEndCallback(layoutAnimationConfig, callback)
 ```
 
 ## Types
 
-`layoutAnimationConfig` can be created with the `layoutAnimationConfig` constructor
+`layoutAnimationConfig` can be created with the `layoutAnimationConfig`
+constructor
+
 ```reason
 layoutAnimationConfig:
  (
@@ -31,6 +54,7 @@ layoutAnimationConfig:
  unit
  )
 ```
+
 or by means of the helper function `create`
 
 ```reason
@@ -49,7 +73,6 @@ create:
  )
 ```
 
-
 `animationConfig` can in turn be created with the `animationConfig` constructor
 
 ```reason
@@ -75,11 +98,15 @@ animationConfig:
 
 ## Presets
 
-There are presets for `linear`, `spring` and `easeInEaseOut` transitions which allow a very straightforward way to setup animation. Presets may either be passed as ready-made `layoutAnimationConfig` to `configureNext` and `configureNextWithEndCallback` as below
+There are presets for `linear`, `spring` and `easeInEaseOut` transitions which
+allow a very straightforward way to setup animation. Presets may either be
+passed as ready-made `layoutAnimationConfig` to `configureNext` and
+`configureNextWithEndCallback` as below
 
 ```reason
 LayoutAnimation.configureNext(LayoutAnimation.Presets.spring)
 ```
+
 or equivalently as already passed to `configureNext` as
 
 ```reason
@@ -89,8 +116,9 @@ LayoutAnimation.spring()
 
 ## Example
 
-The example below illustrates animated transition (`spring`) between two views, such as registration and login forms. Animation is specified in the reducer, as below. Making use of `presets` is also illustrated (commented out).
-
+The example below illustrates animated transition (`spring`) between two views,
+such as registration and login forms. Animation is specified in the reducer, as
+below, before state is returned.
 
 ```reason
 open ReactNative;
@@ -157,11 +185,15 @@ let make = () => {
 };
 ```
 
-Above animation specification is that of the `spring` preset. Accordingly, the animation could have been specified as
+Note that above animation specification is that of the `spring` preset.
+Accordingly, the animation could have been specified as
+
 ```reason
 LayoutAnimation.configureNext(LayoutAnimation.Presets.spring);
 ```
+
 or equivalently as
+
 ```reason
 LayoutAnimation.spring();
 ```