{"version":3,"file":"DocCommentEnhancer.js","sourceRoot":"","sources":["../../src/enhancers/DocCommentEnhancer.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport * as ts from 'typescript';\nimport * as tsdoc from '@microsoft/tsdoc';\n\nimport type { Collector } from '../collector/Collector';\nimport { AstSymbol } from '../analyzer/AstSymbol';\nimport type { AstDeclaration } from '../analyzer/AstDeclaration';\nimport type { ApiItemMetadata } from '../collector/ApiItemMetadata';\nimport { ReleaseTag } from '@microsoft/api-extractor-model';\nimport { ExtractorMessageId } from '../api/ExtractorMessageId';\nimport { VisitorState } from '../collector/VisitorState';\nimport { ResolverFailure } from '../analyzer/AstReferenceResolver';\n\nexport class DocCommentEnhancer {\n  private readonly _collector: Collector;\n\n  public constructor(collector: Collector) {\n    this._collector = collector;\n  }\n\n  public static analyze(collector: Collector): void {\n    const docCommentEnhancer: DocCommentEnhancer = new DocCommentEnhancer(collector);\n    docCommentEnhancer.analyze();\n  }\n\n  public analyze(): void {\n    for (const entity of this._collector.entities) {\n      if (entity.astEntity instanceof AstSymbol) {\n        if (\n          entity.consumable ||\n          this._collector.extractorConfig.apiReportIncludeForgottenExports ||\n          this._collector.extractorConfig.docModelIncludeForgottenExports\n        ) {\n          entity.astEntity.forEachDeclarationRecursive((astDeclaration: AstDeclaration) => {\n            this._analyzeApiItem(astDeclaration);\n          });\n        }\n      }\n    }\n  }\n\n  private _analyzeApiItem(astDeclaration: AstDeclaration): void {\n    const metadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);\n    if (metadata.docCommentEnhancerVisitorState === VisitorState.Visited) {\n      return;\n    }\n\n    if (metadata.docCommentEnhancerVisitorState === VisitorState.Visiting) {\n      this._collector.messageRouter.addAnalyzerIssue(\n        ExtractorMessageId.CyclicInheritDoc,\n        `The @inheritDoc tag for \"${astDeclaration.astSymbol.localName}\" refers to its own declaration`,\n        astDeclaration\n      );\n      return;\n    }\n    metadata.docCommentEnhancerVisitorState = VisitorState.Visiting;\n\n    if (metadata.tsdocComment && metadata.tsdocComment.inheritDocTag) {\n      this._applyInheritDoc(astDeclaration, metadata.tsdocComment, metadata.tsdocComment.inheritDocTag);\n    }\n\n    this._analyzeNeedsDocumentation(astDeclaration, metadata);\n\n    this._checkForBrokenLinks(astDeclaration, metadata);\n\n    metadata.docCommentEnhancerVisitorState = VisitorState.Visited;\n  }\n\n  private _analyzeNeedsDocumentation(astDeclaration: AstDeclaration, metadata: ApiItemMetadata): void {\n    if (astDeclaration.declaration.kind === ts.SyntaxKind.Constructor) {\n      // Constructors always do pretty much the same thing, so it's annoying to require people to write\n      // descriptions for them.  Instead, if the constructor lacks a TSDoc summary, then API Extractor\n      // will auto-generate one.\n      metadata.undocumented = false;\n\n      // The class that contains this constructor\n      const classDeclaration: AstDeclaration = astDeclaration.parent!;\n\n      const configuration: tsdoc.TSDocConfiguration = this._collector.extractorConfig.tsdocConfiguration;\n\n      if (!metadata.tsdocComment) {\n        metadata.tsdocComment = new tsdoc.DocComment({ configuration });\n      }\n\n      if (!tsdoc.PlainTextEmitter.hasAnyTextContent(metadata.tsdocComment.summarySection)) {\n        metadata.tsdocComment.summarySection.appendNodesInParagraph([\n          new tsdoc.DocPlainText({ configuration, text: 'Constructs a new instance of the ' }),\n          new tsdoc.DocCodeSpan({\n            configuration,\n            code: classDeclaration.astSymbol.localName\n          }),\n          new tsdoc.DocPlainText({ configuration, text: ' class' })\n        ]);\n      }\n\n      const apiItemMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);\n      if (apiItemMetadata.effectiveReleaseTag === ReleaseTag.Internal) {\n        // If the constructor is marked as internal, then add a boilerplate notice for the containing class\n        const classMetadata: ApiItemMetadata = this._collector.fetchApiItemMetadata(classDeclaration);\n\n        if (!classMetadata.tsdocComment) {\n          classMetadata.tsdocComment = new tsdoc.DocComment({ configuration });\n        }\n\n        if (classMetadata.tsdocComment.remarksBlock === undefined) {\n          classMetadata.tsdocComment.remarksBlock = new tsdoc.DocBlock({\n            configuration,\n            blockTag: new tsdoc.DocBlockTag({\n              configuration,\n              tagName: tsdoc.StandardTags.remarks.tagName\n            })\n          });\n        }\n\n        classMetadata.tsdocComment.remarksBlock.content.appendNode(\n          new tsdoc.DocParagraph({ configuration }, [\n            new tsdoc.DocPlainText({\n              configuration,\n              text:\n                `The constructor for this class is marked as internal. Third-party code should not` +\n                ` call the constructor directly or create subclasses that extend the `\n            }),\n            new tsdoc.DocCodeSpan({\n              configuration,\n              code: classDeclaration.astSymbol.localName\n            }),\n            new tsdoc.DocPlainText({ configuration, text: ' class.' })\n          ])\n        );\n      }\n      return;\n    }\n\n    if (metadata.tsdocComment) {\n      // Require the summary to contain at least 10 non-spacing characters\n      metadata.undocumented = !tsdoc.PlainTextEmitter.hasAnyTextContent(\n        metadata.tsdocComment.summarySection,\n        10\n      );\n    } else {\n      metadata.undocumented = true;\n    }\n  }\n\n  private _checkForBrokenLinks(astDeclaration: AstDeclaration, metadata: ApiItemMetadata): void {\n    if (!metadata.tsdocComment) {\n      return;\n    }\n    this._checkForBrokenLinksRecursive(astDeclaration, metadata.tsdocComment);\n  }\n\n  private _checkForBrokenLinksRecursive(astDeclaration: AstDeclaration, node: tsdoc.DocNode): void {\n    if (node instanceof tsdoc.DocLinkTag) {\n      if (node.codeDestination) {\n        // Is it referring to the working package?  If not, we don't do any link validation, because\n        // AstReferenceResolver doesn't support it yet (but ModelReferenceResolver does of course).\n        // Tracked by:  https://github.com/microsoft/rushstack/issues/1195\n        if (\n          node.codeDestination.packageName === undefined ||\n          node.codeDestination.packageName === this._collector.workingPackage.name\n        ) {\n          const referencedAstDeclaration: AstDeclaration | ResolverFailure =\n            this._collector.astReferenceResolver.resolve(node.codeDestination);\n\n          if (referencedAstDeclaration instanceof ResolverFailure) {\n            this._collector.messageRouter.addAnalyzerIssue(\n              ExtractorMessageId.UnresolvedLink,\n              'The @link reference could not be resolved: ' + referencedAstDeclaration.reason,\n              astDeclaration\n            );\n          }\n        }\n      }\n    }\n    for (const childNode of node.getChildNodes()) {\n      this._checkForBrokenLinksRecursive(astDeclaration, childNode);\n    }\n  }\n\n  /**\n   * Follow an `{@inheritDoc ___}` reference and copy the content that we find in the referenced comment.\n   */\n  private _applyInheritDoc(\n    astDeclaration: AstDeclaration,\n    docComment: tsdoc.DocComment,\n    inheritDocTag: tsdoc.DocInheritDocTag\n  ): void {\n    if (!inheritDocTag.declarationReference) {\n      this._collector.messageRouter.addAnalyzerIssue(\n        ExtractorMessageId.UnresolvedInheritDocBase,\n        'The @inheritDoc tag needs a TSDoc declaration reference; signature matching is not supported yet',\n        astDeclaration\n      );\n      return;\n    }\n\n    // Is it referring to the working package?\n    if (\n      !(\n        inheritDocTag.declarationReference.packageName === undefined ||\n        inheritDocTag.declarationReference.packageName === this._collector.workingPackage.name\n      )\n    ) {\n      // It's referencing an external package, so skip this inheritDoc tag, since AstReferenceResolver doesn't\n      // support it yet.  As a workaround, this tag will get handled later by api-documenter.\n      // Tracked by:  https://github.com/microsoft/rushstack/issues/1195\n      return;\n    }\n\n    const referencedAstDeclaration: AstDeclaration | ResolverFailure =\n      this._collector.astReferenceResolver.resolve(inheritDocTag.declarationReference);\n\n    if (referencedAstDeclaration instanceof ResolverFailure) {\n      this._collector.messageRouter.addAnalyzerIssue(\n        ExtractorMessageId.UnresolvedInheritDocReference,\n        'The @inheritDoc reference could not be resolved: ' + referencedAstDeclaration.reason,\n        astDeclaration\n      );\n      return;\n    }\n\n    this._analyzeApiItem(referencedAstDeclaration);\n\n    const referencedMetadata: ApiItemMetadata =\n      this._collector.fetchApiItemMetadata(referencedAstDeclaration);\n\n    if (referencedMetadata.tsdocComment) {\n      this._copyInheritedDocs(docComment, referencedMetadata.tsdocComment);\n    }\n  }\n\n  /**\n   * Copy the content from `sourceDocComment` to `targetDocComment`.\n   */\n  private _copyInheritedDocs(targetDocComment: tsdoc.DocComment, sourceDocComment: tsdoc.DocComment): void {\n    targetDocComment.summarySection = sourceDocComment.summarySection;\n    targetDocComment.remarksBlock = sourceDocComment.remarksBlock;\n\n    targetDocComment.params.clear();\n    for (const param of sourceDocComment.params) {\n      targetDocComment.params.add(param);\n    }\n    for (const typeParam of sourceDocComment.typeParams) {\n      targetDocComment.typeParams.add(typeParam);\n    }\n    targetDocComment.returnsBlock = sourceDocComment.returnsBlock;\n\n    targetDocComment.inheritDocTag = undefined;\n  }\n}\n"]}