some comment docs

src/CSSTransition.js

@@ -7,16 +7,111 @@ import Transition from './Transition';
 import { classNamesShape } from './utils/PropTypes';
 
 const propTypes = {
+  ...Transition.propTypes,
+
+  /**
+   * The animation classNames applied to the component as it enters or exits.
+   * A single name can be provided and it will be suffixed for each stage: e.g.
+   *
+   * `classNames="fade"` applies `fade-enter`, `fade-enter-active`,
+   * `fade-exit`, `fade-exit-active`, `fade-appear`, and `fade-appear-active`.
+   * Each individual classNames can also be specified independently like:
+   *
+   * ```js
+   * classNames={{
+   *  appear: 'my-appear',
+   *  appearActive: 'my-active-appear',
+   *  enter: 'my-enter',
+   *  enterActive: 'my-active-enter',
+   *  exit: 'my-exit',
+   *  exitActive: 'my-active-exit',
+   * }}
+   * ```
+   */
   classNames: classNamesShape,
+
+  /**
+   * A `<Transition>` callback fired immediately after the 'enter' or 'appear' class is
+   * applied.
+   *
+   * @type Function(node: HtmlElement, isAppearing: bool)
+   */
   onEnter: PropTypes.func,
+
+  /**
+   * A `<Transition>` callback fired immediately after the 'enter-active' or
+   * 'appear-active' class is applied.
+   *
+   * @type Function(node: HtmlElement, isAppearing: bool)
+   */
   onEntering: PropTypes.func,
+
+  /**
+   * A `<Transition>` callback fired immediately after the 'enter' or
+   * 'appear' classes are **removed** from the DOM node.
+   *
+   * @type Function(node: HtmlElement, isAppearing: bool)
+   */
   onEntered: PropTypes.func,
 
+
+  /**
+   * A `<Transition>` callback fired immediately after the 'exit'  class is
+   * applied.
+   *
+   * @type Function(node: HtmlElement, isAppearing: bool)
+   */
   onExit: PropTypes.func,
+
+  /**
+   * A `<Transition>` callback fired immediately after the 'exit-active' is
+   * class is applied.
+   *
+   * @type Function(node: HtmlElement, isAppearing: bool)
+   */
   onExiting: PropTypes.func,
+
+  /**
+   * A `<Transition>` callback fired immediately after the 'exit' classes
+   * are **removed** from the DOM node.
+   *
+   * @type Function(node: HtmlElement, isAppearing: bool)
+   */
   onExited: PropTypes.func,
 };
 
