From cb6ec7c32141ef5bdde837d7f9d71b7adb83b751 Mon Sep 17 00:00:00 2001
From: Garrett McCullough <garrett.mccullough@build.com>
Date: Tue, 7 Nov 2017 11:34:20 -0800
Subject: [PATCH] improve docs for KeyboardAvoidingView

Summary:
The documentation for `KeyboardAvoidingView` was pretty thin. Tried to fill it out more and corrected a couple words.

n/a

[DOCS] [ENHANCEMENT] [KeyboardAvoidingView] - Improve the documentation for the props for KeyboardAvoidingView

* **Who does this affect**: Users that are manually calling the methods on KeyboardingAvoidingView.
* **How to migrate**: Add an underscore before the name of the method
* **Why make this breaking change**: These methods are not meant to be public. For example, the exposed `onLayout` function is not a prop that accepts a function like is typical of the rest of React Native but is the internal method that is called when the component's onLayout is triggered.
* **Severity (number of people affected x effort)**: Low
Closes https://github.com/facebook/react-native/pull/16479

Differential Revision: D6261005

Pulled By: hramos

fbshipit-source-id: 7e0bcfb0e7cb6bb419964bd0b02cf52c9347c608
---
 .../Keyboard/KeyboardAvoidingView.js          | 32 +++++++++++--------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/Libraries/Components/Keyboard/KeyboardAvoidingView.js b/Libraries/Components/Keyboard/KeyboardAvoidingView.js
index 5b90702fefd363..1f6c4848496d5d 100644
--- a/Libraries/Components/Keyboard/KeyboardAvoidingView.js
+++ b/Libraries/Components/Keyboard/KeyboardAvoidingView.js
@@ -43,8 +43,8 @@ type KeyboardChangeEvent = {
 const viewRef = 'VIEW';
 
 /**
- * It is a component to solve the common problem of views that need to move out of the way of the virtual keyboard.
- * It can automatically adjust either its position or bottom padding based on the position of the keyboard.
+ * This is a component to solve the common problem of views that need to move out of the way of the virtual keyboard.
+ * It can automatically adjust either its height, position or bottom padding based on the position of the keyboard.
  */
 const KeyboardAvoidingView = createReactClass({
   displayName: 'KeyboardAvoidingView',
@@ -52,6 +52,10 @@ const KeyboardAvoidingView = createReactClass({
 
   propTypes: {
     ...ViewPropTypes,
+    /**
+     * Specify how the `KeyboardAvoidingView` will react to the presence of
+     * the keyboard. It can adjust the height, position or bottom padding of the view
+     */
     behavior: PropTypes.oneOf(['height', 'position', 'padding']),
 
     /**
@@ -61,7 +65,7 @@ const KeyboardAvoidingView = createReactClass({
 
     /**
      * This is the distance between the top of the user screen and the react native view,
-     * may be non-zero in some use cases.
+     * may be non-zero in some use cases. The default value is 0.
      */
     keyboardVerticalOffset: PropTypes.number.isRequired,
   },
@@ -81,7 +85,7 @@ const KeyboardAvoidingView = createReactClass({
   subscriptions: ([]: Array<EmitterSubscription>),
   frame: (null: ?ViewLayout),
 
-  relativeKeyboardHeight(keyboardFrame: ScreenRect): number {
+  _relativeKeyboardHeight(keyboardFrame: ScreenRect): number {
     const frame = this.frame;
     if (!frame || !keyboardFrame) {
       return 0;
@@ -94,14 +98,14 @@ const KeyboardAvoidingView = createReactClass({
     return Math.max(frame.y + frame.height - keyboardY, 0);
   },
 
-  onKeyboardChange(event: ?KeyboardChangeEvent) {
+  _onKeyboardChange(event: ?KeyboardChangeEvent) {
     if (!event) {
       this.setState({bottom: 0});
       return;
     }
 
     const {duration, easing, endCoordinates} = event;
-    const height = this.relativeKeyboardHeight(endCoordinates);
+    const height = this._relativeKeyboardHeight(endCoordinates);
 
     if (duration && easing) {
       LayoutAnimation.configureNext({
@@ -115,7 +119,7 @@ const KeyboardAvoidingView = createReactClass({
     this.setState({bottom: height});
   },
 
-  onLayout(event: ViewLayoutEvent) {
+  _onLayout(event: ViewLayoutEvent) {
     this.frame = event.nativeEvent.layout;
   },
 
@@ -132,12 +136,12 @@ const KeyboardAvoidingView = createReactClass({
   componentWillMount() {
     if (Platform.OS === 'ios') {
       this.subscriptions = [
-        Keyboard.addListener('keyboardWillChangeFrame', this.onKeyboardChange),
+        Keyboard.addListener('keyboardWillChangeFrame', this._onKeyboardChange),
       ];
     } else {
       this.subscriptions = [
-        Keyboard.addListener('keyboardDidHide', this.onKeyboardChange),
-        Keyboard.addListener('keyboardDidShow', this.onKeyboardChange),
+        Keyboard.addListener('keyboardDidHide', this._onKeyboardChange),
+        Keyboard.addListener('keyboardDidShow', this._onKeyboardChange),
       ];
     }
   },
@@ -161,7 +165,7 @@ const KeyboardAvoidingView = createReactClass({
           heightStyle = {height: this.frame.height - this.state.bottom, flex: 0};
         }
         return (
-          <View ref={viewRef} style={[style, heightStyle]} onLayout={this.onLayout} {...props}>
+          <View ref={viewRef} style={[style, heightStyle]} onLayout={this._onLayout} {...props}>
             {children}
           </View>
         );
@@ -171,7 +175,7 @@ const KeyboardAvoidingView = createReactClass({
         const { contentContainerStyle } = this.props;
 
         return (
-          <View ref={viewRef} style={style} onLayout={this.onLayout} {...props}>
+          <View ref={viewRef} style={style} onLayout={this._onLayout} {...props}>
             <View style={[contentContainerStyle, positionStyle]}>
               {children}
             </View>
@@ -181,14 +185,14 @@ const KeyboardAvoidingView = createReactClass({
       case 'padding':
         const paddingStyle = {paddingBottom: this.state.bottom};
         return (
-          <View ref={viewRef} style={[style, paddingStyle]} onLayout={this.onLayout} {...props}>
+          <View ref={viewRef} style={[style, paddingStyle]} onLayout={this._onLayout} {...props}>
             {children}
           </View>
         );
 
       default:
         return (
-          <View ref={viewRef} onLayout={this.onLayout} style={style} {...props}>
+          <View ref={viewRef} onLayout={this._onLayout} style={style} {...props}>
             {children}
           </View>
         );