Add a deprecatedPropType module to show deprecation warnings

Summary:
To allow smoother API changes for users we often deprecate props and keep them around for a while before removing them. Right now it is all done manually, this adds a consistent way to show a warning when using a deprecated prop.

This also adds a deprecation warning of the website generated from the deprecatedPropType.

<img width="643" alt="screen shot 2016-01-26 at 7 43 08 pm" src="https://cloud.githubusercontent.com/assets/2677334/12600172/7af28fb0-c465-11e5-85e5-3786852bf522.png">

It also changes places where we added the warnings manually to use deprecatedPropType instead.
Closes https://github.com/facebook/react-native/pull/5566

Reviewed By: svcscm

Differential Revision: D2874629

Pulled By: nicklockwood

fb-gh-sync-id: c3c63bae7bbec26cc146029abd9aa5efbe73f795

website/layout/AutodocsLayout.js

@@ -119,6 +119,15 @@ var ComponentDoc = React.createClass({
             {renderType(prop.type)}
           </span>}
         </Header>
+        {prop.deprecationMessage && <div className="deprecated">
+          <div className="deprecatedTitle">
+            <img className="deprecatedIcon" src="/react-native/img/Warning.png" />
+            <span>Deprecated</span>
+          </div>
+          <div className="deprecatedMessage">
+            <Marked>{prop.deprecationMessage}</Marked>
+          </div>
+        </div>}
         {prop.type && prop.type.name === 'stylesheet' &&
           this.renderStylesheetProps(prop.type.value)}
         {prop.description && <Marked>{prop.description}</Marked>}

website/server/docgenHelpers.js

@@ -6,6 +6,7 @@ function stylePropTypeHandler(documentation, path) {
   if (!propTypesPath) {
     return;
   }
+
   propTypesPath = docgen.utils.resolveToValue(propTypesPath);
   if (!propTypesPath || propTypesPath.node.type !== 'ObjectExpression') {
     return;
@@ -34,6 +35,43 @@ function stylePropTypeHandler(documentation, path) {
   });
 }
 
+function deprecatedPropTypeHandler(documentation, path) {
+  var propTypesPath = docgen.utils.getMemberValuePath(path, 'propTypes');
+  if (!propTypesPath) {
+    return;
+  }
+
+  propTypesPath = docgen.utils.resolveToValue(propTypesPath);
+  if (!propTypesPath || propTypesPath.node.type !== 'ObjectExpression') {
+    return;
+  }
+
+  // Checks for deprecatedPropType function and add deprecation info.
+  propTypesPath.get('properties').each(function(propertyPath) {
+    var valuePath = docgen.utils.resolveToValue(propertyPath.get('value'));
+    // If it's a call to deprecatedPropType, do stuff
+    if (valuePath.node.type !== 'CallExpression' ||
+        valuePath.node.callee.name !== 'deprecatedPropType') {
+      return;
+    }
+    var propDescriptor = documentation.getPropDescriptor(
+      docgen.utils.getPropertyName(propertyPath)
+    );
+    // The 2nd argument of deprecatedPropType is the deprecation message.
+    // Used printValue to get the string otherwise there was issues with template
+    // strings.
+    propDescriptor.deprecationMessage = docgen.utils
+      .printValue(valuePath.get('arguments', 1))
+      // Remove the quotes printValue adds.
+      .slice(1, -1);
+
+    // Get the actual prop type.
+    propDescriptor.type = docgen.utils.getPropType(
+      valuePath.get('arguments', 0)
+    );
+  });
+}
+
 function findExportedOrFirst(node, recast) {
   return docgen.resolver.findExportedComponentDefinition(node, recast) ||
     docgen.resolver.findAllComponentDefinitions(node, recast)[0];
@@ -86,5 +124,6 @@ function findExportedObject(ast, recast) {
 }
 
 exports.stylePropTypeHandler = stylePropTypeHandler;
+exports.deprecatedPropTypeHandler = deprecatedPropTypeHandler;
 exports.findExportedOrFirst = findExportedOrFirst;
 exports.findExportedObject = findExportedObject;

website/server/extractDocs.js

@@ -149,7 +149,10 @@ function renderComponent(filepath) {
   var json = docgen.parse(
     fs.readFileSync(filepath),
     docgenHelpers.findExportedOrFirst,
-    docgen.defaultHandlers.concat(docgenHelpers.stylePropTypeHandler)
+    docgen.defaultHandlers.concat([
+      docgenHelpers.stylePropTypeHandler,
+      docgenHelpers.deprecatedPropTypeHandler,
+    ])
   );
 
   return componentsToMarkdown('component', json, filepath, n++, styleDocs);

website/src/react-native/css/react-native.css

@@ -1096,6 +1096,28 @@ div[data-twttr-id] iframe {
   border: 1px solid rgba(0, 0, 0, 0.2);
 }
 
+.deprecated {
+  margin-bottom: 24px;
+}
+
+.deprecatedTitle {
+  margin-bottom: 6px;
+  line-height: 18px;
+  font-weight: bold;
+  color: #ffa500;
+}
+
+.deprecatedIcon {
+  width: 18px;
+  height: 18px;
+  margin-right: 8px;
+  vertical-align: top;
+}
+
+.deprecatedMessage {
+  margin-left: 26px;
+}
+
 .edit-github {
   font-size: 15px;
   font-weight: normal;