+/**
+ * A `Transition` component using CSS transitions and animations.
+ * It's inspired by the excellent [ng-animate](http://www.nganimate.org/) libary.
+ *
+ * `CSSTransition` applies a pair of class names during the `appear`, `enter`,
+ * and `exit` stages of the transition. The first class is applied and then a
+ * second "active" class in order to activate the css animation.
+ *
+ * When the `in` prop is toggled to `true` the Component will get
+ * the `example-enter` CSS class and the `example-enter-active` CSS class
+ * added in the next tick. This is a convention based on the `classNames` prop.
+ *
+ * ```css
+ * .example-enter {
+ *   opacity: 0.01;
+ * }
+ *
+ * .example-enter.example-enter-active {
+ *   opacity: 1;
+ *   transition: opacity 500ms ease-in;
+ * }
+ *
+ * .example-leave {
+ *   opacity: 1;
+ * }
+ *
+ * .example-leave.example-leave-active {
+ *   opacity: 0.01;
+ *   transition: opacity 300ms ease-in;
+ * }
+ * ```
+ */
 class CSSTransition extends React.Component {
   onEnter = (node, appearing) => {
     const { className } = this.getClassNames(appearing ? 'appear' : 'enter')

src/Transition.js

@@ -4,20 +4,17 @@ import ReactDOM from 'react-dom';
 
 import { timeoutsShape } from './utils/PropTypes';
 
-export const UNMOUNTED = 0;
-export const EXITED = 1;
-export const ENTERING = 2;
-export const ENTERED = 3;
-export const EXITING = 4;
+export const UNMOUNTED = 'unmounted';
+export const EXITED = 'exited';
+export const ENTERING = 'entering';
+export const ENTERED = 'entered';
+export const EXITING = 'exiting';
 
 /**
- * The Transition component lets you define and run css transitions with a simple declarative api.
- * It works similar to React's own [CSSTransitionGroup](http://facebook.github.io/react/docs/animation.html#high-level-api-reactcsstransitiongroup)
- * but is specifically optimized for transitioning a single child "in" or "out".
- *
- * You don't even need to use class based css transitions if you don't want to (but it is easiest).
- * The extensive set of lifecycle callbacks means you have control over
- * the transitioning now at each step of the way.
+ * The Transition component lets you describe a transition from one component
+ * state to another _over time_ with a simple declarative api. Most commonly
+ * It's used to animate the mounting and unmounting of Component, but can also
+ * be used to describe in-place transition states as well.
  */
 class Transition extends React.Component {
   static contextTypes = {
@@ -247,12 +244,30 @@ class Transition extends React.Component {
 }
 
 Transition.propTypes = {
+  /**
+   * Generally a React element to animate, all unknown props on Transition are
+   * transfered to the **single** child element.
+   *
+   * For advanced uses a `function` child can be used instead of a React element.
+   * This function is called with the current transition status
+   * ('entering', 'entered', 'exiting', 'exited', 'unmounted'), which can used
+   * to apply context specific props to a component.
+   *
+   * ```js
+   * <Transition timeout={150}>
+   *   {(status) => (
+   *     <MyComponent className={`fade fade-${status}`} />
+   *   )}
+   * </Transition>
+   * ```
+   */
   children: PropTypes.oneOfType([
     PropTypes.func.isRequired,
     PropTypes.element.isRequired,
   ]).isRequired,
+
   /**
-   * Show the component; triggers the enter or exit animation
+   * Show the component; triggers the enter or exit states
    */
   in: PropTypes.bool,
 
@@ -267,20 +282,32 @@ Transition.propTypes = {
   unmountOnExit: PropTypes.bool,
 
   /**
-   * Run the enter animation when the component mounts, if it is initially
-   * shown
+   * Run the enter transition when the component mounts, if it is initially
+   * `in={true}`
    */
   appear: PropTypes.bool,
+
+  /**
+   * Run the enter transition when `in={true}`.
+   */
   enter: PropTypes.bool,
+
+  /**
+   * Run the exit transition when `in={false}`.
+   */
   exit: PropTypes.bool,
 
   /**
-   * A Timeout for the animation, in milliseconds, to ensure that a node doesn't
-   * transition indefinately if the browser transitionEnd events are
-   * canceled or interrupted.
+   * The duration for the transition, in milliseconds.
    *
-   * By default this is set to a high number (5 seconds) as a failsafe. You should consider
-   * setting this to the duration of your animation (or a bit above it).
+   * You may specify a single timeout for all transitions like: `timeout={500}`,
+   * or individually like:
+   * ```js
+   * timeout={{
+   *  enter: 300,
+   *  leave: 500,
+   * }}
+   * ```
    */
   timeout: timeoutsShape,
 
@@ -295,37 +322,41 @@ Transition.propTypes = {
    * }}
    */
   addEndListener: PropTypes.func,
+
   /**
-   * Callback fired before the "entering" classes are applied
+   * Callback fired before the "entering" status is applied.
    */
   onEnter: PropTypes.func,
+
   /**
-   * Callback fired after the "entering" classes are applied
+   * Callback fired after the "entering" status is applied.
    */
   onEntering: PropTypes.func,
+
   /**
-   * Callback fired after the "enter" classes are applied
+   * Callback fired after the "enter" status is applied.
    */
   onEntered: PropTypes.func,
+
   /**
-   * Callback fired before the "exiting" classes are applied
+   * Callback fired before the "exiting" status is applied.
    */
   onExit: PropTypes.func,
+
   /**
-   * Callback fired after the "exiting" classes are applied
+   * Callback fired after the "exiting" status is applied.
    */
   onExiting: PropTypes.func,
+
   /**
-   * Callback fired after the "exited" classes are applied
+   * Callback fired after the "exited" status is applied.
    */
   onExited: PropTypes.func,
 };
 
 // Name the function so it is clearer in the documentation
 function noop() {}
 
-Transition.displayName = 'Transition';
-
 Transition.defaultProps = {
   in: false,
   unmountOnExit: false,