From c1025c5461d146596b05cc3d1a56bdd717258338 Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Wed, 27 Mar 2019 22:48:13 -0700
Subject: [PATCH 1/8] Reintroduce the generated boilerplate for "The
 constructor for this class is marked as internal. Third-party code should not
 call the constructor directly or create subclasses that extend the ___
 class."

---
 .../src/enhancers/DocCommentEnhancer.ts       | 46 ++++++++++++++++++-
 .../etc/api-documenter-test.api.json          | 41 +----------------
 .../etc/api-documenter-test.api.md            |  1 +
 .../markdown/api-documenter-test.docclass1.md |  2 +
 .../yaml/api-documenter-test/docclass1.yml    | 22 +++------
 .../api-documenter-test/src/DocClass1.ts      |  3 +-
 6 files changed, 56 insertions(+), 59 deletions(-)

diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
index e2fd62ba7a5..c2151a3bb1b 100644
--- a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
+++ b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -8,10 +8,11 @@ import { Collector } from '../collector/Collector';
 import { AstSymbol } from '../analyzer/AstSymbol';
 import { AstDeclaration } from '../analyzer/AstDeclaration';
 import { DeclarationMetadata } from '../collector/DeclarationMetadata';
-import { AedocDefinitions } from '@microsoft/api-extractor-model';
+import { AedocDefinitions, ReleaseTag } from '@microsoft/api-extractor-model';
 import { ExtractorMessageId } from '../api/ExtractorMessageId';
 import { VisitorState } from '../collector/VisitorState';
 import { ResolverFailure } from '../analyzer/AstReferenceResolver';
