Display component methods on the website and tweak the documentation

Summary:The website now displays public methods on components. This was implemented mostly in react-docgen via facebook#66. This adds a <Method> component that is used by the component and API doc pages to display documentation for a method. It also adds some missing documentation and tweak some existing one to integrate with this feature. I also prefixed some component methods with an '_' so they don't show up in the doc. **Test plan (required)** Tested every component page locally to make sure the methods doc was displayed properly. Tested an API page to make sure it still worked properly. Closes facebook#6890 Differential Revision: D3159911 Pulled By: vjeux fb-gh-sync-id: 1e6a4640cda6794496d9844c1af6a1451c017dcc fbshipit-source-id: 1e6a4640cda6794496d9844c1af6a1451c017dcc
nightingale · Jun 18, 2016 · fa6e6cc · fa6e6cc
1 parent 97cdcd2
commit fa6e6cc
Show file tree

Hide file tree

Showing 14 changed files with 297 additions and 152 deletions.
diff --git a/Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.android.js b/Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.android.js
@@ -223,14 +223,20 @@ var DrawerLayoutAndroid = React.createClass({
     }
   },
 
-  openDrawer: function() {
+  /**
+   * Opens the drawer.
+   */
+  openDrawer: function(test: number) {
     UIManager.dispatchViewManagerCommand(
       this._getDrawerLayoutHandle(),
       UIManager.AndroidDrawerLayout.Commands.openDrawer,
       null
     );
   },
 
+  /**
+   * Closes the drawer.
+   */
   closeDrawer: function() {
     UIManager.dispatchViewManagerCommand(
       this._getDrawerLayoutHandle(),

diff --git a/Libraries/Components/Navigation/NavigatorIOS.ios.js b/Libraries/Components/Navigation/NavigatorIOS.ios.js
@@ -143,20 +143,6 @@ type Event = Object;
  * });
  * ```
  *
- * A navigation object contains the following functions:
- *
- *  - `push(route)` - Navigate forward to a new route
- *  - `pop()` - Go back one page
- *  - `popN(n)` - Go back N pages at once. When N=1, behavior matches `pop()`
- *  - `replace(route)` - Replace the route for the current page and immediately
- *    load the view for the new route
- *  - `replacePrevious(route)` - Replace the route/view for the previous page
- *  - `replacePreviousAndPop(route)` - Replaces the previous route/view and
- *    transitions back to it
- *  - `resetTo(route)` - Replaces the top item and popToTop
- *  - `popToRoute(route)` - Go back to the item for a particular route object
- *  - `popToTop()` - Go back to the top item
- *
  * Navigator functions are also available on the NavigatorIOS component:
  *
  * ```
@@ -492,6 +478,9 @@ var NavigatorIOS = React.createClass({
     this.navigationContext.emit('willfocus', {route: route});
   },
 
+  /**
+   * Navigate forward to a new route
+   */
   push: function(route: Route) {
     invariant(!!route, 'Must supply route to push');
     // Make sure all previous requests are caught up first. Otherwise reject.
@@ -514,6 +503,9 @@ var NavigatorIOS = React.createClass({
     }
   },
 
+  /**
+   * Go back N pages at once. When N=1, behavior matches `pop()`
+   */
   popN: function(n: number) {
     if (n === 0) {
       return;
@@ -535,6 +527,9 @@ var NavigatorIOS = React.createClass({
     }
   },
 
+  /**
+   * Go back one page
+   */
   pop: function() {
     this.popN(1);
   },
@@ -574,23 +569,30 @@ var NavigatorIOS = React.createClass({
   },
 
   /**
-   * Replaces the top of the navigation stack.
+   * Replace the route for the current page and immediately
+   * load the view for the new route.
    */
   replace: function(route: Route) {
     this.replaceAtIndex(route, -1);
   },
 
   /**
-   * Replace the current route's parent.
+   * Replace the route/view for the previous page.
    */
   replacePrevious: function(route: Route) {
     this.replaceAtIndex(route, -2);
   },
 
+  /**
+   * Go back to the top item
+   */
   popToTop: function() {
     this.popToRoute(this.state.routeStack[0]);
   },
 
+  /**
+   * Go back to the item for a particular route object
+   */
   popToRoute: function(route: Route) {
     var indexOfRoute = this.state.routeStack.indexOf(route);
     invariant(
@@ -601,6 +603,9 @@ var NavigatorIOS = React.createClass({
     this.popN(numToPop);
   },
 
+  /**
+   * Replaces the previous route/view and transitions back to it.
+   */
   replacePreviousAndPop: function(route: Route) {
     // Make sure all previous requests are caught up first. Otherwise reject.
     if (this.state.requestedTopOfStack !== this.state.observedTopOfStack) {
@@ -618,6 +623,9 @@ var NavigatorIOS = React.createClass({
     });
   },
 
+  /**
+   * Replaces the top item and popToTop
+   */
   resetTo: function(route: Route) {
     invariant(!!route, 'Must supply route to push');
     // Make sure all previous requests are caught up first. Otherwise reject.
@@ -628,7 +636,7 @@ var NavigatorIOS = React.createClass({
     this.popToRoute(route);
   },
 
-  handleNavigationComplete: function(e: Event) {
+  _handleNavigationComplete: function(e: Event) {
     if (this._toFocusOnNavigationComplete) {
       this._getFocusEmitter().emit('focus', this._toFocusOnNavigationComplete);
       this._toFocusOnNavigationComplete = null;
@@ -663,7 +671,7 @@ var NavigatorIOS = React.createClass({
     );
   },
 
-  renderNavigationStackItems: function() {
+  _renderNavigationStackItems: function() {
     var shouldRecurseToNavigator =
       this.state.makingNavigatorRequest ||
       this.state.updatingAllIndicesAtOrBeyond !== null;
@@ -678,7 +686,7 @@ var NavigatorIOS = React.createClass({
           style={styles.transitioner}
           vertical={this.props.vertical}
           requestedTopOfStack={this.state.requestedTopOfStack}
-          onNavigationComplete={this.handleNavigationComplete}>
+          onNavigationComplete={this._handleNavigationComplete}>
           {items}
         </NavigatorTransitionerIOS>
       </StaticContainer>
@@ -688,7 +696,7 @@ var NavigatorIOS = React.createClass({
   render: function() {
     return (
       <View style={this.props.style}>
-        {this.renderNavigationStackItems()}
+        {this._renderNavigationStackItems()}
       </View>
     );
   },

diff --git a/Libraries/Components/ScrollView/ScrollView.js b/Libraries/Components/ScrollView/ScrollView.js
@@ -341,6 +341,9 @@ var ScrollView = React.createClass({
     this.refs[SCROLLVIEW].setNativeProps(props);
   },
 
+  /**
+   * Deprecated. Use `RefreshControl` instead.
+   */
   endRefreshing: function() {
     RCTScrollViewManager.endRefreshing(
       ReactNative.findNodeHandle(this)
@@ -367,9 +370,10 @@ var ScrollView = React.createClass({
 
   /**
    * Scrolls to a given x, y offset, either immediately or with a smooth animation.
+   *
    * Syntax:
    *
-   * scrollTo(options: {x: number = 0; y: number = 0; animated: boolean = true})
+   * `scrollTo(options: {x: number = 0; y: number = 0; animated: boolean = true})`
    *
    * Note: The weird argument signature is due to the fact that, for historical reasons,
    * the function also accepts separate arguments as as alternative to the options object.
@@ -397,7 +401,7 @@ var ScrollView = React.createClass({
     this.scrollTo({x, y, animated: false});
   },
 
-  handleScroll: function(e: Object) {
+  _handleScroll: function(e: Object) {
     if (__DEV__) {
       if (this.props.onScroll && !this.props.scrollEventThrottle && Platform.OS === 'ios') {
         console.log(
@@ -480,7 +484,7 @@ var ScrollView = React.createClass({
       onStartShouldSetResponder: this.scrollResponderHandleStartShouldSetResponder,
       onStartShouldSetResponderCapture: this.scrollResponderHandleStartShouldSetResponderCapture,
       onScrollShouldSetResponder: this.scrollResponderHandleScrollShouldSetResponder,
-      onScroll: this.handleScroll,
+      onScroll: this._handleScroll,
       onResponderGrant: this.scrollResponderHandleResponderGrant,
       onResponderTerminationRequest: this.scrollResponderHandleTerminationRequest,
       onResponderTerminate: this.scrollResponderHandleTerminate,

diff --git a/Libraries/Components/StatusBar/StatusBar.js b/Libraries/Components/StatusBar/StatusBar.js
@@ -164,7 +164,7 @@ const StatusBar = React.createClass({
       StatusBarManager.setNetworkActivityIndicatorVisible(visible);
     },
 
-    setBackgroundColor(color, animated?: boolean) {
+    setBackgroundColor(color: string, animated?: boolean) {
       if (Platform.OS !== 'android') {
         console.warn('`setBackgroundColor` is only available on Android');
         return;

diff --git a/Libraries/Components/TextInput/TextInput.js b/Libraries/Components/TextInput/TextInput.js
@@ -319,6 +319,9 @@ var TextInput = React.createClass({
         AndroidTextInput.viewConfig :
         {})) : Object),
 
+  /**
+   * Returns if the input is currently focused.
+   */
   isFocused: function(): boolean {
     return TextInputState.currentlyFocusedField() ===
       ReactNative.findNodeHandle(this.refs.input);
@@ -368,6 +371,9 @@ var TextInput = React.createClass({
     isInAParentText: React.PropTypes.bool
   },
 
+  /**
+   * Removes all text from the input.
+   */
   clear: function() {
     this.setNativeProps({text: ''});
   },

diff --git a/Libraries/Components/Touchable/TouchableHighlight.js b/Libraries/Components/Touchable/TouchableHighlight.js
@@ -94,7 +94,7 @@ var TouchableHighlight = React.createClass({
   getDefaultProps: () => DEFAULT_PROPS,
 
   // Performance optimization to avoid constantly re-generating these objects.
-  computeSyntheticState: function(props) {
+  _computeSyntheticState: function(props) {
     return {
       activeProps: {
         style: {
@@ -115,7 +115,7 @@ var TouchableHighlight = React.createClass({
 
   getInitialState: function() {
     return merge(
-      this.touchableGetInitialState(), this.computeSyntheticState(this.props)
+      this.touchableGetInitialState(), this._computeSyntheticState(this.props)
     );
   },
 
@@ -133,7 +133,7 @@ var TouchableHighlight = React.createClass({
     if (nextProps.activeOpacity !== this.props.activeOpacity ||
         nextProps.underlayColor !== this.props.underlayColor ||
         nextProps.style !== this.props.style) {
-      this.setState(this.computeSyntheticState(nextProps));
+      this.setState(this._computeSyntheticState(nextProps));
     }
   },
 

diff --git a/Libraries/Components/Touchable/TouchableNativeFeedback.android.js b/Libraries/Components/Touchable/TouchableNativeFeedback.android.js
@@ -83,36 +83,39 @@ var TouchableNativeFeedback = React.createClass({
     /**
      * Determines the type of background drawable that's going to be used to
      * display feedback. It takes an object with `type` property and extra data
-     * depending on the `type`. It's recommended to use one of the following
-     * static methods to generate that dictionary:
-     *
-     * 1) TouchableNativeFeedback.SelectableBackground() - will create object
-     * that represents android theme's default background for selectable
-     * elements (?android:attr/selectableItemBackground)
-     *
-     * 2) TouchableNativeFeedback.SelectableBackgroundBorderless() - will create
-     * object that represent android theme's default background for borderless
-     * selectable elements (?android:attr/selectableItemBackgroundBorderless).
-     * Available on android API level 21+
-     *
-     * 3) TouchableNativeFeedback.Ripple(color, borderless) - will create
-     * object that represents ripple drawable with specified color (as a
-     * string). If property `borderless` evaluates to true the ripple will
-     * render outside of the view bounds (see native actionbar buttons as an
-     * example of that behavior). This background type is available on Android
-     * API level 21+
+     * depending on the `type`. It's recommended to use one of the static
+     * methods to generate that dictionary.
      */
     background: backgroundPropType,
   },
 
   statics: {
+    /**
+     * Creates an object that represents android theme's default background for
+     * selectable elements (?android:attr/selectableItemBackground).
+     */
     SelectableBackground: function() {
       return {type: 'ThemeAttrAndroid', attribute: 'selectableItemBackground'};
     },
+    /**
+     * Creates an object that represent android theme's default background for borderless
+     * selectable elements (?android:attr/selectableItemBackgroundBorderless).
+     * Available on android API level 21+.
+     */
     SelectableBackgroundBorderless: function() {
       return {type: 'ThemeAttrAndroid', attribute: 'selectableItemBackgroundBorderless'};
     },
-    Ripple: function(color, borderless) {
+    /**
+     * Creates an object that represents ripple drawable with specified color (as a
+     * string). If property `borderless` evaluates to true the ripple will
+     * render outside of the view bounds (see native actionbar buttons as an
+     * example of that behavior). This background type is available on Android
+     * API level 21+.
+     *
+     * @param color The ripple color
+     * @param borderless If the ripple can render outside it's bounds
+     */
+    Ripple: function(color: string, borderless: boolean) {
       return {type: 'RippleAndroid', color: processColor(color), borderless: borderless};
     },
   },

diff --git a/Libraries/Components/Touchable/TouchableOpacity.js b/Libraries/Components/Touchable/TouchableOpacity.js
@@ -81,7 +81,10 @@ var TouchableOpacity = React.createClass({
     ensurePositiveDelayProps(nextProps);
   },
 
-  setOpacityTo: function(value) {
+  /**
+   * Animate the touchable to a new opacity.
+   */
+  setOpacityTo: function(value: number) {
     Animated.timing(
       this.state.anim,
       {toValue: value, duration: 150}