Use documentation comments from inherited properties when @inheritdoc is present

sjbarag · sjbarag · commit df96aba72c1b · 2017-09-27T11:53:36.000-07:00
The JSDoc `@ineheritDoc` [tag](http://usejsdoc.org/tags-inheritdoc.html) "indicates that a symbol should inherit its documentation from its parent class". In the case of a TypeScript file, this also includes implemented interfaces and parent interfaces. With this change, a class method or property (or an interface property) with the `@inheritDoc` tag in its JSDoc comment will automatically use the comments from its nearest ancestor that has no `@inheritDoc` tag. To prevent breaking backwards compatibility, `Symbol.getDocumentationComment` now accepts an optional `TypeChecker` instance to support this feature. fixes #8912
diff --git a/src/compiler/parser.ts b/src/compiler/parser.ts
@@ -6372,6 +6372,9 @@ namespace ts {
                             case "constructor":
                                 tag = parseClassTag(atToken, tagName);
                                 break;
+                            case "inheritDoc":
+                                tag = parseInheritDocTag(atToken, tagName);
+                                break;
                             case "arg":
                             case "argument":
                             case "param":
@@ -6603,6 +6606,13 @@ namespace ts {
                     return finishNode(result);
                 }
 
+                function parseInheritDocTag(atToken: AtToken, tagName: Identifier): JSDocInheritDocTag {
+                    const tag = <JSDocInheritDocTag>createNode(SyntaxKind.JSDocInheritDocTag, atToken.pos);
+                    tag.atToken = atToken;
+                    tag.tagName = tagName;
+                    return finishNode(tag);
+                }
+
                 function parseAugmentsTag(atToken: AtToken, tagName: Identifier): JSDocAugmentsTag {
                     const typeExpression = parseJSDocTypeExpression(/*requireBraces*/ true);
 
diff --git a/src/compiler/types.ts b/src/compiler/types.ts
@@ -372,6 +372,7 @@ namespace ts {
         JSDocTypedefTag,
         JSDocPropertyTag,
         JSDocTypeLiteral,
+        JSDocInheritDocTag,
 
         // Synthesized list
         SyntaxList,
@@ -413,9 +414,9 @@ namespace ts {
         LastBinaryOperator = CaretEqualsToken,
         FirstNode = QualifiedName,
         FirstJSDocNode = JSDocTypeExpression,
-        LastJSDocNode = JSDocTypeLiteral,
+        LastJSDocNode = JSDocInheritDocTag,
         FirstJSDocTagNode = JSDocTag,
-        LastJSDocTagNode = JSDocTypeLiteral
+        LastJSDocTagNode = JSDocInheritDocTag
     }
 
     export const enum NodeFlags {
@@ -2168,6 +2169,10 @@ namespace ts {
         kind: SyntaxKind.JSDocClassTag;
     }
 
+    export interface JSDocInheritDocTag extends JSDocTag {
+        kind: SyntaxKind.JSDocInheritDocTag;
+    }
+
     export interface JSDocTemplateTag extends JSDocTag {
         kind: SyntaxKind.JSDocTemplateTag;
         typeParameters: NodeArray<TypeParameterDeclaration>;
diff --git a/src/services/jsDoc.ts b/src/services/jsDoc.ts
@@ -19,6 +19,7 @@ namespace ts.JsDoc {
         "fileOverview",
         "function",
         "ignore",
+        "inheritDoc",
         "inner",
         "lends",
         "link",
@@ -70,7 +71,7 @@ namespace ts.JsDoc {
         const tags: JSDocTagInfo[] = [];
         forEachUnique(declarations, declaration => {
             for (const tag of getJSDocTags(declaration)) {
-                if (tag.kind === SyntaxKind.JSDocTag) {
+                if (tag.kind === SyntaxKind.JSDocTag || tag.kind === SyntaxKind.JSDocInheritDocTag) {
                     tags.push({ name: tag.tagName.text, text: tag.comment });
                 }
             }
diff --git a/src/services/services.ts b/src/services/services.ts
@@ -342,9 +342,19 @@ namespace ts {
             return this.declarations;
         }
 
-        getDocumentationComment(): SymbolDisplayPart[] {
+        getDocumentationComment(typeChecker?: TypeChecker): SymbolDisplayPart[] {
             if (this.documentationComment === undefined) {
                 this.documentationComment = JsDoc.getJsDocCommentsFromDeclarations(this.declarations);
+
+                if (this.documentationComment.length === 0 && hasJSDocInheritDocTag(this) && typeChecker) {
+                    for (const declaration of this.getDeclarations()) {
+                        const inheritedDocs = findInheritedJSDocComments(declaration, this.getName(), typeChecker);
+                        if (inheritedDocs.length > 0) {
+                            this.documentationComment = inheritedDocs;
+                            break;
+                        }
+                    }
+                }
             }
 
             return this.documentationComment;
@@ -471,9 +481,13 @@ namespace ts {
             return this.checker.getReturnTypeOfSignature(this);
         }
 
-        getDocumentationComment(): SymbolDisplayPart[] {
+        getDocumentationComment(typeChecker?: TypeChecker): SymbolDisplayPart[] {
             if (this.documentationComment === undefined) {
                 this.documentationComment = this.declaration ? JsDoc.getJsDocCommentsFromDeclarations([this.declaration]) : [];
+
+                if (this.declaration && this.documentationComment.length === 0 && hasJSDocInheritDocTag(this) && typeChecker) {
+                    this.documentationComment = findInheritedJSDocComments(this.declaration, this.declaration.symbol.getName(), typeChecker);
+                }
             }
 
             return this.documentationComment;
@@ -488,6 +502,63 @@ namespace ts {
         }
     }
 
+    /**
+     * Returns whether or not the given symbol or signature has a JSDoc "inheritDoc" tag on it.
+     * @param symbol the Symbol or Signature in question.
+     * @returns `true` if `symbol` has a JSDoc "inheritDoc" tag on it, otherwise `false`.
+     */
+    function hasJSDocInheritDocTag(symbol: Signature | Symbol) {
+        return !!find(symbol.getJsDocTags(), tag => tag.name === "inheritDoc");
+    }
+
+    /**
+     * Attempts to find JSDoc comments for possibly-inherited properties.  Checks superclasses then traverses
+     * implemented interfaces until a symbol is found with the same name and with documentation.
+     * @param declaration The possibly-inherited declaration to find comments for.
+     * @param propertyName The name of the possibly-inherited property.
+     * @param typeChecker A TypeChecker, used to find inherited properties.
+     * @returns A filled array of documentation comments if any were found, otherwise an empty array.
+     */
+    function findInheritedJSDocComments(declaration: Declaration, propertyName: string, typeChecker: TypeChecker): SymbolDisplayPart[] {
+        let documentationComment: SymbolDisplayPart[] = [];
+
+        if (isClassDeclaration(declaration.parent) || isInterfaceDeclaration(declaration.parent)) {
+            const container: ClassDeclaration | InterfaceDeclaration = declaration.parent;
+            const baseTypeNode = getClassExtendsHeritageClauseElement(container);
+
+            if (baseTypeNode) {
+                const baseType = typeChecker.getTypeAtLocation(baseTypeNode);
+
+                // First check superclasses for a property of the same name
+                let baseProperty = typeChecker.getPropertyOfType(baseType, propertyName);
+                let baseDocs = baseProperty ? baseProperty.getDocumentationComment(typeChecker) : [];
+                if (baseDocs.length > 0) {
+                    documentationComment = baseDocs;
+                }
+
+                // If there's nothing in the superclass, walk through implemented interfaces left-to-right
+                if (documentationComment.length === 0) {
+                    const implementedInterfaces = map(
+                        getClassImplementsHeritageClauseElements(container as ClassLikeDeclaration),
+                        interfaceNode => typeChecker.getTypeAtLocation(interfaceNode)
+                    );
+
+                    for (const implementedInterface of implementedInterfaces) {
+                        // Use the docs from the first implemented interface to have this property and documentation
+                        baseProperty = typeChecker.getPropertyOfType(implementedInterface, propertyName);
+                        baseDocs = baseProperty ? baseProperty.getDocumentationComment(typeChecker) : [];
+                        if (baseDocs.length > 0) {
+                            documentationComment = baseDocs;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
+        return documentationComment;
+    }
+
     class SourceFileObject extends NodeObject implements SourceFile {
         public kind: SyntaxKind.SourceFile;
         public _declarationBrand: any;
@@ -1423,7 +1494,7 @@ namespace ts {
                                 kindModifiers: ScriptElementKindModifier.none,
                                 textSpan: createTextSpan(node.getStart(), node.getWidth()),
                                 displayParts: typeToDisplayParts(typeChecker, type, getContainerNode(node)),
-                                documentation: type.symbol ? type.symbol.getDocumentationComment() : undefined,
+                                documentation: type.symbol ? type.symbol.getDocumentationComment(typeChecker) : undefined,
                                 tags: type.symbol ? type.symbol.getJsDocTags() : undefined
                             };
                         }
diff --git a/src/services/signatureHelp.ts b/src/services/signatureHelp.ts
@@ -400,7 +400,7 @@ namespace ts.SignatureHelp {
                 suffixDisplayParts,
                 separatorDisplayParts: [punctuationPart(SyntaxKind.CommaToken), spacePart()],
                 parameters: signatureHelpParameters,
-                documentation: candidateSignature.getDocumentationComment(),
+                documentation: candidateSignature.getDocumentationComment(typeChecker),
                 tags: candidateSignature.getJsDocTags()
             };
         });
@@ -420,7 +420,7 @@ namespace ts.SignatureHelp {
 
             return {
                 name: parameter.name,
-                documentation: parameter.getDocumentationComment(),
+                documentation: parameter.getDocumentationComment(typeChecker),
                 displayParts,
                 isOptional: typeChecker.isOptionalParameter(<ParameterDeclaration>parameter.valueDeclaration)
             };
@@ -438,4 +438,4 @@ namespace ts.SignatureHelp {
             };
         }
     }
-}
+}
diff --git a/src/services/symbolDisplay.ts b/src/services/symbolDisplay.ts
@@ -429,7 +429,7 @@ namespace ts.SymbolDisplay {
         }
 
         if (!documentation) {
-            documentation = symbol.getDocumentationComment();
+            documentation = symbol.getDocumentationComment(typeChecker);
             tags = symbol.getJsDocTags();
             if (documentation.length === 0 && symbolFlags & SymbolFlags.Property) {
                 // For some special property access expressions like `exports.foo = foo` or `module.exports.foo = foo`
@@ -446,7 +446,7 @@ namespace ts.SymbolDisplay {
                             continue;
                         }
 
-                        documentation = rhsSymbol.getDocumentationComment();
+                        documentation = rhsSymbol.getDocumentationComment(typeChecker);
                         tags = rhsSymbol.getJsDocTags();
                         if (documentation.length > 0) {
                             break;
@@ -513,7 +513,7 @@ namespace ts.SymbolDisplay {
                 displayParts.push(textPart(allSignatures.length === 2 ? "overload" : "overloads"));
                 displayParts.push(punctuationPart(SyntaxKind.CloseParenToken));
             }
-            documentation = signature.getDocumentationComment();
+            documentation = signature.getDocumentationComment(typeChecker);
             tags = signature.getJsDocTags();
         }
 
diff --git a/src/services/types.ts b/src/services/types.ts
@@ -32,7 +32,7 @@ namespace ts {
         getEscapedName(): __String;
         getName(): string;
         getDeclarations(): Declaration[] | undefined;
-        getDocumentationComment(): SymbolDisplayPart[];
+        getDocumentationComment(typeChecker?: TypeChecker): SymbolDisplayPart[];
         getJsDocTags(): JSDocTagInfo[];
     }
 
@@ -55,7 +55,7 @@ namespace ts {
         getTypeParameters(): TypeParameter[] | undefined;
         getParameters(): Symbol[];
         getReturnType(): Type;
-        getDocumentationComment(): SymbolDisplayPart[];
+        getDocumentationComment(typeChecker?: TypeChecker): SymbolDisplayPart[];
         getJsDocTags(): JSDocTagInfo[];
     }
 
diff --git a/tests/baselines/reference/inheritDoc.baseline b/tests/baselines/reference/inheritDoc.baseline
diff --git a/tests/cases/fourslash/jsDocInheritDoc.ts b/tests/cases/fourslash/jsDocInheritDoc.ts
diff --git a/tests/cases/fourslash/jsDocTags.ts b/tests/cases/fourslash/jsDocTags.ts

Original file line number	Diff line number	Diff line change
`@@ -429,7 +429,7 @@ namespace ts.SymbolDisplay {`
`429`	`429`	`}`
`430`	`430`
`431`	`431`	`if (!documentation) {`
`432`		`- documentation = symbol.getDocumentationComment();`
	`432`	`+ documentation = symbol.getDocumentationComment(typeChecker);`
`433`	`433`	`tags = symbol.getJsDocTags();`
`434`	`434`	`if (documentation.length === 0 && symbolFlags & SymbolFlags.Property) {`
`435`	`435`	// For some special property access expressions like `exports.foo = foo` or `module.exports.foo = foo`
`@@ -446,7 +446,7 @@ namespace ts.SymbolDisplay {`
`446`	`446`	`continue;`
`447`	`447`	`}`
`448`	`448`
`449`		`- documentation = rhsSymbol.getDocumentationComment();`
	`449`	`+ documentation = rhsSymbol.getDocumentationComment(typeChecker);`
`450`	`450`	`tags = rhsSymbol.getJsDocTags();`
`451`	`451`	`if (documentation.length > 0) {`
`452`	`452`	`break;`
`@@ -513,7 +513,7 @@ namespace ts.SymbolDisplay {`
`513`	`513`	`displayParts.push(textPart(allSignatures.length === 2 ? "overload" : "overloads"));`
`514`	`514`	`displayParts.push(punctuationPart(SyntaxKind.CloseParenToken));`
`515`	`515`	`}`
`516`		`- documentation = signature.getDocumentationComment();`
	`516`	`+ documentation = signature.getDocumentationComment(typeChecker);`
`517`	`517`	`tags = signature.getJsDocTags();`
`518`	`518`	`}`
`519`	`519`