gistfile1.diff

diff --git a/src/core/React.js b/src/core/React.js
index 2c63e87..0039e4f 100644
--- a/src/core/React.js
+++ b/src/core/React.js
@@ -31,12 +31,38 @@ var ReactDefaultInjection = require('ReactDefaultInjection');
 
 ReactDefaultInjection.inject();
 
+/**
+ * The primary entry point into the React library.
+ *
+ * @class React
+ * @static
+ */
 var React = {
+  /**
+   * Alias to {{#crossLink "ReactDOM"}}{{/crossLink}}.
+   *
+   * @property DOM {object}
+   */
   DOM: ReactDOM,
+
+  /**
+   * Alias to {{#crossLink "ReactPropTypes"}}{{/crossLink}}.
+   *
+   * @property PropTypes {object}
+   */
   PropTypes: ReactPropTypes,
+
+  /**
+   * Enable the handling of touch events in your application. This must be
+   * called before anything else.
+   *
+   * @method initializeTouchEvents
+   * @param shouldUseTouch {bool}
+   */
   initializeTouchEvents: function(shouldUseTouch) {
     ReactMount.useTouchEvents = shouldUseTouch;
   },
+
   autoBind: ReactCompositeComponent.autoBind,
   createClass: ReactCompositeComponent.createClass,
   constructAndRenderComponent: ReactMount.constructAndRenderComponent,
diff --git a/src/core/ReactComponent.js b/src/core/ReactComponent.js
index d8c883b..3f0d208 100644
--- a/src/core/ReactComponent.js
+++ b/src/core/ReactComponent.js
@@ -67,7 +67,7 @@ var ownerHasWarned = {};
  * reordered. All children, that hasn't already been validated, are required to
  * have a "key" property assigned to it.
  *
- * @internal
+ * @private
  * @param {ReactComponent} component Component that requires a key.
  */
 function validateExplicitKey(component) {
@@ -108,7 +108,7 @@ function validateExplicitKey(component) {
  * Ensure that every component either is passed in a static location or, if
  * if it's passed in an array, has an explicit key property defined.
  *
- * @internal
+ * @private
  * @param {*} component Statically passed child of any type.
  * @return {boolean}
  */
@@ -154,6 +154,7 @@ function validateChildKeys(component) {
 var ReactComponent = {
 
   /**
+   * @method isValidComponent
    * @param {?object} object
    * @return {boolean} True if `object` is a valid component.
    * @final
@@ -169,10 +170,11 @@ var ReactComponent = {
   /**
    * Generate a key string that identifies a component within a set.
    *
+   * @method getKey
+   * @private
    * @param {*} component A component that could contain a manual key.
    * @param {number} index Index that is used if a manual key is not provided.
    * @return {string}
-   * @internal
    */
   getKey: function(component, index) {
     if (component && component.props && component.props.key != null) {
@@ -184,7 +186,8 @@ var ReactComponent = {
   },
 
   /**
-   * @internal
+   * @property LifeCycle {object}
+   * @private
    */
   LifeCycle: ComponentLifeCycle,
 
@@ -193,7 +196,8 @@ var ReactComponent = {
    * Injected into the base class because many different subclasses need access
    * to this.
    *
-   * @internal
+   * @property DOMIDOperations {object}
+   * @private
    */
   DOMIDOperations: ReactComponentEnvironment.DOMIDOperations,
 
@@ -202,6 +206,7 @@ var ReactComponent = {
    * browser etc). Example: A browser system caches DOM nodes based on component
    * ID and must remove that cache entry when this instance is unmounted.
    *
+   * @method unmountIDFromEnvironment
    * @private
    */
   unmountIDFromEnvironment: ReactComponentEnvironment.unmountIDFromEnvironment,
@@ -213,6 +218,7 @@ var ReactComponent = {
    * low level `div` and `span` nodes. Other platforms may have different
    * encoding of this "image". This must be injected.
    *
+   * @method mountImageIntoNode
    * @private
    */
   mountImageIntoNode: ReactComponentEnvironment.mountImageIntoNode,
@@ -221,7 +227,7 @@ var ReactComponent = {
    * React references `ReactReconcileTransaction` using this property in order
    * to allow dependency injection.
    *
-   * @internal
+   * @private
    */
   ReactReconcileTransaction:
     ReactComponentEnvironment.ReactReconcileTransaction,
@@ -290,7 +296,7 @@ var ReactComponent = {
      *
      * @param {?object} initialProps
      * @param {*} children
-     * @internal
+     * @private
      */
     construct: function(initialProps, children) {
       this.props = initialProps || {};
@@ -332,7 +338,7 @@ var ReactComponent = {
      * @param {string} rootID DOM ID of the root node.
      * @param {ReactReconcileTransaction} transaction
      * @return {?string} Rendered markup to be inserted into the DOM.
-     * @internal
+     * @private
      */
     mountComponent: function(rootID, transaction) {
       invariant(
@@ -357,7 +363,7 @@ var ReactComponent = {
      * Subclasses that override this method should make sure to invoke
      * `ReactComponent.Mixin.unmountComponent.call(this)`.
      *
-     * @internal
+     * @private
      */
     unmountComponent: function() {
       invariant(
@@ -381,7 +387,7 @@ var ReactComponent = {
      *
      * @param {object} nextProps Next set of properties.
      * @param {ReactReconcileTransaction} transaction
-     * @internal
+     * @private
      */
     receiveProps: function(nextProps, transaction) {
       invariant(
@@ -396,7 +402,7 @@ var ReactComponent = {
      * Call `_performUpdateIfNecessary` within a new transaction.
      *
      * @param {ReactReconcileTransaction} transaction
-     * @internal
+     * @private
      */
     performUpdateIfNecessary: function() {
       var transaction = ReactComponent.ReactReconcileTransaction.getPooled();
@@ -408,7 +414,7 @@ var ReactComponent = {
      * If `_pendingProps` is set, update the component.
      *
      * @param {ReactReconcileTransaction} transaction
-     * @internal
+     * @private
      */
     _performUpdateIfNecessary: function(transaction) {
       if (this._pendingProps == null) {
@@ -425,7 +431,7 @@ var ReactComponent = {
      *
      * @param {ReactReconcileTransaction} transaction
      * @param {object} prevProps
-     * @internal
+     * @private
      */
     updateComponent: function(transaction, prevProps) {
       var props = this.props;
@@ -452,7 +458,7 @@ var ReactComponent = {
      * @param {DOMElement} container DOM element to mount into.
      * @param {boolean} shouldReuseMarkup If true, do not insert markup
      * @final
-     * @internal
+     * @private
      * @see {ReactMount.renderComponent}
      */
     mountComponentIntoNode: function(rootID, container, shouldReuseMarkup) {
@@ -491,7 +497,7 @@ var ReactComponent = {
      * @param {ReactComponent} owner Component to check.
      * @return {boolean} True if `owners` owns this component.
      * @final
-     * @internal
+     * @private
      */
     isOwnedBy: function(owner) {
       return this.props[OWNER] === owner;
@@ -503,7 +509,7 @@ var ReactComponent = {
      * @param {string} ref of a sibling Component.
      * @return {?ReactComponent} the actual sibling Component.
      * @final
-     * @internal
+     * @private
      */
     getSiblingByRef: function(ref) {
       var owner = this.props[OWNER];
diff --git a/src/core/ReactPropTypes.js b/src/core/ReactPropTypes.js
index 5857c8f..25aca20 100644
--- a/src/core/ReactPropTypes.js
+++ b/src/core/ReactPropTypes.js
@@ -25,67 +25,113 @@ var invariant = require('invariant');
  * Collection of methods that allow declaration and validation of props that are
  * supplied to React components. Example usage:
  *
- *   var Props = require('ReactPropTypes');
- *   var MyArticle = React.createClass({
- *     propTypes: {
- *       // An optional string prop named "description".
- *       description: Props.string,
+ *     var Props = require('ReactPropTypes');
+ *     var MyArticle = React.createClass({
+ *       propTypes: {
+ *         // An optional string prop named "description".
+ *         description: Props.string,
  *
- *       // A required enum prop named "category".
- *       category: Props.oneOf(['News','Photos']).isRequired,
+ *         // A required enum prop named "category".
+ *         category: Props.oneOf(['News','Photos']).isRequired,
  *
- *       // A prop named "dialog" that requires an instance of Dialog.
- *       dialog: Props.instanceOf(Dialog).isRequired
- *     },
- *     render: function() { ... }
- *   });
+ *         // A prop named "dialog" that requires an instance of Dialog.
+ *         dialog: Props.instanceOf(Dialog).isRequired
+ *       },
+ *       render: function() { ... }
+ *     });
  *
  * A more formal specification of how these methods are used:
  *
- *   type := array|bool|object|number|string|oneOf([...])|instanceOf(...)
- *   decl := ReactPropTypes.{type}(.isRequired)?
+ *     type := array|bool|object|number|string|oneOf([...])|instanceOf(...)
+ *     decl := ReactPropTypes.{type}(.isRequired)?
  *
  * Each and every declaration produces a function with the same signature. This
  * allows the creation of custom validation functions. For example:
  *
- *   var Props = require('ReactPropTypes');
- *   var MyLink = React.createClass({
- *     propTypes: {
- *       // An optional string or URI prop named "href".
- *       href: function(props, propName, componentName) {
- *         var propValue = props[propName];
- *         invariant(
- *           propValue == null ||
- *           typeof propValue === string ||
- *           propValue instanceof URI,
- *           'Invalid `%s` supplied to `%s`, expected string or URI.',
- *           propName,
- *           componentName
- *         );
- *       }
- *     },
- *     render: function() { ... }
- *   });
+ *     var Props = require('ReactPropTypes');
+ *     var MyLink = React.createClass({
+ *       propTypes: {
+ *         // An optional string or URI prop named "href".
+ *         href: function(props, propName, componentName) {
+ *           var propValue = props[propName];
+ *           invariant(
+ *             propValue == null ||
+ *             typeof propValue === string ||
+ *             propValue instanceof URI,
+ *             'Invalid `%s` supplied to `%s`, expected string or URI.',
+ *             propName,
+ *             componentName
+ *           );
+ *         }
+ *       },
+ *       render: function() { ... }
+ *     });
  *
- * @internal
+ * @class ReactPropTypes
+ * @static
  */
 var Props = {
 
+  /**
+   * @property array
+   */
   array: createPrimitiveTypeChecker('array'),
+
+  /**
+   * @property bool
+   */
   bool: createPrimitiveTypeChecker('boolean'),
+
+  /**
+   * @property func
+   */
   func: createPrimitiveTypeChecker('function'),
+
+  /**
+   * @property number
+   */
   number: createPrimitiveTypeChecker('number'),
+
+  /**
+   * @property object
+   */
   object: createPrimitiveTypeChecker('object'),
+
+  /**
+   * @property string
+   */
   string: createPrimitiveTypeChecker('string'),
 
+  /**
+   * Creates a type checker that ensures the `prop` has one of the values
+   * provided.
+   *
+   * @method oneOf
+   * @param {array} expectedValues
+   */
   oneOf: createEnumTypeChecker,
 
+  /**
+   * Creates a type checker that ensures the `prop` is an instance of the class
+   * provided. Equivalent to writing:
+   *
+   *     invariant(this.props.foo instanceof MyClass)
+   *
+   * @method instanceOf
+   * @param {*} expectedClass
+   */
   instanceOf: createInstanceTypeChecker
 
 };
 
 var ANONYMOUS = '<<anonymous>>';
 
+/**
+ * @method createPrimitiveTypeChecker
+ * @private
+ * @param {string} expectedType String value of type as used with `typeof`
+ * @return {function} A chainable type checker
+ */
 function createPrimitiveTypeChecker(expectedType) {
   function validatePrimitiveType(propValue, propName, componentName) {
     var propType = typeof propValue;
@@ -104,6 +150,12 @@ function createPrimitiveTypeChecker(expectedType) {
   return createChainableTypeChecker(validatePrimitiveType);
 }
 
+/**
+ * @method createEnumTypeChecker
+ * @private
+ * @param {array} expectedValues
+ * @return {function} A chainable type checker
+ */
 function createEnumTypeChecker(expectedValues) {
   var expectedEnum = createObjectFrom(expectedValues);
   function validateEnumType(propValue, propName, componentName) {
@@ -118,6 +170,12 @@ function createEnumTypeChecker(expectedValues) {
   return createChainableTypeChecker(validateEnumType);
 }
 
+/**
+ * @method createInstanceTypeChecker
+ * @private
+ * @param {*} expectedClass
+ * @return {function} A chainable type checker
+ */
 function createInstanceTypeChecker(expectedClass) {
   function validateInstanceType(propValue, propName, componentName) {
     invariant(