chore(api doc gen): reduce false positives

- Don't report ambiguous links for deprecated modules; instead resolve
them by default to their respective modules. E.g., `{@link NgControl}`
will resolve to the type in `@angular/common/src/forms-deprecated` when
referenced from with `forms-deprecated` and to the type in
`@angular/forms` when referenced within `forms`.
- Missing API docs are now reported at log-level 'info' rather than
'warn'.
- Don't warn about issues that are due to bug
angular/dgeni-packages#192.

Author: chalin

tools/api-builder/angular.io-package/index.js

@@ -89,6 +89,14 @@ module.exports = new Package('angular.io', [basePackage, targetPackage, cheatshe
 
 .config(function(getLinkInfo) {
   getLinkInfo.useFirstAmbiguousLink = false;
+  // TODO(chalin): remove once the deprecated angular modules are dropped.
+  getLinkInfo.resolveAmbiguityForDeprecatedModules = true;
+  // TODO(chalin): remove the following once this issue is fixed:
+  // https://github.com/angular/dgeni-packages/issues/192
+  getLinkInfo.isInvalidLinkOk = function (url, doc) {
+    return (url === 'CanActivateAnnotation' || url === 'RouteConfigAnnotation') &&
+      doc && doc.path.includes('router-deprecated');
+  }
 })
 
 

tools/api-builder/docs-package/processors/addNotYetDocumentedProperty.js

@@ -23,8 +23,7 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
         }
 
         if (doc.notYetDocumented) {
-          // TODO: (ericjim) should I remove this?
-          log.warn(createDocMessage("Not yet documented", doc));
+          log.info(createDocMessage("Not yet documented", doc));
         }
       });
 
@@ -35,4 +34,4 @@ module.exports = function addNotYetDocumentedProperty(EXPORT_DOC_TYPES, log, cre
 
 function notYetDocumented(doc) {
   return !doc.noDescription && doc.description.trim().length == 0;
-}
+}

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

@@ -13,6 +13,30 @@ var path = require('canonical-path');
  */
 module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
 
+  var deprecatedModuleName, indexOfDepDoc = -1, indexOfOtherDoc = -1;
+
+  function isAmbiguityOk(docs) {
+    if (docs.length != 2) return false;
+
+    // Tolerate deprecated modules having an ambiguity with its non-deprecated counterpart.
+    docs.forEach(function (doc, index) {
+      var matches = doc.fileInfo.relativePath.match(/\/(\w+)-deprecated\//);
+      if (matches) {
+        deprecatedModuleName = matches[1];
+        indexOfDepDoc = index;
+      } else {
+        indexOfOtherDoc = index;
+      }
+    });
+    return indexOfDepDoc >= 0 &&
+      docs[indexOfOtherDoc].fileInfo.relativePath.match(new RegExp('\/'+deprecatedModuleName+'\/'));
+  }
+
+  // Assumes that isAmbiguityOk(docs) has just been invoked.
+  function ambiguityResolver(docs, url) {
+    return url.indexOf('-deprecated') < 0 ? indexOfOtherDoc : indexOfDepDoc;
+  }
+
   return function getLinkInfoImpl(url, title, currentDoc) {
     var linkInfo = {
       url: url,
@@ -26,8 +50,9 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
     }
 
     var docs = getDocFromAlias(url, currentDoc);
+    var isAmbOk = getLinkInfoImpl.resolveAmbiguityForDeprecatedModules && isAmbiguityOk(docs);
 
-    if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 ) {
+    if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 && !isAmbOk ) {
 
       linkInfo.valid = false;
       linkInfo.errorType = 'ambiguous';
@@ -36,16 +61,17 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
 
     } else if ( docs.length >= 1 ) {
 
-      linkInfo.url = docs[0].path;
-      linkInfo.title = title || encodeCodeBlock(docs[0].name, true);
+      const i = isAmbOk ? ambiguityResolver(docs, url) : 0;
+      linkInfo.url = docs[i].path;
+      linkInfo.title = title || encodeCodeBlock(docs[i].name, true);
       linkInfo.type = 'doc';
 
       if ( getLinkInfoImpl.relativeLinks && currentDoc && currentDoc.path ) {
         var currentFolder = path.dirname(currentDoc.path);
         var docFolder = path.dirname(linkInfo.url);
         var relativeFolder = path.relative(path.join('/', currentFolder), path.join('/', docFolder));
         linkInfo.url = path.join(relativeFolder, path.basename(linkInfo.url));
-        log.debug(currentDoc.path, docs[0].path, linkInfo.url);
+        log.debug(currentDoc.path, docs[i].path, linkInfo.url);
       }
 
     } else if ( url.indexOf('#') > 0 ) {
@@ -56,9 +82,11 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
 
     } else if ( url.indexOf('/') === -1 && url.indexOf('#') !== 0 ) {
 
-      linkInfo.valid = false;
-      linkInfo.errorType = 'missing';
-      linkInfo.error = 'Invalid link (does not match any doc): "' + url + '"';
+      if ( getLinkInfoImpl.isInvalidLinkOk && !getLinkInfoImpl.isInvalidLinkOk(url, currentDoc) ) {
+        linkInfo.valid = false;
+        linkInfo.errorType = 'missing';
+        linkInfo.error = 'Invalid link (does not match any doc): "' + url + '"';
+      }
 
     } else {