build(aio): improve accuracy of code auto-linking (#22494)

The new version of `dgeni-packages/typescript` no longer strips
out "namespaces" from types, which was part of the problem of
not autolinking correctly to `HttpEventType.Response`.

Another part of the problem was that we did not include `.`
characters when matching potential code blocks for auto-linking,
which precluded properties of enums from being linked.

Finally, members we not being given a `path` property, which is
needed to effectively autolink to them. This is now set in
the `simplifyMemberAnchors` processor.

Closes #21375

PR Close #22494

aio/package.json

@@ -107,7 +107,7 @@
     "cross-spawn": "^5.1.0",
     "css-selector-parser": "^1.3.0",
     "dgeni": "^0.4.7",
-    "dgeni-packages": "^0.24.3",
+    "dgeni-packages": "^0.25.0",
     "entities": "^1.1.1",
     "eslint": "^3.19.0",
     "eslint-plugin-jasmine": "^2.2.0",

aio/tools/transforms/angular-api-package/index.js

@@ -130,6 +130,6 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
     ]);
     convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
     postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
-    autoLinkCode.docTypes = DOCS_TO_CONVERT;
+    autoLinkCode.docTypes = DOCS_TO_CONVERT.concat(['member']);
     autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
   });

aio/tools/transforms/angular-api-package/processors/simplifyMemberAnchors.js

@@ -5,15 +5,21 @@
  */
 module.exports = function simplifyMemberAnchors() {
   return {
-    $runAfter: ['extra-docs-added'],
-    $runBefore: ['computing-paths'],
+    $runAfter: ['paths-computed'],
+    $runBefore: ['rendering-docs'],
     $process: function(docs) {
       return docs.forEach(doc => {
         if (doc.members) {
-          doc.members.forEach(member => member.anchor = computeAnchor(member));
+          doc.members.forEach(member => {
+            member.anchor = computeAnchor(member);
+            member.path = doc.path + '#' + member.anchor;
+          });
         }
         if (doc.statics) {
-          doc.statics.forEach(member => member.anchor = computeAnchor(member));
+          doc.statics.forEach(member => {
+            member.anchor = computeAnchor(member);
+            member.path = doc.path + '#' + member.anchor;
+          });
         }
       });
     }

aio/tools/transforms/angular-api-package/processors/simplifyMemberAnchors.spec.js

@@ -0,0 +1,72 @@
+const testPackage = require('../../helpers/test-package');
+const processorFactory = require('./simplifyMemberAnchors');
+const Dgeni = require('dgeni');
+
+describe('simplifyMemberAnchors processor', () => {
+
+  it('should be available on the injector', () => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    const processor = injector.get('simplifyMemberAnchors');
+    expect(processor.$process).toBeDefined();
+    expect(processor.$runAfter).toEqual(['paths-computed']);
+    expect(processor.$runBefore).toEqual(['rendering-docs']);
+  });
+
+  describe('$process', () => {
+    describe('docs without members', () => {
+      it('should ignore the docs', () => {
+        const processor = processorFactory();
+        const docs = [
+          { id: 'some-doc' },
+          { id: 'some-other' }
+        ];
+        processor.$process(docs);
+        expect(docs).toEqual([
+          { id: 'some-doc' },
+          { id: 'some-other' }
+        ]);
+      });
+    });
+
+    describe('docs with members', () => {
+      it('should compute an anchor for each instance member', () => {
+        const processor = processorFactory();
+        const docs = [
+          { id: 'some-doc', members: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
+        ];
+        processor.$process(docs);
+        expect(docs[0].members.map(member => member.anchor)).toEqual(['foo', 'new', 'call']);
+      });
+
+      it('should compute a path for each instance member', () => {
+        const processor = processorFactory();
+        const docs = [
+          { id: 'some-doc', path: 'a/b/c', members: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
+        ];
+        processor.$process(docs);
+        expect(docs[0].members.map(member => member.path)).toEqual(['a/b/c#foo', 'a/b/c#new', 'a/b/c#call']);
+      });
+    });
+
+    describe('docs with static members', () => {
+      it('should compute an anchor for each static member', () => {
+        const processor = processorFactory();
+        const docs = [
+          { id: 'some-doc', statics: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
+        ];
+        processor.$process(docs);
+        expect(docs[0].statics.map(member => member.anchor)).toEqual(['foo', 'new', 'call']);
+      });
+
+      it('should compute a path for each static member', () => {
+        const processor = processorFactory();
+        const docs = [
+          { id: 'some-doc', path: 'a/b/c', statics: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
+        ];
+        processor.$process(docs);
+        expect(docs[0].statics.map(member => member.path)).toEqual(['a/b/c#foo', 'a/b/c#new', 'a/b/c#call']);
+      });
+    });
+  });
+});

aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js

@@ -45,7 +45,7 @@ module.exports = function autoLinkCode(getDocFromAlias) {
                 parent.children.splice(index, 1, createLinkNode(docs[0], node.value));
               } else {
                 // Parse the text for words that we can convert to links
-                const nodes = textContent(node).split(/([A-Za-z0-9_-]+)/)
+                const nodes = textContent(node).split(/([A-Za-z0-9_.-]+)/)
                   .filter(word => word.length)
                   .map((word, index, words) => {
                     // remove docs that fail the custom filter tests

aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js

@@ -9,7 +9,7 @@ describe('autoLinkCode post-processor', () => {
     const dgeni = new Dgeni([testPackage]);
     const injector = dgeni.configureInjector();
     autoLinkCode = injector.get('autoLinkCode');
-    autoLinkCode.docTypes = ['class', 'pipe', 'function', 'const'];
+    autoLinkCode.docTypes = ['class', 'pipe', 'function', 'const', 'member'];
     aliasMap = injector.get('aliasMap');
     processor = injector.get('postProcessHtml');
     processor.docTypes = ['test-doc'];
@@ -31,6 +31,13 @@ describe('autoLinkCode post-processor', () => {
     expect(doc.renderedContent).toEqual('<code><a href="a/b/myclass" class="code-anchor">foo.MyClass</a></code>');
   });
 
+  it('should match code items within a block of code that contain a dot in their identifier', () => {
+    aliasMap.addDoc({ docType: 'member', id: 'MyEnum.Value', aliases: ['Value', 'MyEnum.Value'], path: 'a/b/myenum' });
+    const doc = { docType: 'test-doc', renderedContent: '<code>someFn(): MyEnum.Value</code>' };
+    processor.$process([doc]);
+    expect(doc.renderedContent).toEqual('<code>someFn(): <a href="a/b/myenum" class="code-anchor">MyEnum.Value</a></code>');
+  });
+
   it('should ignore code items that do not match a link to an API doc', () => {
     aliasMap.addDoc({ docType: 'guide', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' });
     const doc = { docType: 'test-doc', renderedContent: '<code>MyClass</code>' };

aio/yarn.lock

@@ -2312,9 +2312,9 @@ devtools-timeline-model@1.1.6:
     chrome-devtools-frontend "1.0.401423"
     resolve "1.1.7"
 
-dgeni-packages@^0.24.3:
-  version "0.24.3"
-  resolved "https://registry.yarnpkg.com/dgeni-packages/-/dgeni-packages-0.24.3.tgz#153ce2bf9d71a70cd8c71171c7f49adf0d725ab9"
+dgeni-packages@^0.25.0:
+  version "0.25.0"
+  resolved "https://registry.yarnpkg.com/dgeni-packages/-/dgeni-packages-0.25.0.tgz#380f0b569ae36d82959252604b729e85e0cd7d4a"
   dependencies:
     canonical-path "0.0.2"
     catharsis "^0.8.1"