chore(api-builder): add configurable link disambuators & put to work

closes #1852
Add configurable link disambuators
Add a service to disambiguate docs by module
Add a service to disambiguate docs that are deprecated

Author: petebacondarwin

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

@@ -10,11 +10,18 @@ module.exports = new Package('links', [])
 .factory(require('dgeni-packages/links/services/getDocFromAlias'))
 .factory(require('./services/getLinkInfo'))
 .factory(require('./services/parseArgString'))
+.factory(require('./services/moduleScopeLinkDisambiguator'))
+.factory(require('./services/deprecatedDocsLinkDisambiguator'))
 .factory(require('./services/getApiFragmentFileName'))
 
 .config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) {
   inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
   inlineTagProcessor.inlineTagDefinitions.push(linkDocsInlineTagDef);
   inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef);
   inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef);
+})
+
+.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;
+  };
+};

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

@@ -10,10 +10,17 @@ var path = require('canonical-path');
  * @return {Object}       The link information
  *
  * @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc
+ * @property {array<function(url, title, currentDoc, ambiguousDocs) : array} disambiguators a collection of functions
+ *           that attempt to resolve ambiguous links. Each disambiguator returns a new collection of docs with
+ *           unwanted ambiguous docs removed (see moduleScopeLinkDisambiguator service for an example).
  */
 module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
 
-  return function getLinkInfoImpl(url, title, currentDoc) {
+  getLinkInfoImpl.disambiguators = [];
+
+  return getLinkInfoImpl;
+
+  function getLinkInfoImpl(url, title, currentDoc) {
     var linkInfo = {
       url: url,
       type: 'url',
@@ -27,6 +34,11 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
 
     var docs = getDocFromAlias(url, currentDoc);
 
+    // Give each disambiguator a chance to reduce the number of ambiguous docs
+    docs = getLinkInfoImpl.disambiguators.reduce(function(docs, disambiguator) {
+      return disambiguator(url, title, currentDoc, docs);
+    }, docs);
+
     if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 ) {
 
       linkInfo.valid = false;
@@ -68,4 +80,5 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
 
     return linkInfo;
   };
+
 };

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

@@ -0,0 +1,15 @@
+var _ = require('lodash');
+
+module.exports = function moduleScopeLinkDisambiguator() {
+  return function(url, title, currentDoc, docs) {
+    if (docs.length > 1) {
+      // filter out target docs that are not in the same module as the source doc
+      var filteredDocs = _.filter(docs, function(doc) {
+        return doc.moduleDoc === currentDoc.moduleDoc;
+      });
+      // if all target docs are in a different module then just return the full collection of ambiguous docs
+      return filteredDocs.length > 0 ? filteredDocs : docs;
+    }
+    return docs;
+  };
+};