+import { SymbolMetadata } from '../collector/SymbolMetadata';
 
 export class DocCommentEnhancer {
   private readonly _collector: Collector;
@@ -72,6 +73,9 @@ export class DocCommentEnhancer {
       // will auto-generate one.
       metadata.needsDocumentation = false;
 
+      // The class that contains this constructor
+      const classDeclaration: AstDeclaration = astDeclaration.parent!;
+
       const configuration: tsdoc.TSDocConfiguration = AedocDefinitions.tsdocConfiguration;
 
       if (!metadata.tsdocComment) {
@@ -83,12 +87,50 @@ export class DocCommentEnhancer {
           new tsdoc.DocPlainText({ configuration, text: 'Constructs a new instance of the ' }),
           new tsdoc.DocCodeSpan({
             configuration,
-            code: astDeclaration.astSymbol.parentAstSymbol!.localName
+            code: classDeclaration.astSymbol.localName
           }),
           new tsdoc.DocPlainText({ configuration, text: ' class' })
         ]);
       }
 
+      const symbolMetadata: SymbolMetadata = this._collector.fetchMetadata(astDeclaration.astSymbol);
+
+      if (symbolMetadata.releaseTag === ReleaseTag.Internal) {
+        // If the constructor is marked as internal, then add a boilerplate notice for the containing class
+
+        const classMetadata: DeclarationMetadata = this._collector.fetchMetadata(classDeclaration);
+
+        if (!classMetadata.tsdocComment) {
+          classMetadata.tsdocComment = new tsdoc.DocComment({ configuration });
+        }
+
+        if (classMetadata.tsdocComment.remarksBlock === undefined) {
+          classMetadata.tsdocComment.remarksBlock = new tsdoc.DocBlock({
+            configuration,
+            blockTag: new tsdoc.DocBlockTag({
+              configuration,
+              tagName: tsdoc.StandardTags.remarks.tagName
+            })
+          });
+        }
+
+        classMetadata.tsdocComment.remarksBlock.content.appendNode(
+          new tsdoc.DocParagraph({ configuration}, [
+            new tsdoc.DocPlainText({
+              configuration,
+              text: `The constructor for this class is marked as internal. Third-party code should not`
+                + ` call the constructor directly or create subclasses that extend the `
+            }),
+            new tsdoc.DocCodeSpan({
+              configuration,
+              code: classDeclaration.astSymbol.localName
+            }),
+            new tsdoc.DocPlainText({ configuration, text: ' class.' })
+          ])
+        );
+
+      }
+
     } else if (metadata.tsdocComment) {
       // Require the summary to contain at least 10 non-spacing characters
       metadata.needsDocumentation = !tsdoc.PlainTextEmitter.hasAnyTextContent(
diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.json b/build-tests/api-documenter-test/etc/api-documenter-test.api.json
index 24c3be7e6a6..2c45b983a3e 100644
--- a/build-tests/api-documenter-test/etc/api-documenter-test.api.json
+++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.json
@@ -40,7 +40,7 @@
         {
           "kind": "Class",
           "canonicalReference": "(DocClass1:class)",
-          "docComment": "/**\n * This is an example class.\n *\n * @remarks\n *\n * These are some remarks.\n *\n * @defaultValue\n *\n * a default value for this function\n *\n * @public\n */\n",
+          "docComment": "/**\n * This is an example class.\n *\n * @remarks\n *\n * These are some remarks.\n *\n * The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DocClass1` class.\n *\n * @defaultValue\n *\n * a default value for this function\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -86,45 +86,6 @@
           "releaseTag": "Public",
           "name": "DocClass1",
           "members": [
-            {
-              "kind": "Constructor",
-              "canonicalReference": "(:constructor,instance,0)",
-              "docComment": "/**\n * The class constructor\n */\n",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "constructor("
-                },
-                {
-                  "kind": "Reference",
-                  "text": "name"
-                },
-                {
-                  "kind": "Content",
-                  "text": ": "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string"
-                },
-                {
-                  "kind": "Content",
-                  "text": ");"
-                }
-              ],
-              "isStatic": false,
-              "releaseTag": "Public",
-              "overloadIndex": 0,
-              "parameters": [
-                {
-                  "parameterName": "name",
-                  "parameterTypeTokenRange": {
-                    "startIndex": 3,
-                    "endIndex": 4
-                  }
-                }
-              ]
-            },
             {
               "kind": "Method",
               "canonicalReference": "(deprecatedExample:instance,0)",
diff --git a/build-tests/api-documenter-test/etc/api-documenter-test.api.md b/build-tests/api-documenter-test/etc/api-documenter-test.api.md
index 37831d80e9a..7dd6254a229 100644
--- a/build-tests/api-documenter-test/etc/api-documenter-test.api.md
+++ b/build-tests/api-documenter-test/etc/api-documenter-test.api.md
@@ -13,6 +13,7 @@ export class DocBaseClass {
 
 // @public
 export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInterface2 {
+    // @internal
     constructor(name: string);
     // @deprecated (undocumented)
     deprecatedExample(): void;
diff --git a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md
index 67e54d835b6..55279654179 100644
--- a/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md
+++ b/build-tests/api-documenter-test/etc/markdown/api-documenter-test.docclass1.md
@@ -38,3 +38,5 @@ export declare class DocClass1 extends DocBaseClass implements IDocInterface1, I
 
 These are some remarks.
 
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DocClass1` class.
+
diff --git a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml
index d14911b9bba..8883547a1f0 100644
--- a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml
+++ b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml
@@ -2,7 +2,12 @@
 items:
   - uid: api-documenter-test.DocClass1
     summary: This is an example class.
-    remarks: These are some remarks.
+    remarks: >-
+      These are some remarks.
+
+
+      The constructor for this class is marked as internal. Third-party code should not call the constructor directly or
+      create subclasses that extend the `DocClass1` class.
     name: DocClass1
     fullName: DocClass1
     langs:
@@ -15,7 +20,6 @@ items:
       - api-documenter-test.IDocInterface2
     package: api-documenter-test
     children:
-      - api-documenter-test.DocClass1.(constructor)
       - api-documenter-test.DocClass1.deprecatedExample
       - api-documenter-test.DocClass1.exampleFunction
       - api-documenter-test.DocClass1.exampleFunction_1
@@ -25,20 +29,6 @@ items:
       - api-documenter-test.DocClass1.regularProperty
       - api-documenter-test.DocClass1.sumWithExample
       - api-documenter-test.DocClass1.tableExample
-  - uid: api-documenter-test.DocClass1.(constructor)
-    summary: The class constructor
-    name: (constructor)(name)
-    fullName: (constructor)(name)
-    langs:
-      - typeScript
-    type: constructor
-    syntax:
-      content: 'constructor(name: string);'
-      parameters:
-        - id: name
-          description: ''
-          type:
-            - string
   - uid: api-documenter-test.DocClass1.deprecatedExample
     deprecated:
       content: Use `otherThing()` instead.
diff --git a/build-tests/api-documenter-test/src/DocClass1.ts b/build-tests/api-documenter-test/src/DocClass1.ts
index 5a5ea238585..04203af2575 100644
--- a/build-tests/api-documenter-test/src/DocClass1.ts
+++ b/build-tests/api-documenter-test/src/DocClass1.ts
@@ -98,7 +98,8 @@ export interface IDocInterface4 {
  */
 export class DocClass1 extends DocBaseClass implements IDocInterface1, IDocInterface2 {
   /**
-   * The class constructor
+   * An internal class constructor.
+   * @internal
    */
   public constructor(name: string) {
     super();

From c013670a3d473bb3715b8930c5ed1c1a5ba71e9d Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Wed, 27 Mar 2019 23:20:21 -0700
Subject: [PATCH 2/8] Rather than reporting an error for @inheritDoc tags that
 reference an external package, instead let api-documenter handle them

---
 apps/api-documenter/src/cli/BaseAction.ts     | 69 ++++++++++++++++++-
 .../src/enhancers/DocCommentEnhancer.ts       | 14 +++-
 2 files changed, 79 insertions(+), 4 deletions(-)

diff --git a/apps/api-documenter/src/cli/BaseAction.ts b/apps/api-documenter/src/cli/BaseAction.ts
index c39208cb8ca..2cbe63800b6 100644
--- a/apps/api-documenter/src/cli/BaseAction.ts
+++ b/apps/api-documenter/src/cli/BaseAction.ts
@@ -2,13 +2,20 @@
 // See LICENSE in the project root for license information.
 
 import * as path from 'path';
+import * as tsdoc from '@microsoft/tsdoc';
 
 import {
   CommandLineAction,
   CommandLineStringParameter
 } from '@microsoft/ts-command-line';
 import { FileSystem } from '@microsoft/node-core-library';
-import { ApiModel } from '@microsoft/api-extractor-model';
+import {
+  ApiModel,
+  ApiItem,
+  ApiItemContainerMixin,
+  ApiDocumentedItem,
+  IResolveDeclarationReferenceResult
+} from '@microsoft/api-extractor-model';
 
 export abstract class BaseAction extends CommandLineAction {
   protected inputFolder: string;
@@ -55,6 +62,66 @@ export abstract class BaseAction extends CommandLineAction {
       }
     }
 
+    this._applyInheritDoc(apiModel, apiModel);
+
     return apiModel;
   }
+
+  // TODO: This is a temporary workaround.  The long term plan is for API Extractor's DocCommentEnhancer
+  // to apply all @inheritDoc tags before the .api.json file is written.
+  // See DocCommentEnhancer._applyInheritDoc() for more info.
+  private _applyInheritDoc(apiItem: ApiItem, apiModel: ApiModel): void {
+
+    if (apiItem instanceof ApiDocumentedItem) {
+      if (apiItem.tsdocComment) {
+        const inheritDocTag: tsdoc.DocInheritDocTag | undefined = apiItem.tsdocComment.inheritDocTag;
+
+        if (inheritDocTag && inheritDocTag.declarationReference) {
+          // Attempt to resolve the declaration reference
+          const result: IResolveDeclarationReferenceResult
+            = apiModel.resolveDeclarationReference(inheritDocTag.declarationReference, apiItem);
+
+          if (result.errorMessage) {
+            console.log(`Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: `
+              + result.errorMessage);
+          } else {
+            if (result.resolvedApiItem instanceof ApiDocumentedItem
+              && result.resolvedApiItem.tsdocComment
+              && result.resolvedApiItem !== apiItem) {
+              this._copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);
+            }
+          }
+        }
+
+      }
+    }
+
+    // Recurse members
+    if (ApiItemContainerMixin.isBaseClassOf(apiItem)) {
+      for (const member of apiItem.members) {
+        this._applyInheritDoc(member, apiModel);
+      }
+    }
+  }
+
+  /**
+   * Copy the content from `sourceDocComment` to `targetDocComment`.
+   * This code is borrowed from DocCommentEnhancer as a temporary workaround.
+   */
+  private _copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {
+    targetDocComment.summarySection = sourceDocComment.summarySection;
+    targetDocComment.remarksBlock = sourceDocComment.remarksBlock;
+
+    targetDocComment.params.clear();
+    for (const param of sourceDocComment.params) {
+      targetDocComment.params.add(param);
+    }
+    for (const typeParam of sourceDocComment.typeParams) {
+      targetDocComment.typeParams.add(typeParam);
+    }
+    targetDocComment.returnsBlock = sourceDocComment.returnsBlock;
+
+    targetDocComment.inheritDocTag = undefined;
+  }
+
 }
diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
index c2151a3bb1b..5a47b5a6f73 100644
--- a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
+++ b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -55,7 +55,7 @@ export class DocCommentEnhancer {
     metadata.docCommentEnhancerVisitorState = VisitorState.Visiting;
 
     if (metadata.tsdocComment && metadata.tsdocComment.inheritDocTag) {
-      this._analyzeInheritDoc(astDeclaration, metadata.tsdocComment, metadata.tsdocComment.inheritDocTag);
+      this._applyInheritDoc(astDeclaration, metadata.tsdocComment, metadata.tsdocComment.inheritDocTag);
     }
 
     this._analyzeNeedsDocumentation(astDeclaration, metadata);
@@ -151,7 +151,7 @@ export class DocCommentEnhancer {
     if (node instanceof tsdoc.DocLinkTag) {
       if (node.codeDestination) {
 
-        // Is it referring to the working package?  If so, we don't do any link validation, because
+        // Is it referring to the working package?  If not, we don't do any link validation, because
         // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).
         // TODO: We need to come back and fix this.
         if (node.codeDestination.packageName === undefined
@@ -177,7 +177,7 @@ export class DocCommentEnhancer {
   /**
    * Follow an `{@inheritDoc ___}` reference and copy the content that we find in the referenced comment.
    */
-  private _analyzeInheritDoc(astDeclaration: AstDeclaration, docComment: tsdoc.DocComment,
+  private _applyInheritDoc(astDeclaration: AstDeclaration, docComment: tsdoc.DocComment,
     inheritDocTag: tsdoc.DocInheritDocTag): void {
 
     if (!inheritDocTag.declarationReference) {
@@ -187,6 +187,14 @@ export class DocCommentEnhancer {
       return;
     }
 
+    // Is it referring to the working package?  If not, skip this inheritDoc tag, because
+    // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).
+    // As a workaround, this tag will get handled later by api-documenter.
+    if (inheritDocTag.declarationReference.packageName === undefined
+      || inheritDocTag.declarationReference.packageName === this._collector.workingPackage.name) {
+      return;
+    }
+
     const referencedAstDeclaration: AstDeclaration | ResolverFailure = this._collector.astReferenceResolver
       .resolve(inheritDocTag.declarationReference);
 

From 19389a76ca99f52c58e029b564322737aae3b45e Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Thu, 28 Mar 2019 19:27:37 -0700
Subject: [PATCH 3/8] rush change

---
 .../ae-misc-doc-fixes_2019-03-29-02-27.json           | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-02-27.json

diff --git a/common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-02-27.json b/common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-02-27.json
new file mode 100644
index 00000000000..631f9ebd145
--- /dev/null
+++ b/common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-02-27.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Reintroduce the generated documentation notice for internal constructors",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
\ No newline at end of file

From 6d102a36b2f738aac4fb67667a07faca02fa026f Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Thu, 28 Mar 2019 20:34:45 -0700
Subject: [PATCH 4/8] rush change

---
 .../ae-misc-doc-fixes_2019-03-29-03-33.json           | 11 +++++++++++
 .../ae-misc-doc-fixes_2019-03-29-03-33.json           | 11 +++++++++++
 2 files changed, 22 insertions(+)
 create mode 100644 common/changes/@microsoft/api-documenter/ae-misc-doc-fixes_2019-03-29-03-33.json
 create mode 100644 common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-03-33.json

diff --git a/common/changes/@microsoft/api-documenter/ae-misc-doc-fixes_2019-03-29-03-33.json b/common/changes/@microsoft/api-documenter/ae-misc-doc-fixes_2019-03-29-03-33.json
new file mode 100644
index 00000000000..f038508edd2
--- /dev/null
+++ b/common/changes/@microsoft/api-documenter/ae-misc-doc-fixes_2019-03-29-03-33.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Add limited support for resolving @inheritDoc references to external packages by postprocessing them in api-documenter",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
\ No newline at end of file
diff --git a/common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-03-33.json b/common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-03-33.json
new file mode 100644
index 00000000000..9a99f31db65
--- /dev/null
+++ b/common/changes/@microsoft/api-extractor/ae-misc-doc-fixes_2019-03-29-03-33.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Add limited support for resolving @inheritDoc references to external packages by postprocessing them in api-documenter",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}
\ No newline at end of file

From 40554fe53263a621f4fabe3b728d7420ada69a36 Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 29 Mar 2019 15:55:13 -0700
Subject: [PATCH 5/8] Fix a regression where boolean logic was flipped

---
 .../src/enhancers/DocCommentEnhancer.ts       | 15 ++++----
 .../api-extractor-scenarios.api.json          | 35 +++++++++++++++++++
 .../api-extractor-scenarios.api.md            |  3 ++
 .../test-outputs/docReferences/rollup.d.ts    | 11 ++++++
 .../api-extractor-scenarios.api.json          |  2 +-
 .../test-outputs/docReferences3/rollup.d.ts   |  2 +-
 .../src/docReferences/index.ts                | 13 +++++++
 .../src/docReferences3/index.ts               |  2 +-
 8 files changed, 73 insertions(+), 10 deletions(-)

diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
index 5a47b5a6f73..9351038d352 100644
--- a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
+++ b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -97,7 +97,6 @@ export class DocCommentEnhancer {
 
       if (symbolMetadata.releaseTag === ReleaseTag.Internal) {
         // If the constructor is marked as internal, then add a boilerplate notice for the containing class
-
         const classMetadata: DeclarationMetadata = this._collector.fetchMetadata(classDeclaration);
 
         if (!classMetadata.tsdocComment) {
@@ -153,7 +152,7 @@ export class DocCommentEnhancer {
 
         // Is it referring to the working package?  If not, we don't do any link validation, because
         // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).
-        // TODO: We need to come back and fix this.
+        // Tracked by:  https://github.com/Microsoft/web-build-tools/issues/1195
         if (node.codeDestination.packageName === undefined
           || node.codeDestination.packageName === this._collector.workingPackage.name) {
 
@@ -187,11 +186,13 @@ export class DocCommentEnhancer {
       return;
     }
 
-    // Is it referring to the working package?  If not, skip this inheritDoc tag, because
-    // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).
-    // As a workaround, this tag will get handled later by api-documenter.
-    if (inheritDocTag.declarationReference.packageName === undefined
-      || inheritDocTag.declarationReference.packageName === this._collector.workingPackage.name) {
+    // Is it referring to the working package?
+    if (!(inheritDocTag.declarationReference.packageName === undefined
+      || inheritDocTag.declarationReference.packageName === this._collector.workingPackage.name)) {
+
+      // It's referencing an external package, so skip this inheritDoc tag, since AstReferenceResolver doesn't
+      // support it yet.  As a workaround, this tag will get handled later by api-documenter.
+      // Tracked by:  https://github.com/Microsoft/web-build-tools/issues/1195
       return;
     }
 
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json
index af96540c735..96cb9e4462c 100644
--- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json
+++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.json
@@ -187,6 +187,41 @@
             }
           ]
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "(succeedForNow:0)",
+          "docComment": "/**\n * @privateRemarks\n *\n * succeedForNow() should fail due to a broken link, but it's ignored until we fix this issue: https://github.com/Microsoft/web-build-tools/issues/1195\n * {@inheritDoc nonexistent-package#MyNamespace.MyClass.nonExistentMethod}\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function "
+            },
+            {
+              "kind": "Reference",
+              "text": "succeedForNow"
+            },
+            {
+              "kind": "Content",
+              "text": "(): "
+            },
+            {
+              "kind": "Content",
+              "text": "void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 0,
+          "parameters": [],
+          "name": "succeedForNow"
+        },
         {
           "kind": "Function",
           "canonicalReference": "(testSimple:0)",
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.md
index c7834d1c4d7..31a9c199c48 100644
--- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.md
+++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/api-extractor-scenarios.api.md
@@ -23,6 +23,9 @@ export namespace MyNamespace {
     }
 }
 
+// @public (undocumented)
+export function succeedForNow(): void;
+
 // @public
 export function testSimple(): void;
 
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/rollup.d.ts
index 4fae84a3287..fc19dca7e88 100644
--- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/rollup.d.ts
+++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences/rollup.d.ts
@@ -28,6 +28,17 @@ export declare namespace MyNamespace {
     }
 }
 
+/**
+ * {@inheritDoc nonexistent-package#MyNamespace.MyClass.nonExistentMethod}
+ *
+ * @privateRemarks
+ * succeedForNow() should fail due to a broken link, but it's ignored until we fix this issue:
+ * https://github.com/Microsoft/web-build-tools/issues/1195
+ *
+ * @public
+ */
+export declare function succeedForNow(): void;
+
 /**
  * {@inheritDoc MyNamespace.MyClass.myMethod}
  * @privateRemarks
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json
index 307095e08c6..05b220c2a55 100644
--- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json
+++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/api-extractor-scenarios.api.json
@@ -184,7 +184,7 @@
         {
           "kind": "Function",
           "canonicalReference": "(succeedWithExternalReference:0)",
-          "docComment": "/**\n * NOTE: The broken link checker currently is not able to validate references to external packages. We need to fix that. {@link nonexistent#nonexistent}\n *\n * @public\n */\n",
+          "docComment": "/**\n * NOTE: The broken link checker currently is not able to validate references to external packages. Tracked by: https://github.com/Microsoft/web-build-tools/issues/1195 {@link nonexistent#nonexistent}\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
diff --git a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/rollup.d.ts
index 315e4d26952..e6c0b763bf9 100644
--- a/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/rollup.d.ts
+++ b/build-tests/api-extractor-scenarios/etc/test-outputs/docReferences3/rollup.d.ts
@@ -18,7 +18,7 @@ export declare function failWithAmbiguity(): void;
 
 /**
  * NOTE: The broken link checker currently is not able to validate references to external packages.
- * We need to fix that.
+ * Tracked by:  https://github.com/Microsoft/web-build-tools/issues/1195
  * {@link nonexistent#nonexistent}
  * @public
  */
diff --git a/build-tests/api-extractor-scenarios/src/docReferences/index.ts b/build-tests/api-extractor-scenarios/src/docReferences/index.ts
index 094f9b4d916..341867f8d9e 100644
--- a/build-tests/api-extractor-scenarios/src/docReferences/index.ts
+++ b/build-tests/api-extractor-scenarios/src/docReferences/index.ts
@@ -30,6 +30,19 @@ export namespace MyNamespace {
 export function testSimple(): void {
 }
 
+/**
+ * {@inheritDoc nonexistent-package#MyNamespace.MyClass.nonExistentMethod}
+ *
+ * @privateRemarks
+ * succeedForNow() should fail due to a broken link, but it's ignored until we fix this issue:
+ * https://github.com/Microsoft/web-build-tools/issues/1195
+ *
+ * @public
+ */
+export function succeedForNow(): void {
+}
+
+
 /**
  * {@inheritDoc MyNamespace.MyClass.nonExistentMethod}
  * @public
diff --git a/build-tests/api-extractor-scenarios/src/docReferences3/index.ts b/build-tests/api-extractor-scenarios/src/docReferences3/index.ts
index 74c56db74cb..0433954e962 100644
--- a/build-tests/api-extractor-scenarios/src/docReferences3/index.ts
+++ b/build-tests/api-extractor-scenarios/src/docReferences3/index.ts
@@ -30,7 +30,7 @@ export function succeedWithSelector() {
 
 /**
  * NOTE: The broken link checker currently is not able to validate references to external packages.
- * We need to fix that.
+ * Tracked by:  https://github.com/Microsoft/web-build-tools/issues/1195
  * {@link nonexistent#nonexistent}
  * @public
  */

From 7a1c52d47ecac90d9e5fcf3e0eb90f7cfb371f2d Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 29 Mar 2019 16:04:03 -0700
Subject: [PATCH 6/8] Fix an issue where the ae-missing-release-tag warning
 sometimes printed "undefined" as the symbol name

---
 apps/api-extractor/src/collector/Collector.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/api-extractor/src/collector/Collector.ts b/apps/api-extractor/src/collector/Collector.ts
index eb5b5c3052d..08d30a78ae7 100644
--- a/apps/api-extractor/src/collector/Collector.ts
+++ b/apps/api-extractor/src/collector/Collector.ts
@@ -526,7 +526,7 @@ export class Collector {
 
               this.messageRouter.addAnalyzerIssue(
                 ExtractorMessageId.MissingReleaseTag,
-                `"${entity.nameForEmit}" is exported by the package, but it is missing `
+                `"${entity.astEntity.localName}" is exported by the package, but it is missing `
                 + `a release tag (@alpha, @beta, @public, or @internal)`,
                 astSymbol
               );

From 7a6c2dc8d97134b459da34d51e43f889794c3bae Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 29 Mar 2019 21:36:13 -0700
Subject: [PATCH 7/8] Improve error formatting

---
 apps/api-documenter/src/cli/BaseAction.ts                 | 5 +++--
 apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/api-documenter/src/cli/BaseAction.ts b/apps/api-documenter/src/cli/BaseAction.ts
index 2cbe63800b6..8a5fef78028 100644
--- a/apps/api-documenter/src/cli/BaseAction.ts
+++ b/apps/api-documenter/src/cli/BaseAction.ts
@@ -3,6 +3,7 @@
 
 import * as path from 'path';
 import * as tsdoc from '@microsoft/tsdoc';
+import * as colors from 'colors';
 
 import {
   CommandLineAction,
@@ -82,8 +83,8 @@ export abstract class BaseAction extends CommandLineAction {
             = apiModel.resolveDeclarationReference(inheritDocTag.declarationReference, apiItem);
 
           if (result.errorMessage) {
-            console.log(`Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: `
-              + result.errorMessage);
+            console.log(colors.yellow(`Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: `
+              + result.errorMessage));
           } else {
             if (result.resolvedApiItem instanceof ApiDocumentedItem
               && result.resolvedApiItem.tsdocComment
diff --git a/apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts b/apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts
index f5cd78c5543..005075b50ea 100644
--- a/apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts
+++ b/apps/api-documenter/src/markdown/CustomMarkdownEmitter.ts
@@ -177,11 +177,12 @@ export class CustomMarkdownEmitter extends MarkdownEmitter {
           context.writer.write(encodedLinkText);
           context.writer.write(`](${filename!})`);
         } else {
-          console.log(colors.red('WARNING: Unable to determine link text'));
+          console.log(colors.yellow('WARNING: Unable to determine link text'));
         }
       }
     } else if (result.errorMessage) {
-      console.log(colors.red('WARNING: Unable to resolve reference: ' + result.errorMessage));
+      console.log(colors.yellow(`WARNING: Unable to resolve reference "${docLinkTag.codeDestination!.emitAsTsdoc()}": `
+        + result.errorMessage));
     }
   }
 

From 4a8b0b129105d360e78e9e57ae3ef7eded17d0bc Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Fri, 29 Mar 2019 21:39:43 -0700
Subject: [PATCH 8/8] PR feedback

---
 apps/api-extractor/src/enhancers/DocCommentEnhancer.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
index 9351038d352..79bd774559f 100644
--- a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
+++ b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -114,7 +114,7 @@ export class DocCommentEnhancer {
         }
 
         classMetadata.tsdocComment.remarksBlock.content.appendNode(
-          new tsdoc.DocParagraph({ configuration}, [
+          new tsdoc.DocParagraph({ configuration }, [
             new tsdoc.DocPlainText({
               configuration,
               text: `The constructor for this class is marked as internal. Third-party code should not`