Improve autogen for reference docs including jsdoc support

Summary:
As part of improving the API and Component reference docs facebook#8154 this pull request adds the following:

- jsdoc support for API docs. See the AlertIOS changes as an example.
- type definitions support and added to both API and Component docs. This is supported via react-docgen and jsdoc.
- better formatting of method properties (now shown in a table).

FYI, API and Component docs were previously generated in two different ways. Components were using react-docgen and that basically remains as-is. APIs were using custom parsing code and that's been switched to use a jsdoc parser + react-docgen as an option for typedefs (it could also use the jsdoc parser).

Two docs have been updated to showcase how we'd like the new docs to look:

- AlertIOS (API): showing method parameters, examples, typedefs, more details overall.
- Statusbar (Component): showing method parameters, typedefs, more details overall.

**Note**: To convert new API docs to use the new format, add `jsdoc` to the initial file comment. C
Closes facebook#8196

Differential Revision: D3465037

Pulled By: lacker

fbshipit-source-id: 78415d44bc5be02db802f5b1f7a0b249689abdf7

Author: Christine Abernathy

Libraries/Components/StatusBar/StatusBar.js

@@ -19,14 +19,35 @@ const processColor = require('processColor');
 
 const StatusBarManager = require('NativeModules').StatusBarManager;
 
+/**
+ * Status bar style
+ */
 export type StatusBarStyle = $Enum<{
+  /**
+   * Default status bar style
+   */
   'default': string,
+  /**
+   * Dark background style
+   */
   'light-content': string,
 }>;
 
+/**
+ * Status bar animation
+ */
 export type StatusBarAnimation = $Enum<{
+  /**
+   * No animation
+   */
   'none': string,
+  /**
+   * Fade animation
+   */
   'fade': string,
+  /**
+   * Slide animation
+   */
   'slide': string,
 }>;
 
