build(aio): compute `{@link ...} titles more effectively

aio/tools/transforms/links-package/services/getLinkInfo.js

@@ -44,7 +44,7 @@ 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);
+      linkInfo.title = title || docs[0].title || docs[0].name && encodeCodeBlock(docs[0].name, true);
       linkInfo.type = 'doc';
 
       if (getLinkInfoImpl.relativeLinks && currentDoc && currentDoc.path) {
@@ -72,6 +72,10 @@ module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
           title || ((url.indexOf('#') === 0) ? url.substring(1) : path.basename(url, '.html'));
     }
 
+    if (linkInfo.title === undefined) {
+      linkInfo.valid = false;
+    }
+
     return linkInfo;
   }
 

aio/tools/transforms/links-package/services/getLinkInfo.spec.js

@@ -0,0 +1,51 @@
+const testPackage = require('../../helpers/test-package');
+const Dgeni = require('dgeni');
+
+let getLinkInfo, aliasMap;
+
+describe('getLinkInfo', () => {
+  beforeEach(function() {
+    var dgeni = new Dgeni([testPackage('links-package', true)]);
+    var injector = dgeni.configureInjector();
+    aliasMap = injector.get('aliasMap');
+    getLinkInfo = injector.get('getLinkInfo');
+  });
+
+  it('should use the title if specified', () => {
+    aliasMap.addDoc({ docType: 'guide', title: 'Browser Support', name: 'browser-support', id: 'guide/browser-support', aliases: ['guide/browser-support', 'browser-support'], path: 'guide/browser-support' });
+    const currentDoc = { };
+    const linkInfo = getLinkInfo('browser-support', '"Browser Support Guide"', currentDoc);
+    expect(linkInfo.title).toBe('"Browser Support Guide"');
+  });
+
+  it('should set the link to invalid if the title is `undefined`', () => {
+    aliasMap.addDoc({ docType: 'guide', id: 'guide/browser-support', aliases: ['guide/browser-support', 'browser-support'], path: 'guide/browser-support' });
+    const currentDoc = { };
+    const linkInfo = getLinkInfo('browser-support', undefined, currentDoc);
+    expect(linkInfo.valid).toBe(false);
+  });
+
+  it('should use the target document title if available and no title is specified', () => {
+    aliasMap.addDoc({ docType: 'guide', title: 'Browser Support', id: 'guide/browser-support', aliases: ['guide/browser-support', 'browser-support'], path: 'guide/browser-support' });
+    const currentDoc = { };
+    const linkInfo = getLinkInfo('browser-support', undefined, currentDoc);
+    expect(linkInfo.valid).toBe(true);
+    expect(linkInfo.title).toEqual('Browser Support');
+  });
+
+  it('should prefer the target doc title over name if available and no title is specified', () => {
+    aliasMap.addDoc({ docType: 'guide', title: 'Browser Support', name: 'browser-support', id: 'guide/browser-support', aliases: ['guide/browser-support', 'browser-support'], path: 'guide/browser-support' });
+    const currentDoc = { };
+    const linkInfo = getLinkInfo('browser-support', undefined, currentDoc);
+    expect(linkInfo.valid).toBe(true);
+    expect(linkInfo.title).toEqual('Browser Support');
+  });
+
+  it('should use the target document name as a code block if available and no title is specified', () => {
+    aliasMap.addDoc({ docType: 'api', name: 'CurrencyPipe', id: 'common/CurrencyPipe', aliases: ['common/CurrencyPipe', 'CurrencyPipe'], path: 'api/common/CurrencyPipe' });
+    const currentDoc = { };
+    const linkInfo = getLinkInfo('CurrencyPipe', undefined, currentDoc);
+    expect(linkInfo.valid).toBe(true);
+    expect(linkInfo.title).toEqual('<code>CurrencyPipe</code>');
+  });
+});