fix(links): Url for @link is not always right

fix #237
compodoc · Jul 21, 2017 · 6be60bc · 6be60bc
1 parent 128d33a
commit 6be60bc
Show file tree

Hide file tree

Showing 11 changed files with 180 additions and 76 deletions.
diff --git a/dist/index-cli.js b/dist/index-cli.js
diff --git a/dist/index.js b/dist/index.js
diff --git a/src/app/compiler/dependencies.ts b/src/app/compiler/dependencies.ts
@@ -835,7 +835,7 @@ export class Dependencies {
         _return.name = (inArgs.length > 0) ? inArgs[0].text : property.name.text;
         _return.defaultValue = property.initializer ? this.stringifyDefaultValue(property.initializer) : undefined;
         if (property.symbol) {
-            _return.description = marked(LinkParser.resolveLinks(ts.displayPartsToString(property.symbol.getDocumentationComment())))
+            _return.description = marked(ts.displayPartsToString(property.symbol.getDocumentationComment()));
         }
         if (!_return.description) {
             if (property.jsDoc) {
@@ -920,7 +920,7 @@ export class Dependencies {
         _return.name = (inArgs.length > 0) ? inArgs[0].text : property.name.text;
         _return.defaultValue = property.initializer ? this.stringifyDefaultValue(property.initializer) : undefined;
         if (property.symbol) {
-            _return.description = marked(LinkParser.resolveLinks(ts.displayPartsToString(property.symbol.getDocumentationComment())))
+            _return.description = marked(ts.displayPartsToString(property.symbol.getDocumentationComment()))
         }
         if (!_return.description) {
             if (property.jsDoc) {
@@ -1037,7 +1037,7 @@ export class Dependencies {
 
 
         if (method.symbol) {
-            result.description = marked(LinkParser.resolveLinks(ts.displayPartsToString(method.symbol.getDocumentationComment())));
+            result.description = marked(ts.displayPartsToString(method.symbol.getDocumentationComment()));
         }
 
         if (method.modifiers) {
@@ -1072,7 +1072,7 @@ export class Dependencies {
 
     private visitCallDeclaration(method, sourceFile) {
         var result = {
-            description: marked(LinkParser.resolveLinks(ts.displayPartsToString(method.symbol.getDocumentationComment()))),
+            description: marked(ts.displayPartsToString(method.symbol.getDocumentationComment())),
             args: method.parameters ? method.parameters.map((prop) => this.visitArgument(prop)) : [],
             returnType: this.visitType(method.type),
             line: this.getPosition(method, sourceFile).line + 1
@@ -1088,7 +1088,7 @@ export class Dependencies {
 
     private visitIndexDeclaration(method, sourceFile?) {
         return {
-            description: marked(LinkParser.resolveLinks(ts.displayPartsToString(method.symbol.getDocumentationComment()))),
+            description: marked(ts.displayPartsToString(method.symbol.getDocumentationComment())),
             args: method.parameters ? method.parameters.map((prop) => this.visitArgument(prop)) : [],
             returnType: this.visitType(method.type),
             line: this.getPosition(method, sourceFile).line + 1
@@ -1115,7 +1115,7 @@ export class Dependencies {
             jsdoctags = JSDocTagsParser.getJSDocs(method);
 
         if (method.symbol) {
-            result.description = marked(LinkParser.resolveLinks(ts.displayPartsToString(method.symbol.getDocumentationComment())));
+            result.description = marked(ts.displayPartsToString(method.symbol.getDocumentationComment()));
         }
 
         if (method.decorators) {
@@ -1215,7 +1215,7 @@ export class Dependencies {
             jsdoctags = JSDocTagsParser.getJSDocs(property);
 
          if (property.symbol) {
-             result.description = marked(LinkParser.resolveLinks(ts.displayPartsToString(property.symbol.getDocumentationComment())));
+             result.description = marked(ts.displayPartsToString(property.symbol.getDocumentationComment()));
          }
 
          if (property.decorators) {
@@ -1359,7 +1359,7 @@ export class Dependencies {
         var symbol = this.typeChecker.getSymbolAtLocation(classDeclaration.name);
         var description = '';
         if (symbol) {
-            description = marked(LinkParser.resolveLinks(ts.displayPartsToString(symbol.getDocumentationComment())));
+            description = marked(ts.displayPartsToString(symbol.getDocumentationComment()));
         }
         var className = classDeclaration.name.text;
         var directiveInfo;

diff --git a/src/app/engines/html.engine.helpers.ts b/src/app/engines/html.engine.helpers.ts
@@ -147,12 +147,16 @@ export let HtmlEngineHelpers = (function() {
          * Convert {@link MyClass} to [MyClass](http://localhost:8080/classes/MyClass.html)
          */
         Handlebars.registerHelper('parseDescription', function(description, depth) {
-            let tagRegExp = new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i'),
+            let tagRegExpLight = new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i'),
+                tagRegExpFull = new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i'),
+                tagRegExp,
                 matches,
                 previousString,
-                tagInfo = []
+                tagInfo = [];
 
-            var processTheLink = function(string, tagInfo) {
+            tagRegExp = (description.indexOf(']{') !== -1) ? tagRegExpFull : tagRegExpLight;
+
+            var processTheLink = function(string, tagInfo, leadingText) {
                 var leading = extractLeadingText(string, tagInfo.completeTag),
                     split,
                     result,
@@ -169,7 +173,11 @@ export let HtmlEngineHelpers = (function() {
                 }
 
                 if (result) {
-                    if (leading.leadingText !== null) {
+
+                    if (leadingText) {
+                        stringtoReplace = '[' + leadingText + ']' + tagInfo.completeTag;
+                    }
+                    else if (leading.leadingText !== null) {
                         stringtoReplace = '[' + leading.leadingText + ']' + tagInfo.completeTag;
                     } else if (typeof split.linkText !== 'undefined') {
                         stringtoReplace = tagInfo.completeTag;
@@ -208,22 +216,31 @@ export let HtmlEngineHelpers = (function() {
                 }
             }
 
-            function replaceMatch(replacer, tag, match, text) {
+            function replaceMatch(replacer, tag, match, text, linkText?) {
                 var matchedTag = {
                     completeTag: match,
                     tag: tag,
                     text: text
                 };
                 tagInfo.push(matchedTag);
 
-                return replacer(description, matchedTag);
+                if (linkText) {
+                    return replacer(description, matchedTag, linkText);
+                } else {
+                    return replacer(description, matchedTag);
+                }
             }
 
             do {
                 matches = tagRegExp.exec(description);
                 if (matches) {
                     previousString = description;
-                    description = replaceMatch(processTheLink, 'link', matches[0], matches[1]);
+                    if (matches.length === 2) {
+                        description = replaceMatch(processTheLink, 'link', matches[0], matches[1]);
+                    }
+                    if (matches.length === 3) {
+                        description = replaceMatch(processTheLink, 'link', matches[0], matches[2], matches[1]);
+                    }
                 }
             } while (matches && previousString !== description);
 

diff --git a/src/utils/link-parser.ts b/src/utils/link-parser.ts
@@ -1,5 +1,3 @@
-import { $dependenciesEngine } from '../app/engines/dependencies.engine';
-
 export function extractLeadingText(string, completeTag) {
     var tagIndex = string.indexOf(completeTag);
     var leadingText = null;
@@ -49,13 +47,15 @@ export function splitLinkText(text) {
 
 export let LinkParser = (function() {
 
-    var processTheLink = function(string, tagInfo) {
+    var processTheLink = function(string, tagInfo, leadingText) {
         var leading = extractLeadingText(string, tagInfo.completeTag),
-            linkText = leading.leadingText || '',
+            linkText,
             split,
             target,
             stringtoReplace;
 
+        linkText = (leadingText) ? leadingText : (leading.leadingText || '');
+
         split = splitLinkText(tagInfo.text);
         target = split.target;
 
@@ -71,32 +71,47 @@ export let LinkParser = (function() {
 
     /**
      * Convert
-     * {@link http://www.google.com|Google} or {@link https://github.com GitHub} to [Github](https://github.com)
+     * {@link http://www.google.com|Google} or {@link https://github.com GitHub} or [Github]{@link https://github.com} to [Github](https://github.com)
      */
 
     var replaceLinkTag = function(str: string) {
 
-        var tagRegExp = new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i'),
+        // new RegExp('\\[((?:.|\n)+?)]\\{@link\\s+((?:.|\n)+?)\\}', 'i').exec('ee [TO DO]{@link Todo} fo') -> "[TO DO]{@link Todo}", "TO DO", "Todo"
+        // new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i').exec('ee [TODO]{@link Todo} fo') -> "{@link Todo}", "Todo"
+
+        var tagRegExpLight = new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i'),
+            tagRegExpFull = new RegExp('\\{@link\\s+((?:.|\n)+?)\\}', 'i'),
+            tagRegExp,
             matches,
             previousString,
             tagInfo = [];
 
-        function replaceMatch(replacer, tag, match, text) {
+        tagRegExp = (str.indexOf(']{') !== -1) ? tagRegExpFull : tagRegExpLight;
+
+        function replaceMatch(replacer, tag, match, text, linkText?) {
             var matchedTag = {
                 completeTag: match,
                 tag: tag,
                 text: text
             };
             tagInfo.push(matchedTag);
-
-            return replacer(str, matchedTag);
+            if (linkText) {
+                return replacer(str, matchedTag, linkText);
+            } else {
+                return replacer(str, matchedTag);
+            }
         }
 
         do {
             matches = tagRegExp.exec(str);
             if (matches) {
                 previousString = str;
-                str = replaceMatch(processTheLink, 'link', matches[0], matches[1]);
+                if (matches.length === 2) {
+                    str = replaceMatch(processTheLink, 'link', matches[0], matches[1]);
+                }
+                if (matches.length === 3) {
+                    str = replaceMatch(processTheLink, 'link', matches[0], matches[2], matches[1]);
+                }
             }
         } while (matches && previousString !== str);
 

diff --git a/test/src/cli/cli-coverage.spec.ts b/test/src/cli/cli-coverage.spec.ts
@@ -67,7 +67,7 @@ describe('CLI coverage report', () => {
             let ls = shell('node', [
                 '../bin/index-cli.js',
                 '-p', '../test/src/sample-files/tsconfig.simple.json',
-                '--coverageTest', '30',
+                '--coverageTest', '40',
                 '-d', '../' + tmp.name + '/'], { cwd: tmp.name, env });
 
             if (ls.stderr.toString() !== '') {

diff --git a/test/src/cli/cli-generation.spec.ts b/test/src/cli/cli-generation.spec.ts
@@ -81,15 +81,16 @@ describe('CLI simple generation', () => {
          */
 
          it('it should have a link with this syntax {@link BarComponent}', () => {
-             expect(fooComponentFile).to.contain('<a href="../components/BarComponent.html">BarComponent');
+             expect(moduleFile).to.contain('See <a href="../components/BarComponent.html">BarComponent');
          });
 
-         it('it should have a link with this syntax [BarComponent2]{@link BarComponent}', () => {
-             expect(fooComponentFile).to.contain('<a href="../components/BarComponent.html">BarComponent2');
+         it('it should have a link with this syntax [The BarComponent]{@link BarComponent}', () => {
+             const barModuleFile  = read(`${tmp.name}/modules/BarModule.html`);
+             expect(barModuleFile).to.contain('Watch <a href="../components/BarComponent.html">The BarComponent');
          });
 
          it('it should have a link with this syntax {@link BarComponent|BarComponent3}', () => {
-             expect(fooComponentFile).to.contain('<a href="../components/BarComponent.html">BarComponent3');
+             expect(fooComponentFile).to.contain('See <a href="../modules/AppModule.html">APP');
          });
 
 

diff --git a/test/src/cli/cli-watch.spec.ts b/test/src/cli/cli-watch.spec.ts
@@ -62,12 +62,12 @@ describe('CLI watch', () => {
         expect(fooCoverageFile).to.contain('2/6');
     });
 
-    it('it should have updated coverage page', (done) => {
+    /*it('it should have updated coverage page', (done) => {
         setTimeout(() => {
             fooCoverageFile = read(`${tmp.name}/coverage.html`);
             //expect(fooCoverageFile).to.contain('3/6');
             done();
         }, 15000);
-    });
+    });*/
 
 });
diff --git a/test/src/sample-files/app.module.ts b/test/src/sample-files/app.module.ts
@@ -7,6 +7,11 @@ import { FooService } from './foo.service';
 import { BarModule } from './bar.module';
 import { FooModule } from './foo.module';
 
+/**
+ * AppModule description
+ *
+ * See {@link BarComponent}
+ */
 @NgModule({
   declarations: [
     FooDirective,

diff --git a/test/src/sample-files/bar.module.ts b/test/src/sample-files/bar.module.ts
@@ -3,6 +3,11 @@ import { BarDirective } from './bar.directive';
 import { BarComponent } from './bar.component';
 import { BarService } from './bar.service';
 
+/**
+ * BarModule description
+ *
+ * Watch [The BarComponent]{@link BarComponent}
+ */
 @NgModule({
   declarations: [
     BarDirective, BarComponent

diff --git a/test/src/sample-files/foo.component.ts b/test/src/sample-files/foo.component.ts
@@ -1,5 +1,10 @@
 import { Component, Output, EventEmitter, Input } from '@angular/core';
 
+/**
+ * FooComponent description
+ *
+ * See {@link AppModule|APP}
+ */
 @Component({
 	selector: 'app-foo',
 	styles: [`