diff --git a/src/addons/ReactComponentWithPureRenderMixin.js b/src/addons/ReactComponentWithPureRenderMixin.js index afafbdaa76..cf00d7cb3d 100644 --- a/src/addons/ReactComponentWithPureRenderMixin.js +++ b/src/addons/ReactComponentWithPureRenderMixin.js @@ -36,6 +36,8 @@ var shallowCompare = require('shallowCompare'); * complex data structures this mixin may have false-negatives for deeper * differences. Only mixin to components which have simple props and state, or * use `forceUpdate()` when you know deep data structures have changed. + * + * See https://facebook.github.io/react/docs/pure-render-mixin.html */ var ReactComponentWithPureRenderMixin = { shouldComponentUpdate: function(nextProps, nextState) { diff --git a/src/addons/ReactFragment.js b/src/addons/ReactFragment.js index f16ccf8bc0..5d83e84533 100644 --- a/src/addons/ReactFragment.js +++ b/src/addons/ReactFragment.js @@ -31,8 +31,11 @@ var numericPropertyRegex = /^\d+$/; var warnedAboutNumeric = false; var ReactFragment = { - // Wrap a keyed object in an opaque proxy that warns you if you access any - // of its properties. + /** + * Wrap a keyed object in an opaque proxy that warns you if you access any + * of its properties. + * See https://facebook.github.io/react/docs/create-fragment.html + */ create: function(object) { if (typeof object !== 'object' || !object || Array.isArray(object)) { warning( diff --git a/src/addons/link/LinkedStateMixin.js b/src/addons/link/LinkedStateMixin.js index c45a79faad..3e2ca17604 100644 --- a/src/addons/link/LinkedStateMixin.js +++ b/src/addons/link/LinkedStateMixin.js @@ -16,6 +16,7 @@ var ReactStateSetters = require('ReactStateSetters'); /** * A simple mixin around ReactLink.forState(). + * See https://facebook.github.io/react/docs/two-way-binding-helpers.html */ var LinkedStateMixin = { /** diff --git a/src/addons/link/ReactLink.js b/src/addons/link/ReactLink.js index ea6435c92b..d327b4f8ec 100644 --- a/src/addons/link/ReactLink.js +++ b/src/addons/link/ReactLink.js @@ -37,6 +37,9 @@ var React = require('React'); /** + * Deprecated: An an easy way to express two-way binding with React. + * See https://facebook.github.io/react/docs/two-way-binding-helpers.html + * * @param {*} value current value of the link * @param {function} requestChange callback to request a change */ diff --git a/src/addons/shallowCompare.js b/src/addons/shallowCompare.js index 33e4591ba8..a6b7a1095d 100644 --- a/src/addons/shallowCompare.js +++ b/src/addons/shallowCompare.js @@ -16,6 +16,7 @@ var shallowEqual = require('shallowEqual'); /** * Does a shallow comparison for props and state. * See ReactComponentWithPureRenderMixin + * See also https://facebook.github.io/react/docs/shallow-compare.html */ function shallowCompare(instance, nextProps, nextState) { return ( diff --git a/src/addons/transitions/ReactCSSTransitionGroup.js b/src/addons/transitions/ReactCSSTransitionGroup.js index 4177ec790b..6d61c2884a 100644 --- a/src/addons/transitions/ReactCSSTransitionGroup.js +++ b/src/addons/transitions/ReactCSSTransitionGroup.js @@ -41,6 +41,11 @@ function createTransitionTimeoutPropValidator(transitionType) { }; } +/** + * An easy way to perform CSS transitions and animations when a React component + * enters or leaves the DOM. + * See https://facebook.github.io/react/docs/animation.html#high-level-api-reactcsstransitiongroup + */ var ReactCSSTransitionGroup = React.createClass({ displayName: 'ReactCSSTransitionGroup', diff --git a/src/addons/transitions/ReactTransitionGroup.js b/src/addons/transitions/ReactTransitionGroup.js index 6d6df1a80b..a2c935eeb2 100644 --- a/src/addons/transitions/ReactTransitionGroup.js +++ b/src/addons/transitions/ReactTransitionGroup.js @@ -16,6 +16,11 @@ var ReactTransitionChildMapping = require('ReactTransitionChildMapping'); var emptyFunction = require('emptyFunction'); +/** + * A basis for animatins. When children are declaratively added or removed, + * special lifecycle hooks are called. + * See https://facebook.github.io/react/docs/animation.html#low-level-api-reacttransitiongroup + */ var ReactTransitionGroup = React.createClass({ displayName: 'ReactTransitionGroup', diff --git a/src/addons/update.js b/src/addons/update.js index cc2434e2bd..8704993c11 100644 --- a/src/addons/update.js +++ b/src/addons/update.js @@ -66,6 +66,10 @@ function invariantArrayCase(value, spec, command) { ); } +/** + * Returns a updated shallow copy of an object without mutating the original. + * See https://facebook.github.io/react/docs/update.html for details. + */ function update(value, spec) { invariant( typeof spec === 'object', diff --git a/src/isomorphic/children/ReactChildren.js b/src/isomorphic/children/ReactChildren.js index 417f78aa28..75670dbe36 100644 --- a/src/isomorphic/children/ReactChildren.js +++ b/src/isomorphic/children/ReactChildren.js @@ -55,6 +55,8 @@ function forEachSingleChild(bookKeeping, child, name) { /** * Iterates through children that are typically specified as `props.children`. * + * See https://facebook.github.io/react/docs/top-level-api.html#react.children.foreach + * * The provided forEachFunc(child, index) will be called for each * leaf child. * @@ -146,7 +148,9 @@ function mapIntoWithKeyPrefixInternal(children, array, prefix, func, context) { /** * Maps children that are typically specified as `props.children`. * - * The provided mapFunction(child, index) will be called for each + * See https://facebook.github.io/react/docs/top-level-api.html#react.children.map + * + * The provided mapFunction(child, key, index) will be called for each * leaf child. * * @param {?*} children Children tree container. @@ -173,6 +177,8 @@ function forEachSingleChildDummy(traverseContext, child, name) { * Count the number of children that are typically specified as * `props.children`. * + * See https://facebook.github.io/react/docs/top-level-api.html#react.children.count + * * @param {?*} children Children tree container. * @return {number} The number of children. */ @@ -184,6 +190,8 @@ function countChildren(children, context) { /** * Flatten a children object (typically specified as `props.children`) and * return an array with appropriately re-keyed children. + * + * See https://facebook.github.io/react/docs/top-level-api.html#react.children.toarray */ function toArray(children) { var result = []; diff --git a/src/isomorphic/children/onlyChild.js b/src/isomorphic/children/onlyChild.js index e1d3706c7e..505dea4246 100644 --- a/src/isomorphic/children/onlyChild.js +++ b/src/isomorphic/children/onlyChild.js @@ -16,10 +16,13 @@ var invariant = require('invariant'); /** * Returns the first child in a collection of children and verifies that there - * is only one child in the collection. The current implementation of this - * function assumes that a single child gets passed without a wrapper, but the - * purpose of this helper function is to abstract away the particular structure - * of children. + * is only one child in the collection. + * + * See https://facebook.github.io/react/docs/top-level-api.html#react.children.only + * + * The current implementation of this function assumes that a single child gets + * passed without a wrapper, but the purpose of this helper function is to + * abstract away the particular structure of children. * * @param {?object} children Child collection structure. * @return {ReactElement} The first and only `ReactElement` contained in the diff --git a/src/isomorphic/classic/class/ReactClass.js b/src/isomorphic/classic/class/ReactClass.js index 56f479a42e..fe82510b89 100644 --- a/src/isomorphic/classic/class/ReactClass.js +++ b/src/isomorphic/classic/class/ReactClass.js @@ -740,6 +740,7 @@ var ReactClass = { /** * Creates a composite component class given a class specification. + * See https://facebook.github.io/react/docs/top-level-api.html#react.createclass * * @param {object} spec Class specification (which must define `render`). * @return {function} Component constructor function. diff --git a/src/isomorphic/classic/element/ReactElement.js b/src/isomorphic/classic/element/ReactElement.js index 307bb4d5c8..40c1c7fc29 100644 --- a/src/isomorphic/classic/element/ReactElement.js +++ b/src/isomorphic/classic/element/ReactElement.js @@ -113,6 +113,10 @@ var ReactElement = function(type, key, ref, self, source, owner, props) { return element; }; +/** + * Create and return a new ReactElement of the given type. + * See https://facebook.github.io/react/docs/top-level-api.html#react.createelement + */ ReactElement.createElement = function(type, config, children) { var propName; @@ -230,6 +234,10 @@ ReactElement.createElement = function(type, config, children) { ); }; +/** + * Return a function that produces ReactElements of a given type. + * See https://facebook.github.io/react/docs/top-level-api.html#react.createfactory + */ ReactElement.createFactory = function(type) { var factory = ReactElement.createElement.bind(null, type); // Expose the type on the factory and the prototype so that it can be @@ -255,6 +263,10 @@ ReactElement.cloneAndReplaceKey = function(oldElement, newKey) { return newElement; }; +/** + * Clone and return a new ReactElement using element as the starting point. + * See https://facebook.github.io/react/docs/top-level-api.html#react.cloneelement + */ ReactElement.cloneElement = function(element, config, children) { var propName; @@ -335,6 +347,8 @@ ReactElement.cloneElement = function(element, config, children) { }; /** + * Verifies the object is a ReactElement. + * See https://facebook.github.io/react/docs/top-level-api.html#react.isvalidelement * @param {?object} object * @return {boolean} True if `object` is a valid component. * @final diff --git a/src/renderers/dom/client/ReactMount.js b/src/renderers/dom/client/ReactMount.js index d7c8b3aed5..564edc7e1a 100644 --- a/src/renderers/dom/client/ReactMount.js +++ b/src/renderers/dom/client/ReactMount.js @@ -511,6 +511,7 @@ var ReactMount = { /** * Renders a React component into the DOM in the supplied `container`. + * See https://facebook.github.io/react/docs/top-level-api.html#reactdom.render * * If the React component was previously rendered into `container`, this will * perform an update on it and only mutate the DOM as necessary to reflect the @@ -527,6 +528,7 @@ var ReactMount = { /** * Unmounts and destroys the React component rendered in the `container`. + * See https://facebook.github.io/react/docs/top-level-api.html#reactdom.unmountcomponentatnode * * @param {DOMElement} container DOM element containing a React component. * @return {boolean} True if a component was found in and unmounted from diff --git a/src/renderers/dom/client/findDOMNode.js b/src/renderers/dom/client/findDOMNode.js index 65c8070093..9c2a3b9ea5 100644 --- a/src/renderers/dom/client/findDOMNode.js +++ b/src/renderers/dom/client/findDOMNode.js @@ -22,6 +22,8 @@ var warning = require('warning'); /** * Returns the DOM node rendered by this element. * + * See https://facebook.github.io/react/docs/top-level-api.html#reactdom.finddomnode + * * @param {ReactComponent|DOMElement} componentOrElement * @return {?DOMElement} The root node of this element. */ diff --git a/src/renderers/dom/server/ReactServerRendering.js b/src/renderers/dom/server/ReactServerRendering.js index 2d30f1a18d..73ce86c460 100644 --- a/src/renderers/dom/server/ReactServerRendering.js +++ b/src/renderers/dom/server/ReactServerRendering.js @@ -63,6 +63,11 @@ function renderToStringImpl(element, makeStaticMarkup) { } } +/** + * Render a ReactElement to its initial HTML. This should only be used on the + * server. + * See https://facebook.github.io/react/docs/top-level-api.html#reactdomserver.rendertostring + */ function renderToString(element) { invariant( ReactElement.isValidElement(element), @@ -71,6 +76,11 @@ function renderToString(element) { return renderToStringImpl(element, false); } +/** + * Similar to renderToString, except this doesn't create extra DOM attributes + * such as data-react-id that React uses internally. + * See https://facebook.github.io/react/docs/top-level-api.html#reactdomserver.rendertostaticmarkup + */ function renderToStaticMarkup(element) { invariant( ReactElement.isValidElement(element), diff --git a/src/test/ReactPerf.js b/src/test/ReactPerf.js index 1eb803a4e8..a8e6679311 100644 --- a/src/test/ReactPerf.js +++ b/src/test/ReactPerf.js @@ -14,6 +14,7 @@ /** * ReactPerf is a general AOP system designed to measure performance. This * module only has the hooks: see ReactDefaultPerf for the analysis tool. + * See also https://facebook.github.io/react/docs/perf.html */ var ReactPerf = { /** diff --git a/src/test/ReactTestUtils.js b/src/test/ReactTestUtils.js index 0e6b19150f..9937bf06e7 100644 --- a/src/test/ReactTestUtils.js +++ b/src/test/ReactTestUtils.js @@ -71,6 +71,10 @@ function findAllInRenderedTreeInternal(inst, test) { } /** + * Utilities for making it easy to test React components. + * + * See https://facebook.github.io/react/docs/test-utils.html + * * Todo: Support the entire DOM.scry query syntax. For now, these simple * utilities will suffice for testing purposes. * @lends ReactTestUtils