diff --git a/docs/05-reusable-components.md b/docs/05-reusable-components.md
index 5dd0e930..89dfba5d 100644
--- a/docs/05-reusable-components.md
+++ b/docs/05-reusable-components.md
@@ -57,17 +57,19 @@ React.createClass({
       fontSize: React.PropTypes.number
     }),
 
-    // You can chain any of the above with isRequired to make sure a warning is
-    // shown if the prop isn't provided.
+    // You can chain any of the above with `isRequired` to make sure a warning
+    // is shown if the prop isn't provided.
     requiredFunc: React.PropTypes.func.isRequired,
 
     // A value of any data type
     requiredAny: React.PropTypes.any.isRequired,
 
-    // You can also specify a custom validator.
+    // You can also specify a custom validator. It should return an Error
+    // object if the validation fails. Don't `console.warn` or throw, as this
+    // won't work inside `oneOfType`.
     customProp: function(props, propName, componentName) {
       if (!/matchme/.test(props[propName])) {
-        console.warn('Validation failed!');
+        return new Error('Validation failed!');
       }
     }
   },
diff --git a/docs/ref-03-component-specs.md b/docs/ref-03-component-specs.md
index 127b2ebf..53388092 100644
--- a/docs/ref-03-component-specs.md
+++ b/docs/ref-03-component-specs.md
@@ -53,8 +53,6 @@ object propTypes
 
 The `propTypes` object allows you to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html).
 
-<!-- TODO: Document propTypes here directly. -->
-
 
 ### mixins
 
@@ -64,8 +62,6 @@ array mixins
 
 The `mixins` array allows you to use mixins to share behavior among multiple components. For more information about mixins, see [Reusable Components](/react/docs/reusable-components.html).
 
-<!-- TODO: Document mixins here directly. -->
-
 
 ### statics