chore(api-builder): add a service to disambiguate docs that are deprecated

Author: petebacondarwin

tools/api-builder/links-package/index.js

@@ -11,6 +11,7 @@ module.exports = new Package('links', [])
 .factory(require('./services/getLinkInfo'))
 .factory(require('./services/parseArgString'))
 .factory(require('./services/moduleScopeLinkDisambiguator'))
+.factory(require('./services/deprecatedDocsLinkDisambiguator'))
 .factory(require('./services/getApiFragmentFileName'))
 
 .config(function(inlineTagProcessor, linkInlineTagDef, linkDevGuideInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) {
@@ -20,6 +21,7 @@ module.exports = new Package('links', [])
   inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef);
 })
 
-.config(function(getLinkInfo, moduleScopeLinkDisambiguator) {
+.config(function(getLinkInfo, moduleScopeLinkDisambiguator, deprecatedDocsLinkDisambiguator) {
   getLinkInfo.disambiguators.push(moduleScopeLinkDisambiguator);
+  getLinkInfo.disambiguators.push(deprecatedDocsLinkDisambiguator);
 });

tools/api-builder/links-package/services/deprecatedDocsLinkDisambiguator.js

@@ -0,0 +1,13 @@
+var _ = require('lodash');
+
+module.exports = function deprecatedDocsLinkDisambiguator() {
+  return function(url, title, currentDoc, docs) {
+    if (docs.length != 2) return docs;
+
+    var filteredDocs = _.filter(docs, function(doc) {
+      return !doc.fileInfo.relativePath.match(/\/(\w+)-deprecated\//);
+    });
+
+    return filteredDocs.length > 0 ? filteredDocs : docs;
+  };
+};