@@ -135,6 +156,13 @@ const StatusBar = React.createClass({
 
     // Provide an imperative API as static functions of the component.
     // See the corresponding prop for more detail.
+
+    /**
+     * Show or hide the status bar
+     * @param hidden The dialog's title.
+     * @param animation Optional animation when
+     *    changing the status bar hidden property.
+     */
     setHidden(hidden: boolean, animation?: StatusBarAnimation) {
       animation = animation || 'none';
       StatusBar._defaultProps.hidden.value = hidden;
@@ -145,6 +173,11 @@ const StatusBar = React.createClass({
       }
     },
 
+    /**
+     * Set the status bar style
+     * @param style Status bar style to set
+     * @param animated Animate the style change.
+     */
     setBarStyle(style: StatusBarStyle, animated?: boolean) {
       if (Platform.OS !== 'ios') {
         console.warn('`setBarStyle` is only available on iOS');
@@ -155,6 +188,10 @@ const StatusBar = React.createClass({
       StatusBarManager.setStyle(style, animated);
     },
 
+    /**
+     * Control the visibility of the network activity indicator
+     * @param visible Show the indicator.
+     */
     setNetworkActivityIndicatorVisible(visible: boolean) {
       if (Platform.OS !== 'ios') {
         console.warn('`setNetworkActivityIndicatorVisible` is only available on iOS');
@@ -164,6 +201,11 @@ const StatusBar = React.createClass({
       StatusBarManager.setNetworkActivityIndicatorVisible(visible);
     },
 
+    /**
+     * Set the background color for the status bar
+     * @param color Background color.
+     * @param animated Animate the style change.
+     */
     setBackgroundColor(color: string, animated?: boolean) {
       if (Platform.OS !== 'android') {
         console.warn('`setBackgroundColor` is only available on Android');
@@ -174,6 +216,10 @@ const StatusBar = React.createClass({
       StatusBarManager.setColor(processColor(color), animated);
     },
 
+    /**
+     * Control the translucency of the status bar
+     * @param translucent Set as translucent.
+     */
     setTranslucent(translucent: boolean) {
       if (Platform.OS !== 'android') {
         console.warn('`setTranslucent` is only available on Android');

Libraries/Utilities/AlertIOS.js

@@ -8,64 +8,129 @@
  *
  * @providesModule AlertIOS
  * @flow
+ * @jsdoc
  */
 'use strict';
 
 var RCTAlertManager = require('NativeModules').AlertManager;
 
+/**
+ * An Alert button type
+ */
 export type AlertType = $Enum<{
+  /**
+   * Default alert with no inputs
+   */
   'default': string;
+  /**
+   * Plain text input alert
+   */
   'plain-text': string;
+  /**
+   * Secure text input alert
+   */
   'secure-text': string;
+  /**
+   * Login and password alert
+   */
   'login-password': string;
 }>;
 
+/**
+ * An Alert button style
+ */
 export type AlertButtonStyle = $Enum<{
+  /**
+   * Default button style
+   */
   'default': string;
+  /**
+   * Cancel button style
+   */
   'cancel': string;
+  /**
+   * Destructive button style
+   */
   'destructive': string;
 }>;
 
+/**
+ * Array or buttons
+ * @typedef {Array} ButtonsArray
+ * @property {string=} text Button label
+ * @property {Function=} onPress Callback function when button pressed
+ * @property {AlertButtonStyle=} style Button style
+ */
 type ButtonsArray = Array<{
+  /**
+   * Button label
+   */
   text?: string;
+  /**
+   * Callback function when button pressed
+   */
   onPress?: ?Function;
+  /**
+   * Button style
+   */
   style?: AlertButtonStyle;
 }>;
 
 /**
- * The AlertsIOS utility provides two functions: `alert` and `prompt`. All
- * functionality available through `AlertIOS.alert` is also available in the
- * cross-platform `Alert.alert`, which we recommend you use if you don't need
- * iOS-specific functionality.
+ * @description
+ * `AlertIOS` provides functionality to create an iOS alert dialog with a
+ * message or create a prompt for user input.
+ *
+ * Creating an iOS alert:
  *
- * `AlertIOS.prompt` allows you to prompt the user for input inside of an
- * alert popup.
+ * ```
+ * AlertIOS.alert(
+ *  'Sync Complete',
+ *  'All your data are belong to us.'
+ * );
+ * ```
+ *
+ * Creating an iOS prompt:
+ *
+ * ```
+ * AlertIOS.prompt(
+ *   'Enter a value',
+ *   null,
+ *   text => console.log("You entered "+text)
+ * );
+ * ```
+ *
+ * We recommend using the [`Alert.alert`](/docs/alert.html) method for
+ * cross-platform support if you don't need to create iOS-only prompts.
  *
  */
 class AlertIOS {
   /**
-   * Creates a popup to alert the user. See
-   * [Alert](docs/alert.html).
-   *
-   *  - title: string -- The dialog's title.
-   *  - message: string -- An optional message that appears above the text input.
-   *  - callbackOrButtons -- This optional argument should be either a
-   *    single-argument function or an array of buttons. If passed a function,
-   *    it will be called when the user taps 'OK'.
+   * Create and display a popup alert.
+   * @static
+   * @method alert
+   * @param title The dialog's title.
+   * @param message An optional message that appears below
+   *     the dialog's title.
+   * @param callbackOrButtons This optional argument should
+   *    be either a single-argument function or an array of buttons. If passed
+   *    a function, it will be called when the user taps 'OK'.
    *
    *    If passed an array of button configurations, each button should include
-   *    a `text` key, as well as optional `onPress` and `style` keys.
-   *    `style` should be one of 'default', 'cancel' or 'destructive'.
-   *  - type -- *deprecated, do not use*
+   *    a `text` key, as well as optional `onPress` and `style` keys. `style`
+   *    should be one of 'default', 'cancel' or 'destructive'.
+   * @param type Deprecated, do not use.
    *
-   * Example:
+   * @example <caption>Example with custom buttons</caption>
    *
-   * ```
    * AlertIOS.alert(
-   *  'Sync Complete',
-   *  'All your data are belong to us.'
+   *  'Update available',
+   *  'Keep your app up to date to enjoy the latest features',
+   *  [
+   *    {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
+   *    {text: 'Install', onPress: () => console.log('Install Pressed')},
+   *  ],
    * );
-   * ```
    */
   static alert(
     title: ?string,
@@ -82,23 +147,26 @@ class AlertIOS {
   }
 
   /**
-   * Prompt the user to enter some text.
-   *
-   *  - title: string -- The dialog's title.
-   *  - message: string -- An optional message that appears above the text input.
-   *  - callbackOrButtons -- This optional argument should be either a
-   *    single-argument function or an array of buttons. If passed a function,
-   *    it will be called with the prompt's value when the user taps 'OK'.
+   * Create and display a prompt to enter some text.
+   * @static
+   * @method prompt
+   * @param title The dialog's title.
+   * @param message An optional message that appears above the text
+   *    input.
+   * @param callbackOrButtons This optional argument should
+   *    be either a single-argument function or an array of buttons. If passed
+   *    a function, it will be called with the prompt's value when the user
+   *    taps 'OK'.
    *
    *    If passed an array of button configurations, each button should include
-   *    a `text` key, as well as optional `onPress` and `style` keys (see example).
-   *    `style` should be one of 'default', 'cancel' or 'destructive'.
-   *  - type: string -- This configures the text input. One of 'plain-text',
+   *    a `text` key, as well as optional `onPress` and `style` keys (see
+   *    example). `style` should be one of 'default', 'cancel' or 'destructive'.
+   * @param type This configures the text input. One of 'plain-text',
    *    'secure-text' or 'login-password'.
-   *  - defaultValue: string -- the default value for the text field.
+   * @param defaultValue The dialog's title.
+   *
+   * @example <caption>Example with custom buttons</caption>
    *
-   * Example with custom buttons:
-   * ```
    * AlertIOS.prompt(
    *   'Enter password',
    *   'Enter your password to claim your $1.5B in lottery winnings',
@@ -108,18 +176,16 @@ class AlertIOS {
    *   ],
    *   'secure-text'
    * );
-   * ```
    *
-   * Example with the default button and a custom callback:
-   * ```
+   * @example <caption>Example with the default button and a custom callback</caption>
+   *
    * AlertIOS.prompt(
    *   'Update username',
    *   null,
    *   text => console.log("Your username is "+text),
    *   null,
    *   'default'
-   * )
-   * ```
+   * );
    */
   static prompt(
     title: ?string,

website/jsdocs/jsdoc-conf.json

@@ -0,0 +1,15 @@
+{
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
+    },
+    "source": {
+        "includePattern": ".+\\.js(doc)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "plugins": ["./jsdocs/jsdoc-plugin-values"],
+    "templates": {
+        "cleverLinks": true,
+        "monospaceLinks": false
+    }
+}

website/jsdocs/jsdoc-plugin-values.js

@@ -0,0 +1,11 @@
+exports.defineTags = function(dictionary) {
+    dictionary.defineTag('value', {
+        mustHaveValue: true,
+        canHaveType: true,
+        canHaveName: true,
+        onTagged: function(doclet, tag) {
+            if (!doclet.values) { doclet.values = []; }
+            doclet.values.push(tag.value);
+        }
+    });
+};