1 line
16 KiB
Plaintext
1 line
16 KiB
Plaintext
{"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"]} |