| 1 | {"version":3,"file":"PackageDocComment.js","sourceRoot":"","sources":["../../src/aedoc/PackageDocComment.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;;;;;;;;;;;;;;;;;;;;;;;;AAE3D,+CAAiC;AAIjC,MAAa,iBAAiB;IAC5B;;OAEG;IACI,MAAM,CAAC,mBAAmB,CAC/B,UAAyB,EACzB,SAAoB;QAEpB,oFAAoF;QACpF,mFAAmF;QACnF,6BAA6B;QAC7B,EAAE;QACF,sFAAsF;QACtF,uFAAuF;QACvF,+DAA+D;QAC/D,EAAE;QACF,kGAAkG;QAClG,wFAAwF;QACxF,8FAA8F;QAC9F,eAAe;QACf,IAAI,mBAAmB,GAA6B,SAAS,CAAC,CAAC,eAAe;QAE9E,KAAK,MAAM,YAAY,IAAI,EAAE,CAAC,uBAAuB,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE;YACvG,IAAI,YAAY,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,sBAAsB,EAAE;gBAC9D,MAAM,WAAW,GAAW,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;gBAE1F,uCAAuC;gBACvC,IAAI,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE;oBAClC,oEAAoE;oBACpE,wDAAwD;oBACxD,IAAI,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE;wBAC/C,mBAAmB,GAAG,YAAY,CAAC;qBACpC;oBACD,MAAM;iBACP;aACF;SACF;QAED,IAAI,CAAC,mBAAmB,EAAE;YACxB,uFAAuF;YACvF,8FAA8F;YAC9F,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,UAAU,EAAE;gBAC7C,MAAM,MAAM,GAAsB,EAAE,CAAC;gBACrC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,uBAAuB,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC9F,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,wBAAwB,CAAC,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;gBAEzF,KAAK,MAAM,YAAY,IAAI,MAAM,EAAE;oBACjC,MAAM,WAAW,GAAW,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC;oBAE1F,IAAI,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE;wBAC/C,SAAS,CAAC,aAAa,CAAC,2BAA2B,uDAEjD,qFAAqF,EACrF,UAAU,EACV,YAAY,CAAC,GAAG,CACjB,CAAC;wBACF,MAAM;qBACP;iBACF;aACF;SACF;QAED,OAAO,mBAAmB,CAAC;IAC7B,CAAC;CACF;AAhED,8CAgEC","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 { Collector } from '../collector/Collector';\nimport { ExtractorMessageId } from '../api/ExtractorMessageId';\n\nexport class PackageDocComment {\n /**\n * For the given source file, see if it starts with a TSDoc comment containing the `@packageDocumentation` tag.\n */\n public static tryFindInSourceFile(\n sourceFile: ts.SourceFile,\n collector: Collector\n ): ts.TextRange | undefined {\n // The @packageDocumentation comment is special because it is not attached to an AST\n // definition. Instead, it is part of the \"trivia\" tokens that the compiler treats\n // as irrelevant white space.\n //\n // WARNING: If the comment doesn't precede an export statement, the compiler will omit\n // it from the *.d.ts file, and API Extractor won't find it. If this happens, you need\n // to rearrange your statements to ensure it is passed through.\n //\n // This implementation assumes that the \"@packageDocumentation\" will be in the first TSDoc comment\n // that appears in the entry point *.d.ts file. We could possibly look in other places,\n // but the above warning suggests enforcing a standardized layout. This design choice is open\n // to feedback.\n let packageCommentRange: ts.TextRange | undefined = undefined; // empty string\n\n for (const commentRange of ts.getLeadingCommentRanges(sourceFile.text, sourceFile.getFullStart()) || []) {\n if (commentRange.kind === ts.SyntaxKind.MultiLineCommentTrivia) {\n const commentBody: string = sourceFile.text.substring(commentRange.pos, commentRange.end);\n\n // Choose the first JSDoc-style comment\n if (/^\\s*\\/\\*\\*/.test(commentBody)) {\n // But only if it looks like it's trying to be @packageDocumentation\n // (The TSDoc parser will validate this more rigorously)\n if (/\\@packageDocumentation/i.test(commentBody)) {\n packageCommentRange = commentRange;\n }\n break;\n }\n }\n }\n\n if (!packageCommentRange) {\n // If we didn't find the @packageDocumentation tag in the expected place, is it in some\n // wrong place? This sanity check helps people to figure out why there comment isn't working.\n for (const statement of sourceFile.statements) {\n const ranges: ts.CommentRange[] = [];\n ranges.push(...(ts.getLeadingCommentRanges(sourceFile.text, statement.getFullStart()) || []));\n ranges.push(...(ts.getTrailingCommentRanges(sourceFile.text, statement.getEnd()) || []));\n\n for (const commentRange of ranges) {\n const commentBody: string = sourceFile.text.substring(commentRange.pos, commentRange.end);\n\n if (/\\@packageDocumentation/i.test(commentBody)) {\n collector.messageRouter.addAnalyzerIssueForPosition(\n ExtractorMessageId.MisplacedPackageTag,\n 'The @packageDocumentation comment must appear at the top of entry point *.d.ts file',\n sourceFile,\n commentRange.pos\n );\n break;\n }\n }\n }\n }\n\n return packageCommentRange;\n }\n}\n"]} |