From 597e4a7fcde3d2da8a9692bb58d1b22203790e8d Mon Sep 17 00:00:00 2001 From: Jake Bailey <5341706+jakebailey@users.noreply.github.com> Date: Wed, 7 Sep 2022 14:04:47 -0700 Subject: [PATCH] Fix all internal JSDoc comments If these are regular comments, then they won't appear in our d.ts files. But, now we are relying on an external d.ts bundler to produce our final merged, so they need to be present in the "input" d.ts files, meaning they have to be JSDoc comments. These comments only work today because all of our builds load their TS files from scratch, so they see the actual source files and their non-JSDoc comments. The comments also need to be attached to a declaration, not floating, otherwise they won't be used by api-extractor, so move them if needed. --- scripts/failed-tests.cjs | 1 + scripts/processDiagnosticMessages.mjs | 1 + scripts/word2md.mjs | 1 + src/compiler/builder.ts | 39 +- src/compiler/builderPublic.ts | 27 +- src/compiler/builderStatePublic.ts | 4 +- src/compiler/commandLineParser.ts | 111 +- src/compiler/core.ts | 307 ++- src/compiler/corePublic.ts | 18 +- src/compiler/emitter.ts | 40 +- src/compiler/factory/baseNodeFactory.ts | 6 +- src/compiler/factory/emitHelpers.ts | 14 +- src/compiler/factory/emitNode.ts | 21 +- src/compiler/factory/nodeConverters.ts | 2 +- src/compiler/factory/nodeFactory.ts | 14 +- src/compiler/factory/nodeTests.ts | 42 +- src/compiler/factory/utilities.ts | 68 +- src/compiler/moduleNameResolver.ts | 88 +- src/compiler/moduleSpecifiers.ts | 7 +- src/compiler/parser.ts | 28 +- src/compiler/path.ts | 109 +- src/compiler/perfLogger.ts | 7 +- src/compiler/performance.ts | 32 +- src/compiler/performanceCore.ts | 9 +- src/compiler/program.ts | 64 +- src/compiler/resolutionCache.ts | 10 +- src/compiler/scanner.ts | 46 +- src/compiler/semver.ts | 6 +- src/compiler/sourcemap.ts | 3 +- src/compiler/symbolWalker.ts | 4 +- src/compiler/sys.ts | 77 +- src/compiler/transformer.ts | 3 +- src/compiler/transformers/classFields.ts | 3 +- src/compiler/transformers/declarations.ts | 5 +- src/compiler/transformers/destructuring.ts | 6 +- src/compiler/transformers/es2017.ts | 7 +- src/compiler/transformers/es5.ts | 3 +- src/compiler/transformers/legacyDecorators.ts | 2 +- src/compiler/transformers/typeSerializer.ts | 2 +- src/compiler/transformers/utilities.ts | 27 +- src/compiler/tsbuild.ts | 2 +- src/compiler/tsbuildPublic.ts | 65 +- src/compiler/types.ts | 1767 +++++++++-------- src/compiler/utilities.ts | 375 ++-- src/compiler/utilitiesPublic.ts | 187 +- src/compiler/visitorPublic.ts | 26 +- src/compiler/watch.ts | 28 +- src/compiler/watchPublic.ts | 20 +- src/compiler/watchUtilities.ts | 23 +- src/debug/dbg.ts | 2 +- src/deprecatedCompat/deprecations.ts | 2 +- src/harness/client.ts | 8 +- src/jsTyping/jsTyping.ts | 9 +- src/jsTyping/shared.ts | 22 +- src/jsTyping/types.ts | 8 +- src/server/editorServices.ts | 218 +- src/server/project.ts | 283 +-- src/server/protocol.ts | 130 +- src/server/scriptInfo.ts | 46 +- src/server/session.ts | 2 +- src/server/types.ts | 2 +- src/server/typingsCache.ts | 2 +- src/server/utilities.ts | 7 +- src/server/utilitiesPublic.ts | 6 +- src/services/breakpoints.ts | 3 +- src/services/callHierarchy.ts | 28 +- src/services/classifier.ts | 8 +- src/services/classifier2020.ts | 9 +- src/services/codefixes/helpers.ts | 9 +- src/services/codefixes/importFixes.ts | 9 +- src/services/completions.ts | 3 +- src/services/documentHighlights.ts | 2 +- src/services/documentRegistry.ts | 11 +- src/services/exportAsModule.ts | 4 +- src/services/findAllReferences.ts | 14 +- src/services/formatting/formatting.ts | 4 +- src/services/globalThisShim.ts | 4 +- src/services/goToDefinition.ts | 7 +- src/services/importTracker.ts | 17 +- src/services/jsDoc.ts | 3 +- src/services/organizeImports.ts | 16 +- src/services/refactorProvider.ts | 7 +- src/services/refactors/extractSymbol.ts | 15 +- src/services/refactors/helpers.ts | 10 +- src/services/services.ts | 32 +- src/services/shims.ts | 23 +- src/services/sourcemaps.ts | 3 +- src/services/textChanges.ts | 10 +- src/services/transpile.ts | 7 +- src/services/types.ts | 96 +- src/services/utilities.ts | 98 +- src/typingsInstallerCore/typingsInstaller.ts | 8 +- src/webServer/webServer.ts | 2 +- 93 files changed, 2850 insertions(+), 2116 deletions(-) diff --git a/scripts/failed-tests.cjs b/scripts/failed-tests.cjs index 78e90fc97695d..d2f3078e7b765 100644 --- a/scripts/failed-tests.cjs +++ b/scripts/failed-tests.cjs @@ -10,6 +10,7 @@ const os = require("os"); reporter?: Mocha.ReporterConstructor | keyof Mocha.reporters; reporterOptions?: any; // TODO(jakebailey): what? }} ReporterOptions */ +void 0; /** * .failed-tests reporter diff --git a/scripts/processDiagnosticMessages.mjs b/scripts/processDiagnosticMessages.mjs index 9b46eb6630ab4..33069ce66aa6a 100644 --- a/scripts/processDiagnosticMessages.mjs +++ b/scripts/processDiagnosticMessages.mjs @@ -9,6 +9,7 @@ import fs from "fs"; isEarly?: boolean; elidedInCompatabilityPyramid?: boolean; }} DiagnosticDetails */ +void 0; /** @typedef {Map} InputDiagnosticMessageTable */ diff --git a/scripts/word2md.mjs b/scripts/word2md.mjs index 785bcf93f1475..1bed91726ad41 100644 --- a/scripts/word2md.mjs +++ b/scripts/word2md.mjs @@ -60,6 +60,7 @@ const sys = (() => { subscript?: boolean; }; }} FindReplaceOptions */ +void 0; /** * @param {Word.Document} doc diff --git a/src/compiler/builder.ts b/src/compiler/builder.ts index dfc492c78086c..a0ab1339bca19 100644 --- a/src/compiler/builder.ts +++ b/src/compiler/builder.ts @@ -39,8 +39,11 @@ export interface ReusableDiagnosticRelatedInformation { /** @internal */ export type ReusableDiagnosticMessageChain = DiagnosticMessageChain; -/** @internal */ -/** Signature (Hash of d.ts emitted), is string if it was emitted using same d.ts.map option as what compilerOptions indicate, otherwise tuple of string */ +/** + * Signature (Hash of d.ts emitted), is string if it was emitted using same d.ts.map option as what compilerOptions indicate, otherwise tuple of string + * + * @internal + */ export type EmitSignature = string | [signature: string]; /** @internal */ @@ -105,9 +108,10 @@ export const enum BuilderFileEmit { All = AllJs | AllDts, } -/** @internal */ /** * State to store the changed files, affected files and cache semantic diagnostics + * + * @internal */ // TODO: GH#18217 Properties of this interface are frequently asserted to be defined. export interface BuilderProgramState extends BuilderState, ReusableBuilderProgramState { @@ -174,8 +178,11 @@ export type SavedBuildProgramEmitState = Pick & { changedFilesSet: BuilderProgramState["changedFilesSet"] | undefined }; -/** @internal */ -/** Get flags determining what all needs to be emitted */ +/** + * Get flags determining what all needs to be emitted + * + * @internal + */ export function getBuilderFileEmit(options: CompilerOptions) { let result = BuilderFileEmit.Js; if (options.sourceMap) result = result | BuilderFileEmit.JsMap; @@ -186,8 +193,11 @@ export function getBuilderFileEmit(options: CompilerOptions) { return result; } -/** @internal */ -/** Determing what all is pending to be emitted based on previous options or previous file emit flags */ +/** + * Determing what all is pending to be emitted based on previous options or previous file emit flags + * + * @internal + */ export function getPendingEmitKind(optionsOrEmitKind: CompilerOptions | BuilderFileEmit, oldOptionsOrEmitKind: CompilerOptions | BuilderFileEmit | undefined): BuilderFileEmit { const oldEmitKind = oldOptionsOrEmitKind && (isNumber(oldOptionsOrEmitKind) ? oldOptionsOrEmitKind : getBuilderFileEmit(oldOptionsOrEmitKind)); const emitKind = isNumber(optionsOrEmitKind) ? optionsOrEmitKind : getBuilderFileEmit(optionsOrEmitKind); @@ -821,11 +831,12 @@ export type ProgramBuildInfoFileId = number & { __programBuildInfoFileIdBrand: a export type ProgramBuildInfoFileIdListId = number & { __programBuildInfoFileIdListIdBrand: any }; /** @internal */ export type ProgramBuildInfoDiagnostic = ProgramBuildInfoFileId | [fileId: ProgramBuildInfoFileId, diagnostics: readonly ReusableDiagnostic[]]; -/** @internal */ /** * fileId if pending emit is same as what compilerOptions suggest * [fileId] if pending emit is only dts file emit * [fileId, emitKind] if any other type emit is pending + * + * @internal */ export type ProgramBuilderInfoFilePendingEmit = ProgramBuildInfoFileId | [fileId: ProgramBuildInfoFileId] | [fileId: ProgramBuildInfoFileId, emitKind: BuilderFileEmit]; /** @internal */ @@ -840,15 +851,17 @@ export type ProgramMultiFileEmitBuildInfoBuilderStateFileInfo = Omit ["" + value, key] as const))); // NOTE: The order here is important to default lib ordering as entries will have the same @@ -122,19 +122,21 @@ const libEntries: [string, string][] = [ * An array of supported "lib" reference file names used to determine the order for inclusion * when referenced, as well as for spelling suggestions. This ensures the correct ordering for * overload resolution when a type declared in one lib is extended by another. + * + * @internal */ -/* @internal */ export const libs = libEntries.map(entry => entry[0]); /** * A map of lib names to lib files. This map is used both for parsing the "lib" command line * option as well as for resolving lib reference directives. + * + * @internal */ -/* @internal */ export const libMap = new Map(libEntries); // Watch related options -/* @internal */ +/** @internal */ export const optionsForWatch: CommandLineOption[] = [ { name: "watchFile", @@ -207,7 +209,7 @@ export const optionsForWatch: CommandLineOption[] = [ }, ]; -/* @internal */ +/** @internal */ export const commonOptionsWithBuild: CommandLineOption[] = [ { name: "help", @@ -395,7 +397,7 @@ export const commonOptionsWithBuild: CommandLineOption[] = [ }, ]; -/* @internal */ +/** @internal */ export const targetOptionDeclaration: CommandLineOptionOfCustomType = { name: "target", shortName: "t", @@ -424,7 +426,7 @@ export const targetOptionDeclaration: CommandLineOptionOfCustomType = { defaultValueDescription: ScriptTarget.ES3, }; -/*@internal*/ +/** @internal */ export const moduleOptionDeclaration: CommandLineOptionOfCustomType = { name: "module", shortName: "m", @@ -1372,42 +1374,42 @@ const commandOptionsWithoutBuild: CommandLineOption[] = [ } ]; -/* @internal */ +/** @internal */ export const optionDeclarations: CommandLineOption[] = [ ...commonOptionsWithBuild, ...commandOptionsWithoutBuild, ]; -/* @internal */ +/** @internal */ export const semanticDiagnosticsOptionDeclarations: readonly CommandLineOption[] = optionDeclarations.filter(option => !!option.affectsSemanticDiagnostics); -/* @internal */ +/** @internal */ export const affectsEmitOptionDeclarations: readonly CommandLineOption[] = optionDeclarations.filter(option => !!option.affectsEmit); -/* @internal */ +/** @internal */ export const affectsDeclarationPathOptionDeclarations: readonly CommandLineOption[] = optionDeclarations.filter(option => !!option.affectsDeclarationPath); -/* @internal */ +/** @internal */ export const moduleResolutionOptionDeclarations: readonly CommandLineOption[] = optionDeclarations.filter(option => !!option.affectsModuleResolution); -/* @internal */ +/** @internal */ export const sourceFileAffectingCompilerOptions: readonly CommandLineOption[] = optionDeclarations.filter(option => !!option.affectsSourceFile || !!option.affectsModuleResolution || !!option.affectsBindDiagnostics); -/* @internal */ +/** @internal */ export const optionsAffectingProgramStructure: readonly CommandLineOption[] = optionDeclarations.filter(option => !!option.affectsProgramStructure); -/* @internal */ +/** @internal */ export const transpileOptionValueCompilerOptions: readonly CommandLineOption[] = optionDeclarations.filter(option => hasProperty(option, "transpileOptionValue")); // Build related options -/* @internal */ +/** @internal */ export const optionsForBuild: CommandLineOption[] = [ { name: "verbose", @@ -1442,13 +1444,13 @@ export const optionsForBuild: CommandLineOption[] = [ } ]; -/* @internal */ +/** @internal */ export const buildOpts: CommandLineOption[] = [ ...commonOptionsWithBuild, ...optionsForBuild ]; -/* @internal */ +/** @internal */ export const typeAcquisitionDeclarations: CommandLineOption[] = [ { /* @deprecated typingOptions.enableAutoDiscovery @@ -1486,13 +1488,13 @@ export const typeAcquisitionDeclarations: CommandLineOption[] = [ }, ]; -/* @internal */ +/** @internal */ export interface OptionsNameMap { optionsNameMap: ESMap; shortOptionNames: ESMap; } -/*@internal*/ +/** @internal */ export function createOptionNameMap(optionDeclarations: readonly CommandLineOption[]): OptionsNameMap { const optionsNameMap = new Map(); const shortOptionNames = new Map(); @@ -1508,7 +1510,7 @@ export function createOptionNameMap(optionDeclarations: readonly CommandLineOpti let optionsNameMapCache: OptionsNameMap; -/* @internal */ +/** @internal */ export function getOptionsNameMap(): OptionsNameMap { return optionsNameMapCache ||= createOptionNameMap(optionDeclarations); } @@ -1518,7 +1520,7 @@ const compilerOptionsAlternateMode: AlternateModeDiagnostics = { getOptionsNameMap: getBuildOptionsNameMap }; -/* @internal */ +/** @internal */ export const defaultInitCompilerOptions: CompilerOptions = { module: ModuleKind.CommonJS, target: ScriptTarget.ES2016, @@ -1528,7 +1530,7 @@ export const defaultInitCompilerOptions: CompilerOptions = { skipLibCheck: true }; -/* @internal */ +/** @internal */ export function convertEnableAutoDiscoveryToEnable(typeAcquisition: TypeAcquisition): TypeAcquisition { // Convert deprecated typingOptions.enableAutoDiscovery to typeAcquisition.enable if (typeAcquisition && typeAcquisition.enableAutoDiscovery !== undefined && typeAcquisition.enable === undefined) { @@ -1541,7 +1543,7 @@ export function convertEnableAutoDiscoveryToEnable(typeAcquisition: TypeAcquisit return typeAcquisition; } -/* @internal */ +/** @internal */ export function createCompilerDiagnosticForInvalidCustomType(opt: CommandLineOptionOfCustomType): Diagnostic { return createDiagnosticForInvalidCustomType(opt, createCompilerDiagnostic); } @@ -1551,12 +1553,12 @@ function createDiagnosticForInvalidCustomType(opt: CommandLineOptionOfCustomType return createDiagnostic(Diagnostics.Argument_for_0_option_must_be_Colon_1, `--${opt.name}`, namesOfType); } -/* @internal */ +/** @internal */ export function parseCustomTypeOption(opt: CommandLineOptionOfCustomType, value: string, errors: Push) { return convertJsonOptionOfCustomType(opt, trimString(value || ""), errors); } -/* @internal */ +/** @internal */ export function parseListTypeOption(opt: CommandLineOptionOfListType, value = "", errors: Push): (string | number)[] | undefined { value = trimString(value); if (startsWith(value, "-")) { @@ -1576,12 +1578,12 @@ export function parseListTypeOption(opt: CommandLineOptionOfListType, value = "" } } -/*@internal*/ +/** @internal */ export interface OptionsBase { [option: string]: CompilerOptionsValue | TsConfigSourceFile | undefined; } -/*@internal*/ +/** @internal */ export interface ParseCommandLineWorkerDiagnostics extends DidYouMeanOptionsDiagnostics { getOptionsNameMap: () => OptionsNameMap; optionTypeMismatchDiagnostic: DiagnosticMessage; @@ -1607,7 +1609,7 @@ function createUnknownOptionError( createDiagnostics(diagnostics.unknownOptionDiagnostic, unknownOptionErrorText || unknownOption); } -/*@internal*/ +/** @internal */ export function parseCommandLineWorker( diagnostics: ParseCommandLineWorkerDiagnostics, commandLine: readonly string[], @@ -1764,7 +1766,7 @@ function parseOptionValue( return i; } -/*@internal*/ +/** @internal */ export const compilerOptionsDidYouMeanDiagnostics: ParseCommandLineWorkerDiagnostics = { alternateMode: compilerOptionsAlternateMode, getOptionsNameMap, @@ -1795,7 +1797,7 @@ function getOptionDeclarationFromName(getOptionNameMap: () => OptionsNameMap, op return optionsNameMap.get(optionName); } -/*@internal*/ +/** @internal */ export interface ParsedBuildCommand { buildOptions: BuildOptions; watchOptions: WatchOptions | undefined; @@ -1822,7 +1824,7 @@ const buildOptionsDidYouMeanDiagnostics: ParseCommandLineWorkerDiagnostics = { optionTypeMismatchDiagnostic: Diagnostics.Build_option_0_requires_a_value_of_type_1 }; -/*@internal*/ +/** @internal */ export function parseBuildCommand(args: readonly string[]): ParsedBuildCommand { const { options, watchOptions, fileNames: projects, errors } = parseCommandLineWorker( buildOptionsDidYouMeanDiagnostics, @@ -1852,7 +1854,7 @@ export function parseBuildCommand(args: readonly string[]): ParsedBuildCommand { return { buildOptions, watchOptions, projects, errors }; } -/* @internal */ +/** @internal */ export function getDiagnosticText(_message: DiagnosticMessage, ..._args: any[]): string { const diagnostic = createCompilerDiagnostic.apply(undefined, arguments); return diagnostic.messageText as string; @@ -1942,7 +1944,7 @@ export function readJsonConfigFile(fileName: string, readFile: (path: string) => return isString(textOrDiagnostic) ? parseJsonText(fileName, textOrDiagnostic) : { fileName, parseDiagnostics: [textOrDiagnostic] } as TsConfigSourceFile; } -/*@internal*/ +/** @internal */ export function tryReadFile(fileName: string, readFile: (path: string) => string | undefined): string | Diagnostic { let text: string | undefined; try { @@ -2070,7 +2072,7 @@ function getTsconfigRootOptionsMap() { return _tsconfigRootOptions; } -/*@internal*/ +/** @internal */ interface JsonConversionNotifier { /** * Notifies parent option object is being set with the optionKey and a valid optionValue @@ -2134,8 +2136,9 @@ export function convertToObject(sourceFile: JsonSourceFile, errors: Push): object { return { ...arrayFrom(optionMap.entries()).reduce((prev, cur) => ({ ...prev, [cur[0]]: cur[1] }), {}), @@ -2469,7 +2473,7 @@ function getCustomTypeMapOfCommandLineOption(optionDefinition: CommandLineOption } } -/* @internal */ +/** @internal */ export function getNameOfCompilerOptionValue(value: CompilerOptionsValue, customTypeMap: ESMap): string | undefined { // There is a typeMap associated with this command-line option so use it to map value back to its name return forEachEntry(customTypeMap, (mapValue, key) => { @@ -2479,7 +2483,7 @@ export function getNameOfCompilerOptionValue(value: CompilerOptionsValue, custom }); } -/* @internal */ +/** @internal */ export function serializeCompilerOptions( options: CompilerOptions, pathOptions?: { configFilePath: string, useCaseSensitiveFileNames: boolean } @@ -2580,8 +2584,9 @@ function getSerializedCompilerOption(options: CompilerOptions): ESMap string) { const result: CompilerOptions = {}; const optionsNameMap = getOptionsNameMap().optionsNameMap; @@ -2730,7 +2735,7 @@ export function parseJsonSourceFileConfigFileContent(sourceFile: TsConfigSourceF return result; } -/*@internal*/ +/** @internal */ export function setConfigFileInOptions(options: CompilerOptions, configFile: TsConfigSourceFile | undefined) { if (configFile) { Object.defineProperty(options, "configFile", { enumerable: false, writable: false, value: configFile }); @@ -2747,7 +2752,7 @@ function directoryOfCombinedPath(fileName: string, basePath: string) { return getDirectoryPath(getNormalizedAbsolutePath(fileName, basePath)); } -/*@internal*/ +/** @internal */ export const defaultIncludeSpec = "**/*"; /** @@ -2947,12 +2952,12 @@ function shouldReportNoInputFiles(fileNames: string[], canJsonReportNoInutFiles: return fileNames.length === 0 && canJsonReportNoInutFiles && (!resolutionStack || resolutionStack.length === 0); } -/*@internal*/ +/** @internal */ export function canJsonReportNoInputFiles(raw: any) { return !hasProperty(raw, "files") && !hasProperty(raw, "references"); } -/*@internal*/ +/** @internal */ export function updateErrorForNoInputFiles(fileNames: string[], configFileName: string, configFileSpecs: ConfigFileSpecs, configParseDiagnostics: Diagnostic[], canJsonReportNoInutFiles: boolean) { const existingErrors = configParseDiagnostics.length; if (shouldReportNoInputFiles(fileNames, canJsonReportNoInutFiles)) { @@ -3308,7 +3313,7 @@ function convertOptionsFromJson(optionsNameMap: ESMap return defaultOptions; } -/*@internal*/ +/** @internal */ export function convertJsonOption(opt: CommandLineOption, value: any, basePath: string, errors: Push): CompilerOptionsValue { if (isCompilerOptionsValue(opt, value)) { const optType = opt.type; @@ -3410,8 +3415,9 @@ const wildcardDirectoryPattern = /^[^*?]*(?=\/[^/]*[*?])/; * @param options Compiler options. * @param host The host used to resolve files and directories. * @param extraFileExtensions optionaly file extra file extension information from host + * + * @internal */ -/* @internal */ export function getFileNamesFromConfigSpecs( configFileSpecs: ConfigFileSpecs, basePath: string, @@ -3501,7 +3507,7 @@ export function getFileNamesFromConfigSpecs( return literalFiles.concat(wildcardFiles, arrayFrom(wildCardJsonFileMap.values())); } -/* @internal */ +/** @internal */ export function isExcludedFile( pathToCheck: string, spec: ConfigFileSpecs, @@ -3538,7 +3544,7 @@ function invalidDotDotAfterRecursiveWildcard(s: string) { return lastDotIndex > wildcardIndex; } -/* @internal */ +/** @internal */ export function matchesExclude( pathToCheck: string, excludeSpecs: readonly string[] | undefined, @@ -3729,8 +3735,9 @@ function removeWildcardFilesWithLowerPriorityExtension(file: string, wildcardFil /** * Produces a cleaned version of compiler options with personally identifying info (aka, paths) removed. * Also converts enum values back to strings. + * + * @internal */ -/* @internal */ export function convertCompilerOptionsForTelemetry(opts: CompilerOptions): CompilerOptions { const out: CompilerOptions = {}; for (const key in opts) { diff --git a/src/compiler/core.ts b/src/compiler/core.ts index 05a2b6bf085e3..e69910846ecd2 100644 --- a/src/compiler/core.ts +++ b/src/compiler/core.ts @@ -41,11 +41,12 @@ export function length(array: readonly any[] | undefined): number { return array ? array.length : 0; } -/** @internal */ /** * Iterates through 'array' by index and performs the callback on each element of array until the callback * returns a truthy value, then returns that value. * If no such value is found, the callback is applied to each element of array and undefined is returned. + * + * @internal */ export function forEach(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined { if (array) { @@ -59,9 +60,10 @@ export function forEach(array: readonly T[] | undefined, callback: (elemen return undefined; } -/** @internal */ /** * Like `forEach`, but iterates in reverse order. + * + * @internal */ export function forEachRight(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined { if (array) { @@ -75,8 +77,11 @@ export function forEachRight(array: readonly T[] | undefined, callback: (e return undefined; } -/** @internal */ -/** Like `forEach`, but suitable for use with numbers and strings (which may be falsy). */ +/** + * Like `forEach`, but suitable for use with numbers and strings (which may be falsy). + * + * @internal + */ export function firstDefined(array: readonly T[] | undefined, callback: (element: T, index: number) => U | undefined): U | undefined { if (array === undefined) { return undefined; @@ -151,10 +156,11 @@ export function zipToMap(keys: readonly K[], values: readonly V[]): ESMap< return map; } -/** @internal */ /** * Creates a new array with `element` interspersed in between each element of `input` * if there is more than 1 value in `input`. Otherwise, returns the existing array. + * + * @internal */ export function intersperse(input: T[], element: T): T[] { if (input.length <= 1) { @@ -168,11 +174,12 @@ export function intersperse(input: T[], element: T): T[] { return result; } -/** @internal */ /** * Iterates through `array` by index and performs the callback on each element of array until the callback * returns a falsey value, then returns false. * If no such value is found, the callback is applied to each element of array and `true` is returned. + * + * @internal */ export function every(array: readonly T[] | undefined, callback: (element: T, index: number) => boolean): boolean { if (array) { @@ -186,8 +193,11 @@ export function every(array: readonly T[] | undefined, callback: (element: T, return true; } -/** @internal */ -/** Works like Array.prototype.find, returning `undefined` if no element satisfying the predicate is found. */ +/** + * Works like Array.prototype.find, returning `undefined` if no element satisfying the predicate is found. + * + * @internal + */ export function find(array: readonly T[] | undefined, predicate: (element: T, index: number) => element is U, startIndex?: number): U | undefined; /** @internal */ export function find(array: readonly T[] | undefined, predicate: (element: T, index: number) => boolean, startIndex?: number): T | undefined; @@ -219,8 +229,11 @@ export function findLast(array: readonly T[] | undefined, predicate: (element return undefined; } -/** @internal */ -/** Works like Array.prototype.findIndex, returning `-1` if no element satisfying the predicate is found. */ +/** + * Works like Array.prototype.findIndex, returning `-1` if no element satisfying the predicate is found. + * + * @internal + */ export function findIndex(array: readonly T[] | undefined, predicate: (element: T, index: number) => boolean, startIndex?: number): number { if (array === undefined) return -1; for (let i = startIndex ?? 0; i < array.length; i++) { @@ -242,10 +255,11 @@ export function findLastIndex(array: readonly T[] | undefined, predicate: (el return -1; } -/** @internal */ /** * Returns the first truthy result of `callback`, or else fails. * This is like `forEach`, but never returns undefined. + * + * @internal */ export function findMap(array: readonly T[], callback: (element: T, index: number) => U | undefined): U { for (let i = 0; i < array.length; i++) { @@ -298,10 +312,11 @@ export function countWhere(array: readonly T[] | undefined, predicate: (x: T, return count; } -/** @internal */ /** * Filters an array by a predicate function. Returns the same array instance if the predicate is * true for all elements, otherwise returns a new array instance containing the filtered subset. + * + * @internal */ export function filter(array: T[], f: (x: T) => x is U): U[]; /** @internal */ @@ -384,8 +399,10 @@ export function mapIterator(iter: Iterator, mapFn: (x: T) => U): Iterat }; } -// Maps from T to T and avoids allocation if all elements map to themselves -/** @internal */ +/** + * Maps from T to T and avoids allocation if all elements map to themselves + * + * @internal */ export function sameMap(array: T[], f: (x: T, i: number) => T): T[]; /** @internal */ export function sameMap(array: readonly T[], f: (x: T, i: number) => T): readonly T[]; @@ -412,11 +429,12 @@ export function sameMap(array: readonly T[] | undefined, f: (x: T, i: number) return array; } -/** @internal */ /** * Flattens an array containing a mix of array or non-array elements. * * @param array The array to flatten. + * + * @internal */ export function flatten(array: T[][] | readonly (T | readonly T[] | undefined)[]): T[] { const result = []; @@ -433,12 +451,14 @@ export function flatten(array: T[][] | readonly (T | readonly T[] | undefined return result; } -/** @internal */ + /** * Maps an array. If the mapped value is an array, it is spread into the result. * * @param array The array to map. * @param mapfn The callback used to map the result into one or more values. + * + * @internal */ export function flatMap(array: readonly T[] | undefined, mapfn: (x: T, i: number) => U | readonly U[] | undefined): readonly U[] { let result: U[] | undefined; @@ -506,13 +526,15 @@ export function flatMapIterator(iter: Iterator, mapfn: (x: T) => readon } } -/** @internal */ + /** * Maps an array. If the mapped value is an array, it is spread into the result. * Avoids allocation if all elements map to themselves. * * @param array The array to map. * @param mapfn The callback used to map the result into one or more values. + * + * @internal */ export function sameFlatMap(array: T[], mapfn: (x: T, i: number) => T | readonly T[]): T[]; /** @internal */ @@ -661,13 +683,14 @@ export function singleIterator(value: T): Iterator { }; } -/** @internal */ /** * Maps contiguous spans of values with the same key. * * @param array The array to map. * @param keyfn A callback used to select the key for an element. * @param mapfn A callback used to map a contiguous chunk of values to a single value. + * + * @internal */ export function spanMap(array: readonly T[], keyfn: (x: T, i: number) => K, mapfn: (chunk: T[], key: K, start: number, end: number) => U): U[]; /** @internal */ @@ -752,8 +775,11 @@ export function some(array: readonly T[] | undefined, predicate?: (value: T) return false; } -/** @internal */ -/** Calls the callback with (start, afterEnd) index pairs for each range where 'pred' is true. */ +/** + * Calls the callback with (start, afterEnd) index pairs for each range where 'pred' is true. + * + * @internal + */ export function getRangesWhere(arr: readonly T[], pred: (t: T) => boolean, cb: (start: number, afterEnd: number) => void): void { let start: number | undefined; for (let i = 0; i < arr.length; i++) { @@ -824,12 +850,13 @@ function deduplicateEquality(array: readonly T[], equalityComparer: EqualityC return result; } -/** @internal */ /** * Deduplicates an unsorted array. * @param equalityComparer An `EqualityComparer` used to determine if two values are duplicates. * @param comparer An optional `Comparer` used to sort entries before comparison, though the * result will remain in the original order in `array`. + * + * @internal */ export function deduplicate(array: readonly T[], equalityComparer: EqualityComparer, comparer?: Comparer): T[] { return array.length === 0 ? [] : @@ -935,9 +962,10 @@ export function arrayIsEqualTo(array1: readonly T[] | undefined, array2: read return true; } -/** @internal */ /** * Compacts an array, removing any falsey elements. + * + * @internal */ export function compact(array: (T | undefined | null | false | 0 | "")[]): T[]; /** @internal */ @@ -966,11 +994,12 @@ export function compact(array: T[]): T[] { return result || array; } -/** @internal */ /** * Gets the relative complement of `arrayA` with respect to `arrayB`, returning the elements that * are not present in `arrayA` but are present in `arrayB`. Assumes both arrays are sorted * based on the provided comparer. + * + * @internal */ export function relativeComplement(arrayA: T[] | undefined, arrayB: T[] | undefined, comparer: Comparer): T[] | undefined { if (!arrayB || !arrayA || arrayB.length === 0 || arrayA.length === 0) return arrayB; @@ -1019,7 +1048,6 @@ export function sum, K extends string>(array: readon return result; } -/** @internal */ /** * Appends a value to an array, returning the array. * @@ -1027,6 +1055,8 @@ export function sum, K extends string>(array: readon * is created if `value` was appended. * @param value The value to append to the array. If `value` is `undefined`, nothing is * appended. + * + * @internal */ export function append[number] | undefined>(to: TArray, value: TValue): [undefined, undefined] extends [TArray, TValue] ? TArray : NonNullable[number][]; /** @internal */ @@ -1045,7 +1075,6 @@ export function append(to: T[], value: T | undefined): T[] | undefined { return to; } -/** @internal */ /** * Combines two arrays, values, or undefineds into the smallest container that can accommodate the resulting set: * @@ -1057,6 +1086,8 @@ export function append(to: T[], value: T | undefined): T[] | undefined { * T[] -> T -> T[] (append) * T[] -> T[] -> T[] (concatenate) * ``` + * + * @internal */ export function combine(xs: T | readonly T[] | undefined, ys: T | readonly T[] | undefined): T | readonly T[] | undefined; /** @internal */ @@ -1078,7 +1109,6 @@ function toOffset(array: readonly any[], offset: number) { return offset < 0 ? array.length + offset : offset; } -/** @internal */ /** * Appends a range of value to an array, returning the array. * @@ -1088,6 +1118,8 @@ function toOffset(array: readonly any[], offset: number) { * appended. If an element of `from` is `undefined`, that element is not appended. * @param start The offset in `from` at which to start copying values. * @param end The offset in `from` at which to stop copying values (non-inclusive). + * + * @internal */ export function addRange(to: T[], from: readonly T[] | undefined, start?: number, end?: number): T[]; /** @internal */ @@ -1106,9 +1138,10 @@ export function addRange(to: T[] | undefined, from: readonly T[] | undefined, return to; } -/** @internal */ /** * @return Whether the value was added. + * + * @internal */ export function pushIfUnique(array: T[], toAdd: T, equalityComparer?: EqualityComparer): boolean { if (contains(array, toAdd, equalityComparer)) { @@ -1120,9 +1153,10 @@ export function pushIfUnique(array: T[], toAdd: T, equalityComparer?: Equalit } } -/** @internal */ /** * Unlike `pushIfUnique`, this can take `undefined` as an input, and returns a new array. + * + * @internal */ export function appendIfUnique(array: T[] | undefined, toAdd: T, equalityComparer?: EqualityComparer): T[] { if (array) { @@ -1139,9 +1173,10 @@ function stableSortIndices(array: readonly T[], indices: number[], comparer: indices.sort((x, y) => comparer(array[x], array[y]) || compareValues(x, y)); } -/** @internal */ /** * Returns a new sorted array. + * + * @internal */ export function sort(array: readonly T[], comparer?: Comparer): SortedReadonlyArray { return (array.length === 0 ? array : array.slice().sort(comparer)) as SortedReadonlyArray; @@ -1177,9 +1212,10 @@ export function arrayReverseIterator(array: readonly T[]): Iterator { }; } -/** @internal */ /** * Stable sort of an array. Elements equal to each other maintain their relative position in the array. + * + * @internal */ export function stableSort(array: readonly T[], comparer: Comparer): SortedReadonlyArray { const indices = indicesOf(array); @@ -1198,10 +1234,11 @@ export function rangeEquals(array1: readonly T[], array2: readonly T[], pos: return true; } -/** @internal */ /** * Returns the element at a specific offset in an array if non-empty, `undefined` otherwise. * A negative offset indicates the element should be retrieved from the end of the array. + * + * @internal */ export function elementAt(array: readonly T[] | undefined, offset: number): T | undefined { if (array) { @@ -1213,9 +1250,10 @@ export function elementAt(array: readonly T[] | undefined, offset: number): T return undefined; } -/** @internal */ /** * Returns the first element of an array if non-empty, `undefined` otherwise. + * + * @internal */ export function firstOrUndefined(array: readonly T[] | undefined): T | undefined { return array === undefined || array.length === 0 ? undefined : array[0]; @@ -1227,9 +1265,10 @@ export function first(array: readonly T[]): T { return array[0]; } -/** @internal */ /** * Returns the last element of an array if non-empty, `undefined` otherwise. + * + * @internal */ export function lastOrUndefined(array: readonly T[] | undefined): T | undefined { return array === undefined || array.length === 0 ? undefined : array[array.length - 1]; @@ -1241,9 +1280,10 @@ export function last(array: readonly T[]): T { return array[array.length - 1]; } -/** @internal */ /** * Returns the only element of an array if it contains only one element, `undefined` otherwise. + * + * @internal */ export function singleOrUndefined(array: readonly T[] | undefined): T | undefined { return array && array.length === 1 @@ -1251,18 +1291,20 @@ export function singleOrUndefined(array: readonly T[] | undefined): T | undef : undefined; } -/** @internal */ /** * Returns the only element of an array if it contains only one element; throws otherwise. + * + * @internal */ export function single(array: readonly T[]): T { return Debug.checkDefined(singleOrUndefined(array)); } -/** @internal */ /** * Returns the only element of an array if it contains only one element; otherwise, returns the * array. + * + * @internal */ export function singleOrMany(array: T[]): T | T[]; /** @internal */ @@ -1285,7 +1327,6 @@ export function replaceElement(array: readonly T[], index: number, value: T): return result; } -/** @internal */ /** * Performs a binary search, finding the index at which `value` occurs in `array`. * If no such index is found, returns the 2's-complement of first index at which @@ -1296,12 +1337,13 @@ export function replaceElement(array: readonly T[], index: number, value: T): * `array`. * @param keyComparer A callback used to compare two keys in a sorted array. * @param offset An offset into `array` at which to start the search. + * + * @internal */ export function binarySearch(array: readonly T[], value: T, keySelector: (v: T) => U, keyComparer: Comparer, offset?: number): number { return binarySearchKey(array, keySelector(value), keySelector, keyComparer, offset); } -/** @internal */ /** * Performs a binary search, finding the index at which an object with `key` occurs in `array`. * If no such index is found, returns the 2's-complement of first index at which @@ -1311,6 +1353,8 @@ export function binarySearch(array: readonly T[], value: T, keySelector: ( * @param keySelector A callback used to select the search key from each element of `array`. * @param keyComparer A callback used to compare two keys in a sorted array. * @param offset An offset into `array` at which to start the search. + * + * @internal */ export function binarySearchKey(array: readonly T[], key: U, keySelector: (v: T, i: number) => U, keyComparer: Comparer, offset?: number): number { if (!some(array)) { @@ -1368,31 +1412,34 @@ export function reduceLeft(array: T[], f: (memo: T, value: T, i: number) => T const hasOwnProperty = Object.prototype.hasOwnProperty; -/** @internal */ /** * Indicates whether a map-like contains an own property with the specified key. * * @param map A map-like. * @param key A property key. + * + * @internal */ export function hasProperty(map: MapLike, key: string): boolean { return hasOwnProperty.call(map, key); } -/** @internal */ /** * Gets the value of an owned property in a map-like. * * @param map A map-like. * @param key A property key. + * + * @internal */ export function getProperty(map: MapLike, key: string): T | undefined { return hasOwnProperty.call(map, key) ? map[key] : undefined; } -/** @internal */ /** * Gets the owned, enumerable property keys of a map-like. + * + * @internal */ export function getOwnKeys(map: MapLike): string[] { const keys: string[] = []; @@ -1452,8 +1499,11 @@ export function arrayOf(count: number, f: (index: number) => T): T[] { return result; } -/** @internal */ -/** Shims `Array.from`. */ +/** + * Shims `Array.from`. + * + * @internal + */ export function arrayFrom(iterator: Iterator | IterableIterator, map: (t: T) => U): U[]; /** @internal */ export function arrayFrom(iterator: Iterator | IterableIterator): T[]; @@ -1480,12 +1530,13 @@ export function assign(t: T, ...args: (T | undefined)[]) { return t; } -/** @internal */ /** * Performs a shallow equality comparison of the contents of two map-likes. * * @param left A map-like whose properties should be compared. * @param right A map-like whose properties should be compared. + * + * @internal */ export function equalOwnProperties(left: MapLike | undefined, right: MapLike | undefined, equalityComparer: EqualityComparer = equateValues) { if (left === right) return true; @@ -1506,7 +1557,6 @@ export function equalOwnProperties(left: MapLike | undefined, right: MapLi return true; } -/** @internal */ /** * Creates a map from the elements of an array. * @@ -1516,6 +1566,8 @@ export function equalOwnProperties(left: MapLike | undefined, right: MapLi * This function makes no effort to avoid collisions; if any two elements produce * the same key with the given 'makeKey' function, then the element with the higher * index in the array will be the one associated with the produced key. + * + * @internal */ export function arrayToMap(array: readonly V[], makeKey: (value: V) => K | undefined): ESMap; /** @internal */ @@ -1584,11 +1636,12 @@ export function clone(object: T): T { return result; } -/** @internal */ /** * Creates a new object by adding the own properties of `second`, then the own properties of `first`. * * NOTE: This means that if a property exists in both `first` and `second`, the property in `first` will be chosen. + * + * @internal */ export function extend(first: T1, second: T2): T1 & T2 { const result: T1 & T2 = {} as any; @@ -1729,7 +1782,6 @@ export function createQueue(items?: readonly T[]): Queue { }; } -/** @internal */ /** * Creates a Set with custom equality and hash code functionality. This is useful when you * want to use something looser than object identity - e.g. "has the same span". @@ -1739,6 +1791,8 @@ export function createQueue(items?: readonly T[]): Queue { * * To facilitate a perf optimization (lazy allocation of bucket arrays), `TElement` is * assumed not to be an array type. + * + * @internal */ export function createSet(getHashCode: (element: TElement) => THash, equals: EqualityComparer): Set { const multiMap = new Map(); @@ -1883,9 +1937,10 @@ export function createSet(getHashCode: (element: TElem return set; } -/** @internal */ /** * Tests whether a value is an array. + * + * @internal */ export function isArray(value: any): value is readonly unknown[] { return Array.isArray ? Array.isArray(value) : value instanceof Array; @@ -1900,9 +1955,10 @@ export function toArray(value: T | T[]): T[] { return isArray(value) ? value : [value]; } -/** @internal */ /** * Tests whether a value is string + * + * @internal */ export function isString(text: unknown): text is string { return typeof text === "string"; @@ -1928,8 +1984,11 @@ export function cast(value: TIn | undefined, test: return Debug.fail(`Invalid cast. The supplied value ${value} did not pass the test '${Debug.getFunctionName(test)}'.`); } -/** @internal */ -/** Does nothing. */ +/** + * Does nothing. + * + * @internal + */ export function noop(_?: unknown): void { } /** @internal */ @@ -1938,32 +1997,47 @@ export const noopPush: Push = { length: 0 }; -/** @internal */ -/** Do nothing and return false */ +/** + * Do nothing and return false + * + * @internal + */ export function returnFalse(): false { return false; } -/** @internal */ -/** Do nothing and return true */ +/** + * Do nothing and return true + * + * @internal + */ export function returnTrue(): true { return true; } -/** @internal */ -/** Do nothing and return undefined */ +/** + * Do nothing and return undefined + * + * @internal + */ export function returnUndefined(): undefined { return undefined; } -/** @internal */ -/** Returns its argument. */ +/** + * Returns its argument. + * + * @internal + */ export function identity(x: T) { return x; } -/** @internal */ -/** Returns lower case string */ +/** + * Returns lower case string + * + * @internal + */ export function toLowerCase(x: string) { return x.toLowerCase(); } @@ -1991,7 +2065,6 @@ export function toLowerCase(x: string) { // But to avoid having to do string building for most common cases, also ignore // a-z, 0-9, \u0131, \u00DF, \, /, ., : and space const fileNameLowerCaseRegExp = /[^\u0130\u0131\u00DFa-z0-9\\/:\-_\. ]+/g; -/** @internal */ /** * Case insensitive file systems have descripencies in how they handle some characters (eg. turkish Upper case I with dot on top - \u0130) * This function is used in places where we want to make file name as a key on these systems @@ -2002,6 +2075,8 @@ const fileNameLowerCaseRegExp = /[^\u0130\u0131\u00DFa-z0-9\\/:\-_\. ]+/g; * We could use upper case and we would still need to deal with the descripencies but * we want to continue using lower case since in most cases filenames are lowercasewe and wont need any case changes and avoid having to store another string for the key * So for this function purpose, we go ahead and assume character I with dot on top it as case sensitive since its very unlikely to use lower case form of that special character + * + * @internal */ export function toFileNameLowerCase(x: string) { return fileNameLowerCaseRegExp.test(x) ? @@ -2009,8 +2084,11 @@ export function toFileNameLowerCase(x: string) { x; } -/** @internal */ -/** Throws an error because a function is not implemented. */ +/** + * Throws an error because a function is not implemented. + * + * @internal + */ export function notImplemented(): never { throw new Error("Not implemented"); } @@ -2027,8 +2105,11 @@ export function memoize(callback: () => T): () => T { }; } -/** @internal */ -/** A version of `memoize` that supports a single primitive argument */ +/** + * A version of `memoize` that supports a single primitive argument + * + * @internal + */ export function memoizeOne(callback: (arg: A) => T): (arg: A) => T { const map = new Map(); return (arg: A) => { @@ -2042,12 +2123,13 @@ export function memoizeOne(c }; } -/** @internal */ /** * High-order function, composes functions. Note that functions are composed inside-out; * for example, `compose(a, b)` is the equivalent of `x => b(a(x))`. * * @param args The functions to compose. + * + * @internal */ export function compose(...args: ((t: T) => T)[]): (t: T) => T; /** @internal */ @@ -2085,10 +2167,11 @@ export const enum AssertionLevel { VeryAggressive = 3, } -/** @internal */ /** * Safer version of `Function` which should not be called. * Every function should be assignable to this, but this should not be assignable to every function. + * + * @internal */ export type AnyFunction = (...args: never[]) => void; /** @internal */ @@ -2099,7 +2182,6 @@ export function equateValues(a: T, b: T) { return a === b; } -/** @internal */ /** * Compare the equality of two strings using a case-sensitive ordinal comparison. * @@ -2107,6 +2189,8 @@ export function equateValues(a: T, b: T) { * value of each code-point after applying `toUpperCase` to each string. We always map both * strings to their upper-case form as some unicode characters do not properly round-trip to * lowercase (such as `ẞ` (German sharp capital s)). + * + * @internal */ export function equateStringsCaseInsensitive(a: string, b: string) { return a === b @@ -2115,12 +2199,13 @@ export function equateStringsCaseInsensitive(a: string, b: string) { && a.toUpperCase() === b.toUpperCase(); } -/** @internal */ /** * Compare the equality of two strings using a case-sensitive ordinal comparison. * * Case-sensitive comparisons compare both strings one code-point at a time using the * integer value of each code-point. + * + * @internal */ export function equateStringsCaseSensitive(a: string, b: string) { return equateValues(a, b); @@ -2136,18 +2221,20 @@ function compareComparableValues(a: string | number | undefined, b: string | num Comparison.GreaterThan; } -/** @internal */ /** * Compare two numeric values for their order relative to each other. * To compare strings, use any of the `compareStrings` functions. + * + * @internal */ export function compareValues(a: number | undefined, b: number | undefined): Comparison { return compareComparableValues(a, b); } -/** @internal */ /** * Compare two TextSpans, first by `start`, then by `length`. + * + * @internal */ export function compareTextSpans(a: Partial | undefined, b: Partial | undefined): Comparison { return compareValues(a?.start, b?.start) || compareValues(a?.length, b?.length); @@ -2162,7 +2249,6 @@ export function min(items: readonly T[], compare: Comparer): T | undefined return reduceLeft(items, (x, y) => compare(x, y) === Comparison.LessThan ? x : y); } -/** @internal */ /** * Compare two strings using a case-insensitive ordinal comparison. * @@ -2174,6 +2260,8 @@ export function min(items: readonly T[], compare: Comparer): T | undefined * value of each code-point after applying `toUpperCase` to each string. We always map both * strings to their upper-case form as some unicode characters do not properly round-trip to * lowercase (such as `ẞ` (German sharp capital s)). + * + * @internal */ export function compareStringsCaseInsensitive(a: string, b: string) { if (a === b) return Comparison.EqualTo; @@ -2184,7 +2272,6 @@ export function compareStringsCaseInsensitive(a: string, b: string) { return a < b ? Comparison.LessThan : a > b ? Comparison.GreaterThan : Comparison.EqualTo; } -/** @internal */ /** * Compare two strings using a case-sensitive ordinal comparison. * @@ -2194,6 +2281,8 @@ export function compareStringsCaseInsensitive(a: string, b: string) { * * Case-sensitive comparisons compare both strings one code-point at a time using the integer * value of each code-point. + * + * @internal */ export function compareStringsCaseSensitive(a: string | undefined, b: string | undefined): Comparison { return compareComparableValues(a, b); @@ -2308,7 +2397,6 @@ export function setUILocale(value: string | undefined) { } } -/** @internal */ /** * Compare two strings in a using the case-sensitive sort behavior of the UI locale. * @@ -2318,6 +2406,8 @@ export function setUILocale(value: string | undefined) { * * Case-sensitive comparisons compare strings that differ in base characters, or * accents/diacritic marks, or case as unequal. + * + * @internal */ export function compareStringsCaseSensitiveUI(a: string, b: string) { const comparer = uiComparerCaseSensitive || (uiComparerCaseSensitive = createUIStringComparer(uiLocale)); @@ -2332,13 +2422,16 @@ export function compareProperties(a: T | un comparer(a[key], b[key]); } -/** @internal */ -/** True is greater than false. */ + +/** + * True is greater than false. + * + * @internal + */ export function compareBooleans(a: boolean, b: boolean): Comparison { return compareValues(a ? 1 : 0, b ? 1 : 0); } -/** @internal */ /** * Given a name and a list of names that are *not* equal to the name, return a spelling suggestion if there is one that is close enough. * Names less than length 3 only check for case-insensitive equality. @@ -2350,6 +2443,8 @@ export function compareBooleans(a: boolean, b: boolean): Comparison { * * Whose levenshtein distance is more than 0.4 of the length of the name * (0.4 allows 1 substitution/transposition for every 5 characters, * and 1 insertion/deletion at 3 characters) + * + * @internal */ export function getSpellingSuggestion(name: string, candidates: T[], getName: (candidate: T) => string | undefined): T | undefined { const maximumLengthDifference = Math.max(2, Math.floor(name.length * 0.34)); @@ -2449,9 +2544,10 @@ export function stringContains(str: string, substring: string): boolean { return str.indexOf(substring) !== -1; } -/** @internal */ /** * Takes a string like "jquery-min.4.2.3" and returns "jquery" + * + * @internal */ export function removeMinAndVersionNumbers(fileName: string) { // We used to use the regex /[.-]((min)|(\d+(\.\d+)*))$/ and would just .replace it twice. @@ -2501,8 +2597,11 @@ export function removeMinAndVersionNumbers(fileName: string) { return end === fileName.length ? fileName : fileName.slice(0, end); } -/** @internal */ -/** Remove an item from an array, moving everything to its right one space left. */ +/** + * Remove an item from an array, moving everything to its right one space left. + * + * @internal + */ export function orderedRemoveItem(array: T[], item: T): boolean { for (let i = 0; i < array.length; i++) { if (array[i] === item) { @@ -2513,8 +2612,11 @@ export function orderedRemoveItem(array: T[], item: T): boolean { return false; } -/** @internal */ -/** Remove an item by index from an array, moving everything to its right one space left. */ +/** + * Remove an item by index from an array, moving everything to its right one space left. + * + * @internal + */ export function orderedRemoveItemAt(array: T[], index: number): void { // This seems to be faster than either `array.splice(i, 1)` or `array.copyWithin(i, i+ 1)`. for (let i = index; i < array.length - 1; i++) { @@ -2530,8 +2632,11 @@ export function unorderedRemoveItemAt(array: T[], index: number): void { array.pop(); } -/** @internal */ -/** Remove the *first* occurrence of `item` from the array. */ +/** + * Remove the *first* occurrence of `item` from the array. + * + * @internal + */ export function unorderedRemoveItem(array: T[], item: T) { return unorderedRemoveFirstItemWhere(array, element => element === item); } @@ -2554,8 +2659,11 @@ export function createGetCanonicalFileName(useCaseSensitiveFileNames: boolean): return useCaseSensitiveFileNames ? identity : toFileNameLowerCase; } -/** @internal */ -/** Represents a "prefix*suffix" pattern. */ +/** + * Represents a "prefix*suffix" pattern. + * + * @internal + */ export interface Pattern { prefix: string; suffix: string; @@ -2566,18 +2674,22 @@ export function patternText({ prefix, suffix }: Pattern): string { return `${prefix}*${suffix}`; } -/** @internal */ /** * Given that candidate matches pattern, returns the text matching the '*'. * E.g.: matchedText(tryParsePattern("foo*baz"), "foobarbaz") === "bar" + * + * @internal */ export function matchedText(pattern: Pattern, candidate: string): string { Debug.assert(isPatternMatch(pattern, candidate)); return candidate.substring(pattern.prefix.length, candidate.length - pattern.suffix.length); } -/** @internal */ -/** Return the object corresponding to the best pattern to match `candidate`. */ +/** + * Return the object corresponding to the best pattern to match `candidate`. + * + * @internal + */ export function findBestPatternMatch(values: readonly T[], getPattern: (value: T) => Pattern, candidate: string): T | undefined { let matchedValue: T | undefined; // use length of prefix as betterness criteria @@ -2729,25 +2841,27 @@ function cartesianProductWorker(arrays: readonly (readonly T[])[], result: (r } -/** @internal */ /** * Returns string left-padded with spaces or zeros until it reaches the given length. * * @param s String to pad. * @param length Final padded length. If less than or equal to 's.length', returns 's' unchanged. * @param padString Character to use as padding (default " "). + * + * @internal */ export function padLeft(s: string, length: number, padString: " " | "0" = " ") { return length <= s.length ? s : padString.repeat(length - s.length) + s; } -/** @internal */ /** * Returns string right-padded with spaces until it reaches the given length. * * @param s String to pad. * @param length Final padded length. If less than or equal to 's.length', returns 's' unchanged. * @param padString Character to use as padding (default " "). + * + * @internal */ export function padRight(s: string, length: number, padString: " " = " ") { return length <= s.length ? s : s + padString.repeat(length - s.length); @@ -2765,21 +2879,24 @@ export function takeWhile(array: readonly T[], predicate: (element: T) => boo return array.slice(0, index); } -/** @internal */ /** * Removes the leading and trailing white space and line terminator characters from a string. + * + * @internal */ export const trimString = !!String.prototype.trim ? ((s: string) => s.trim()) : (s: string) => trimStringEnd(trimStringStart(s)); -/** @internal */ /** * Returns a copy with trailing whitespace removed. + * + * @internal */ export const trimStringEnd = !!String.prototype.trimEnd ? ((s: string) => s.trimEnd()) : trimEndImpl; -/** @internal */ /** * Returns a copy with leading whitespace removed. + * + * @internal */ export const trimStringStart = !!String.prototype.trimStart ? ((s: string) => s.trimStart()) : (s: string) => s.replace(/^\s+/g, ""); diff --git a/src/compiler/corePublic.ts b/src/compiler/corePublic.ts index 0727cf392e1c9..aa0933e9e6e60 100644 --- a/src/compiler/corePublic.ts +++ b/src/compiler/corePublic.ts @@ -61,7 +61,7 @@ export interface ESMap extends ReadonlyESMap, Collection { export interface Map extends ESMap { } -/* @internal */ +/** @internal */ export interface MapConstructor { // eslint-disable-next-line @typescript-eslint/prefer-function-type new (iterable?: readonly (readonly [K, V])[] | ReadonlyESMap): ESMap; @@ -81,7 +81,7 @@ export interface Set extends ReadonlySet, Collection { delete(value: T): boolean; } -/* @internal */ +/** @internal */ export interface SetConstructor { // eslint-disable-next-line @typescript-eslint/prefer-function-type new (iterable?: readonly T[] | ReadonlySet): Set; @@ -95,23 +95,23 @@ export interface Iterator { /** Array that is only intended to be pushed to, never read. */ export interface Push { push(...values: T[]): void; - /* @internal*/ readonly length: number; + /** @internal */ readonly length: number; } -/* @internal */ +/** @internal */ export type EqualityComparer = (a: T, b: T) => boolean; -/* @internal */ +/** @internal */ export type Comparer = (a: T, b: T) => Comparison; -/* @internal */ +/** @internal */ export const enum Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 } -/* @internal */ +/** @internal */ namespace NativeCollections { declare const self: any; @@ -149,7 +149,7 @@ namespace NativeCollections { } } -/* @internal */ +/** @internal */ export const Map = NativeCollections.tryGetNativeMap(); -/* @internal */ +/** @internal */ export const Set = NativeCollections.tryGetNativeSet(); diff --git a/src/compiler/emitter.ts b/src/compiler/emitter.ts index 60e33b2eecdd3..1e29552d98f39 100644 --- a/src/compiler/emitter.ts +++ b/src/compiler/emitter.ts @@ -82,12 +82,11 @@ import { const brackets = createBracketsMap(); -/*@internal*/ +/** @internal */ export function isBuildInfoFile(file: string) { return fileExtensionIs(file, Extension.TsBuildInfo); } -/*@internal*/ /** * Iterates over the source files that are expected to have an emit output. * @@ -96,6 +95,8 @@ export function isBuildInfoFile(file: string) { * @param sourceFilesOrTargetSourceFile * If an array, the full list of source files to emit. * Else, calls `getSourceFilesToEmit` with the (optional) target source file to determine the list of source files to emit. + * + * @internal */ export function forEachEmittedFile( host: EmitHost, action: (emitFileNames: EmitFileNames, sourceFileOrBundle: SourceFile | Bundle | undefined) => T, @@ -152,7 +153,7 @@ export function getTsBuildInfoEmitOutputFilePath(options: CompilerOptions) { return buildInfoExtensionLess + Extension.TsBuildInfo; } -/*@internal*/ +/** @internal */ export function getOutputPathsForBundle(options: CompilerOptions, forceDtsPaths: boolean): EmitFileNames { const outPath = outFile(options)!; const jsFilePath = options.emitDeclarationOnly ? undefined : outPath; @@ -163,7 +164,7 @@ export function getOutputPathsForBundle(options: CompilerOptions, forceDtsPaths: return { jsFilePath, sourceMapFilePath, declarationFilePath, declarationMapPath, buildInfoPath }; } -/*@internal*/ +/** @internal */ export function getOutputPathsFor(sourceFile: SourceFile | Bundle, host: EmitHost, forceDtsPaths: boolean): EmitFileNames { const options = host.getCompilerOptions(); if (sourceFile.kind === SyntaxKind.Bundle) { @@ -187,7 +188,7 @@ function getSourceMapFilePath(jsFilePath: string, options: CompilerOptions) { return (options.sourceMap && !options.inlineSourceMap) ? jsFilePath + ".map" : undefined; } -/* @internal */ +/** @internal */ export function getOutputExtension(fileName: string, options: CompilerOptions): Extension { return fileExtensionIs(fileName, Extension.Json) ? Extension.Json : options.jsx === JsxEmit.Preserve && fileExtensionIsOneOf(fileName, [Extension.Jsx, Extension.Tsx]) ? Extension.Jsx : @@ -205,7 +206,7 @@ function getOutputPathWithoutChangingExt(inputFileName: string, configFile: Pars inputFileName; } -/* @internal */ +/** @internal */ export function getOutputDeclarationFileName(inputFileName: string, configFile: ParsedCommandLine, ignoreCase: boolean, getCommonSourceDirectory?: () => string) { return changeExtension( getOutputPathWithoutChangingExt(inputFileName, configFile, ignoreCase, configFile.options.declarationDir || configFile.options.outDir, getCommonSourceDirectory), @@ -264,7 +265,7 @@ function getOwnOutputFileNames(configFile: ParsedCommandLine, inputFileName: str } } -/*@internal*/ +/** @internal */ export function getCommonSourceDirectory( options: CompilerOptions, emittedFiles: () => readonly string[], @@ -296,7 +297,7 @@ export function getCommonSourceDirectory( return commonSourceDirectory; } -/*@internal*/ +/** @internal */ export function getCommonSourceDirectoryOfConfig({ options, fileNames }: ParsedCommandLine, ignoreCase: boolean): string { return getCommonSourceDirectory( options, @@ -306,7 +307,7 @@ export function getCommonSourceDirectoryOfConfig({ options, fileNames }: ParsedC ); } -/*@internal*/ +/** @internal */ export function getAllProjectOutputs(configFile: ParsedCommandLine, ignoreCase: boolean): readonly string[] { const { addOutput, getOutputs } = createAddOutput(); if (outFile(configFile.options)) { @@ -335,7 +336,7 @@ export function getOutputFileNames(commandLine: ParsedCommandLine, inputFileName return getOutputs(); } -/*@internal*/ +/** @internal */ export function getFirstProjectOutput(configFile: ParsedCommandLine, ignoreCase: boolean): string { if (outFile(configFile.options)) { const { jsFilePath, declarationFilePath } = getOutputPathsForBundle(configFile.options, /*forceDtsPaths*/ false); @@ -357,7 +358,7 @@ export function getFirstProjectOutput(configFile: ParsedCommandLine, ignoreCase: return Debug.fail(`project ${configFile.options.configFilePath} expected to have at least one output`); } -/*@internal*/ +/** @internal */ // targetSourceFile is when users only want one file in entire project to be emitted. This is used in compileOnSave feature export function emitFiles(resolver: EmitResolver, host: EmitHost, targetSourceFile: SourceFile | undefined, { scriptTransformers, declarationTransformers }: EmitTransformers, emitOnly?: boolean | EmitOnly, onlyBuildInfo?: boolean, forceDtsEmit?: boolean): EmitResult { const compilerOptions = host.getCompilerOptions(); @@ -727,23 +728,23 @@ export function emitFiles(resolver: EmitResolver, host: EmitHost, targetSourceFi } } -/*@internal*/ +/** @internal */ export function createBuildInfo(program: ProgramBuildInfo | undefined, bundle: BundleBuildInfo | undefined): BuildInfo { const version = ts.version; // Extracted into a const so the form is stable between namespace and module return { bundle, program, version }; } -/*@internal*/ +/** @internal */ export function getBuildInfoText(buildInfo: BuildInfo) { return JSON.stringify(buildInfo); } -/*@internal*/ +/** @internal */ export function getBuildInfo(buildInfoFile: string, buildInfoText: string) { return readJsonOrUndefined(buildInfoFile, buildInfoText) as BuildInfo | undefined; } -/*@internal*/ +/** @internal */ export const notImplementedResolver: EmitResolver = { hasGlobalName: notImplemented, getReferencedExportContainer: notImplemented, @@ -788,8 +789,11 @@ export const notImplementedResolver: EmitResolver = { isImportRequiredByAugmentation: notImplemented, }; -/*@internal*/ -/** File that isnt present resulting in error or output files */ +/** + * File that isnt present resulting in error or output files + * + * @internal + */ export type EmitUsingBuildInfoResult = string | readonly OutputFile[]; function createSourceFilesFromBundleBuildInfo(bundle: BundleBuildInfo, buildInfoDirectory: string, host: CompilerHost): readonly SourceFile[] { @@ -819,7 +823,7 @@ function createSourceFilesFromBundleBuildInfo(bundle: BundleBuildInfo, buildInfo }); } -/*@internal*/ +/** @internal */ export function emitUsingBuildInfo( config: ParsedCommandLine, host: CompilerHost, diff --git a/src/compiler/factory/baseNodeFactory.ts b/src/compiler/factory/baseNodeFactory.ts index 782cee7ea73b0..39b9490fba770 100644 --- a/src/compiler/factory/baseNodeFactory.ts +++ b/src/compiler/factory/baseNodeFactory.ts @@ -3,8 +3,9 @@ import { Node, objectAllocator, SyntaxKind } from "../_namespaces/ts"; /** * A `BaseNodeFactory` is an abstraction over an `ObjectAllocator` that handles caching `Node` constructors * and allocating `Node` instances based on a set of predefined types. + * + * @internal */ -/* @internal */ export interface BaseNodeFactory { createBaseSourceFileNode(kind: SyntaxKind): Node; createBaseIdentifierNode(kind: SyntaxKind): Node; @@ -13,9 +14,10 @@ export interface BaseNodeFactory { createBaseNode(kind: SyntaxKind): Node; } -/** @internal */ /** * Creates a `BaseNodeFactory` which can be used to create `Node` instances from the constructors provided by the object allocator. + * + * @internal */ export function createBaseNodeFactory(): BaseNodeFactory { let NodeConstructor: new (kind: SyntaxKind, pos?: number, end?: number) => Node; diff --git a/src/compiler/factory/emitHelpers.ts b/src/compiler/factory/emitHelpers.ts index 6b05b1c72a7e6..8783c52b767f4 100644 --- a/src/compiler/factory/emitHelpers.ts +++ b/src/compiler/factory/emitHelpers.ts @@ -412,7 +412,7 @@ export function createEmitHelperFactory(context: TransformationContext): EmitHel } } -/* @internal */ +/** @internal */ export function compareEmitHelpers(x: EmitHelper, y: EmitHelper) { if (x === y) return Comparison.EqualTo; if (x.priority === y.priority) return Comparison.EqualTo; @@ -421,10 +421,11 @@ export function compareEmitHelpers(x: EmitHelper, y: EmitHelper) { return compareValues(x.priority, y.priority); } -/** @internal */ /** * @param input Template string input strings * @param args Names which need to be made file-level unique + * + * @internal */ export function helperString(input: TemplateStringsArray, ...args: string[]) { return (uniqueName: EmitHelperUniqueNameCallback) => { @@ -880,7 +881,6 @@ export const exportStarHelper: UnscopedEmitHelper = { };` }; -/** @internal */ /** * Parameters: * @param receiver — The object from which the private member will be read. @@ -928,6 +928,8 @@ export const exportStarHelper: UnscopedEmitHelper = { * * Reading from a private static method (TS 4.3+): * __classPrivateFieldGet(, , "m", ) + * + * @internal */ export const classPrivateFieldGetHelper: UnscopedEmitHelper = { name: "typescript:classPrivateFieldGet", @@ -941,7 +943,6 @@ export const classPrivateFieldGetHelper: UnscopedEmitHelper = { };` }; -/** @internal */ /** * Parameters: * @param receiver — The object on which the private member will be set. @@ -992,6 +993,8 @@ export const classPrivateFieldGetHelper: UnscopedEmitHelper = { * Writing to a private static method (TS 4.3+): * __classPrivateFieldSet(, , , "m", ) * NOTE: This always results in a runtime error. + * + * @internal */ export const classPrivateFieldSetHelper: UnscopedEmitHelper = { name: "typescript:classPrivateFieldSet", @@ -1006,7 +1009,6 @@ export const classPrivateFieldSetHelper: UnscopedEmitHelper = { };` }; -/** @internal */ /** * Parameters: * @param state — One of the following: @@ -1018,6 +1020,8 @@ export const classPrivateFieldSetHelper: UnscopedEmitHelper = { * Usage: * This helper is used to transform `#field in expression` to * `__classPrivateFieldIn(, expression)` + * + * @internal */ export const classPrivateFieldInHelper: UnscopedEmitHelper = { name: "typescript:classPrivateFieldIn", diff --git a/src/compiler/factory/emitNode.ts b/src/compiler/factory/emitNode.ts index 44717059b4ada..693094489a67e 100644 --- a/src/compiler/factory/emitNode.ts +++ b/src/compiler/factory/emitNode.ts @@ -72,8 +72,9 @@ export function setEmitFlags(node: T, emitFlags: EmitFlags) { /** * Sets flags that control emit behavior of a node. + * + * @internal */ -/* @internal */ export function addEmitFlags(node: T, emitFlags: EmitFlags) { const emitNode = getOrCreateEmitNode(node); emitNode.flags = emitNode.flags | emitFlags; @@ -114,16 +115,18 @@ export function setTokenSourceMapRange(node: T, token: SyntaxKin /** * Gets a custom text range to use when emitting comments. + * + * @internal */ -/*@internal*/ export function getStartsOnNewLine(node: Node) { return node.emitNode?.startsOnNewLine; } /** * Sets a custom text range to use when emitting comments. + * + * @internal */ -/*@internal*/ export function setStartsOnNewLine(node: T, newLine: boolean) { getOrCreateEmitNode(node).startsOnNewLine = newLine; return node; @@ -263,36 +266,38 @@ export function moveEmitHelpers(source: Node, target: Node, predicate: (helper: /** * Gets the SnippetElement of a node. + * + * @internal */ -/* @internal */ export function getSnippetElement(node: Node): SnippetElement | undefined { return node.emitNode?.snippetElement; } /** * Sets the SnippetElement of a node. + * + * @internal */ -/* @internal */ export function setSnippetElement(node: T, snippet: SnippetElement): T { const emitNode = getOrCreateEmitNode(node); emitNode.snippetElement = snippet; return node; } -/* @internal */ +/** @internal */ export function ignoreSourceNewlines(node: T): T { getOrCreateEmitNode(node).flags |= EmitFlags.IgnoreSourceNewlines; return node; } -/* @internal */ +/** @internal */ export function setTypeNode(node: T, type: TypeNode): T { const emitNode = getOrCreateEmitNode(node); emitNode.typeNode = type; return node; } -/* @internal */ +/** @internal */ export function getTypeNode(node: T): TypeNode | undefined { return node.emitNode?.typeNode; } diff --git a/src/compiler/factory/nodeConverters.ts b/src/compiler/factory/nodeConverters.ts index 3efb85e75e3f1..74cddf31527b5 100644 --- a/src/compiler/factory/nodeConverters.ts +++ b/src/compiler/factory/nodeConverters.ts @@ -142,4 +142,4 @@ export const nullNodeConverters: NodeConverters = { convertToObjectAssignmentPattern: notImplemented, convertToArrayAssignmentPattern: notImplemented, convertToAssignmentElementTarget: notImplemented, -}; \ No newline at end of file +}; diff --git a/src/compiler/factory/nodeFactory.ts b/src/compiler/factory/nodeFactory.ts index 55f96780e730d..f2f111efb22c1 100644 --- a/src/compiler/factory/nodeFactory.ts +++ b/src/compiler/factory/nodeFactory.ts @@ -82,7 +82,7 @@ import { let nextAutoGenerateId = 0; -/* @internal */ +/** @internal */ export const enum NodeFactoryFlags { None = 0, // Disables the parenthesizer rules for the factory. @@ -97,7 +97,7 @@ export const enum NodeFactoryFlags { const nodeFactoryPatchers: ((factory: NodeFactory) => void)[] = []; -/* @internal */ +/** @internal */ export function addNodeFactoryPatcher(fn: (factory: NodeFactory) => void) { nodeFactoryPatchers.push(fn); } @@ -106,8 +106,9 @@ export function addNodeFactoryPatcher(fn: (factory: NodeFactory) => void) { * Creates a `NodeFactory` that can be used to create and update a syntax tree. * @param flags Flags that control factory behavior. * @param baseFactory A `BaseNodeFactory` used to create the base `Node` objects. + * + * @internal */ -/* @internal */ export function createNodeFactory(flags: NodeFactoryFlags, baseFactory: BaseNodeFactory): NodeFactory { const update = flags & NodeFactoryFlags.NoOriginalNode ? updateWithoutOriginal : updateWithOriginal; @@ -6565,8 +6566,9 @@ function aggregateChildrenFlags(children: MutableNodeArray) { /** * Gets the transform flags to exclude when unioning the transform flags of a subtree. + * + * @internal */ -/* @internal */ export function getTransformFlagsSubtreeExclusions(kind: SyntaxKind) { if (kind >= SyntaxKind.FirstTypeNode && kind <= SyntaxKind.LastTypeNode) { return TransformFlags.TypeExcludes; @@ -6876,7 +6878,7 @@ export function createInputFiles( declarationMapTextOrBuildInfoPath, ); } -/*@internal*/ +/** @internal */ export function createInputFilesWithFilePaths( readFileText: (path: string) => string | undefined, javascriptPath: string, @@ -6929,7 +6931,7 @@ export function createInputFilesWithFilePaths( }); return node; } -/*@internal*/ +/** @internal */ export function createInputFilesWithFileTexts( javascriptPath: string | undefined, javascriptText: string, diff --git a/src/compiler/factory/nodeTests.ts b/src/compiler/factory/nodeTests.ts index 172b7d332a9c4..f391dbb1edb59 100644 --- a/src/compiler/factory/nodeTests.ts +++ b/src/compiler/factory/nodeTests.ts @@ -85,7 +85,7 @@ export function isDotDotDotToken(node: Node): node is DotDotDotToken { return node.kind === SyntaxKind.DotDotDotToken; } -/*@internal*/ +/** @internal */ export function isCommaToken(node: Node): node is Token { return node.kind === SyntaxKind.CommaToken; } @@ -102,27 +102,27 @@ export function isAsteriskToken(node: Node): node is AsteriskToken { return node.kind === SyntaxKind.AsteriskToken; } -/*@internal*/ +/** @internal */ export function isExclamationToken(node: Node): node is ExclamationToken { return node.kind === SyntaxKind.ExclamationToken; } -/*@internal*/ +/** @internal */ export function isQuestionToken(node: Node): node is QuestionToken { return node.kind === SyntaxKind.QuestionToken; } -/*@internal*/ +/** @internal */ export function isColonToken(node: Node): node is ColonToken { return node.kind === SyntaxKind.ColonToken; } -/*@internal*/ +/** @internal */ export function isQuestionDotToken(node: Node): node is QuestionDotToken { return node.kind === SyntaxKind.QuestionDotToken; } -/*@internal*/ +/** @internal */ export function isEqualsGreaterThanToken(node: Node): node is EqualsGreaterThanToken { return node.kind === SyntaxKind.EqualsGreaterThanToken; } @@ -139,57 +139,57 @@ export function isPrivateIdentifier(node: Node): node is PrivateIdentifier { // Reserved Words -/* @internal */ +/** @internal */ export function isExportModifier(node: Node): node is ExportKeyword { return node.kind === SyntaxKind.ExportKeyword; } -/* @internal */ +/** @internal */ export function isAsyncModifier(node: Node): node is AsyncKeyword { return node.kind === SyntaxKind.AsyncKeyword; } -/* @internal */ +/** @internal */ export function isAssertsKeyword(node: Node): node is AssertsKeyword { return node.kind === SyntaxKind.AssertsKeyword; } -/* @internal */ +/** @internal */ export function isAwaitKeyword(node: Node): node is AwaitKeyword { return node.kind === SyntaxKind.AwaitKeyword; } -/* @internal */ +/** @internal */ export function isReadonlyKeyword(node: Node): node is ReadonlyKeyword { return node.kind === SyntaxKind.ReadonlyKeyword; } -/* @internal */ +/** @internal */ export function isStaticModifier(node: Node): node is StaticKeyword { return node.kind === SyntaxKind.StaticKeyword; } -/* @internal */ +/** @internal */ export function isAbstractModifier(node: Node): node is AbstractKeyword { return node.kind === SyntaxKind.AbstractKeyword; } -/* @internal */ +/** @internal */ export function isOverrideModifier(node: Node): node is OverrideKeyword { return node.kind === SyntaxKind.OverrideKeyword; } -/* @internal */ +/** @internal */ export function isAccessorModifier(node: Node): node is AccessorKeyword { return node.kind === SyntaxKind.AccessorKeyword; } -/*@internal*/ +/** @internal */ export function isSuperKeyword(node: Node): node is SuperExpression { return node.kind === SyntaxKind.SuperKeyword; } -/*@internal*/ +/** @internal */ export function isImportKeyword(node: Node): node is ImportExpression { return node.kind === SyntaxKind.ImportKeyword; } @@ -703,17 +703,17 @@ export function isNotEmittedStatement(node: Node): node is NotEmittedStatement { return node.kind === SyntaxKind.NotEmittedStatement; } -/* @internal */ +/** @internal */ export function isSyntheticReference(node: Node): node is SyntheticReferenceExpression { return node.kind === SyntaxKind.SyntheticReferenceExpression; } -/* @internal */ +/** @internal */ export function isMergeDeclarationMarker(node: Node): node is MergeDeclarationMarker { return node.kind === SyntaxKind.MergeDeclarationMarker; } -/* @internal */ +/** @internal */ export function isEndOfDeclarationMarker(node: Node): node is EndOfDeclarationMarker { return node.kind === SyntaxKind.EndOfDeclarationMarker; } @@ -993,7 +993,7 @@ export function isJSDocImplementsTag(node: Node): node is JSDocImplementsTag { // Synthesized list -/* @internal */ +/** @internal */ export function isSyntaxList(n: Node): n is SyntaxList { return n.kind === SyntaxKind.SyntaxList; } diff --git a/src/compiler/factory/utilities.ts b/src/compiler/factory/utilities.ts index e04d06a40651c..010b996d7ab10 100644 --- a/src/compiler/factory/utilities.ts +++ b/src/compiler/factory/utilities.ts @@ -343,7 +343,6 @@ export function createExpressionForObjectLiteralElementLike(factory: NodeFactory } } -/** @internal */ /** * Expand the read and increment/decrement operations a pre- or post-increment or pre- or post-decrement expression. * @@ -375,6 +374,8 @@ export function createExpressionForObjectLiteralElementLike(factory: NodeFactory * @param node The original prefix or postfix unary node. * @param expression The expression to use as the value to increment or decrement * @param resultVariable A temporary variable in which to store the result. Pass `undefined` if the result is discarded, or if the value of `` is the expected result. + * + * @internal */ export function expandPreOrPostfixIncrementOrDecrementExpression(factory: NodeFactory, node: PrefixUnaryExpression | PostfixUnaryExpression, expression: Expression, recordTempVariable: (node: Identifier) => void, resultVariable: Identifier | undefined) { const operator = node.operator; @@ -405,26 +406,29 @@ export function expandPreOrPostfixIncrementOrDecrementExpression(factory: NodeFa return expression; } -/** @internal */ /** * Gets whether an identifier should only be referred to by its internal name. + * + * @internal */ export function isInternalName(node: Identifier) { return (getEmitFlags(node) & EmitFlags.InternalName) !== 0; } -/** @internal */ /** * Gets whether an identifier should only be referred to by its local name. + * + * @internal */ export function isLocalName(node: Identifier) { return (getEmitFlags(node) & EmitFlags.LocalName) !== 0; } -/** @internal */ /** * Gets whether an identifier should only be referred to by its export representation if the * name points to an exported symbol. + * + * @internal */ export function isExportName(node: Identifier) { return (getEmitFlags(node) & EmitFlags.ExportName) !== 0; @@ -623,9 +627,10 @@ export function getOrCreateExternalHelpersModuleNameIfNeeded(factory: NodeFactor } } -/** @internal */ /** * Get the name of that target module from an import or export declaration + * + * @internal */ export function getLocalNameForExternalImport(factory: NodeFactory, node: ImportDeclaration | ExportDeclaration | ImportEqualsDeclaration, sourceFile: SourceFile): Identifier | undefined { const namespaceDeclaration = getNamespaceDeclarationNode(node); @@ -642,7 +647,6 @@ export function getLocalNameForExternalImport(factory: NodeFactory, node: Import return undefined; } -/** @internal */ /** * Get the name of a target module from an import/export declaration as should be written in the emitted output. * The emitted output name can be different from the input if: @@ -650,6 +654,8 @@ export function getLocalNameForExternalImport(factory: NodeFactory, node: Import * 2. --out or --outFile is used, making the name relative to the rootDir * 3- The containing SourceFile has an entry in renamedDependencies for the import as requested by some module loaders (e.g. System). * Otherwise, a new StringLiteral node representing the module name will be returned. + * + * @internal */ export function getExternalModuleNameLiteral(factory: NodeFactory, importNode: ImportDeclaration | ExportDeclaration | ImportEqualsDeclaration | ImportCall, sourceFile: SourceFile, host: EmitHost, resolver: EmitResolver, compilerOptions: CompilerOptions) { const moduleName = getExternalModuleName(importNode); @@ -671,13 +677,14 @@ function tryRenameExternalModule(factory: NodeFactory, moduleName: LiteralExpres return rename ? factory.createStringLiteral(rename) : undefined; } -/** @internal */ /** * Get the name of a module as should be written in the emitted output. * The emitted output name can be different from the input if: * 1. The module has a /// * 2. --out or --outFile is used, making the name relative to the rootDir * Otherwise, a new StringLiteral node representing the module name will be returned. + * + * @internal */ export function tryGetModuleNameFromFile(factory: NodeFactory, file: SourceFile | undefined, host: EmitHost, options: CompilerOptions): StringLiteral | undefined { if (!file) { @@ -696,9 +703,10 @@ function tryGetModuleNameFromDeclaration(declaration: ImportEqualsDeclaration | return tryGetModuleNameFromFile(factory, resolver.getExternalModuleFileFromDeclaration(declaration), host, compilerOptions); } -/** @internal */ /** * Gets the initializer of an BindingOrAssignmentElement. + * + * @internal */ export function getInitializerOfBindingOrAssignmentElement(bindingElement: BindingOrAssignmentElement): Expression | undefined { if (isDeclarationBindingElement(bindingElement)) { @@ -740,9 +748,10 @@ export function getInitializerOfBindingOrAssignmentElement(bindingElement: Bindi } } -/** @internal */ /** * Gets the name of an BindingOrAssignmentElement. + * + * @internal */ export function getTargetOfBindingOrAssignmentElement(bindingElement: BindingOrAssignmentElement): BindingOrAssignmentElementTarget | undefined { if (isDeclarationBindingElement(bindingElement)) { @@ -816,9 +825,10 @@ export function getTargetOfBindingOrAssignmentElement(bindingElement: BindingOrA return bindingElement; } -/** @internal */ /** * Determines whether an BindingOrAssignmentElement is a rest element. + * + * @internal */ export function getRestIndicatorOfBindingOrAssignmentElement(bindingElement: BindingOrAssignmentElement): BindingOrAssignmentElementRestIndicator | undefined { switch (bindingElement.kind) { @@ -836,9 +846,10 @@ export function getRestIndicatorOfBindingOrAssignmentElement(bindingElement: Bin return undefined; } -/** @internal */ /** * Gets the property name of a BindingOrAssignmentElement + * + * @internal */ export function getPropertyNameOfBindingOrAssignmentElement(bindingElement: BindingOrAssignmentElement): Exclude | undefined { const propertyName = tryGetPropertyNameOfBindingOrAssignmentElement(bindingElement); @@ -903,9 +914,10 @@ function isStringOrNumericLiteral(node: Node): node is StringLiteral | NumericLi || kind === SyntaxKind.NumericLiteral; } -/** @internal */ /** * Gets the elements of a BindingOrAssignmentPattern + * + * @internal */ export function getElementsOfBindingOrAssignmentPattern(name: BindingOrAssignmentPattern): readonly BindingOrAssignmentElement[] { switch (name.kind) { @@ -922,7 +934,7 @@ export function getElementsOfBindingOrAssignmentPattern(name: BindingOrAssignmen } } -/* @internal */ +/** @internal */ export function getJSDocTypeAliasName(fullName: JSDocNamespaceBody | undefined) { if (fullName) { let rightNode = fullName; @@ -1256,7 +1268,6 @@ class BinaryExpressionStateMachine { } } -/** @internal */ /** * Creates a state machine that walks a `BinaryExpression` using the heap to reduce call-stack depth on a large tree. * @param onEnter Callback evaluated when entering a `BinaryExpression`. Returns new user-defined state to associate with the node while walking. @@ -1265,6 +1276,8 @@ class BinaryExpressionStateMachine { * @param onExit Callback evaluated when exiting a `BinaryExpression`. The result returned will either be folded into the parent's state, or returned from the walker if at the top frame. * @param foldState Callback evaluated when the result from a nested `onExit` should be folded into the state of that node's parent. * @returns A function that walks a `BinaryExpression` node using the above callbacks, returning the result of the call to `onExit` from the outermost `BinaryExpression` node. + * + * @internal */ export function createBinaryExpressionTrampoline( onEnter: (node: BinaryExpression, prev: TState | undefined) => TState, @@ -1274,7 +1287,6 @@ class BinaryExpressionStateMachine { onExit: (node: BinaryExpression, userState: TState) => TResult, foldState: ((userState: TState, result: TResult, side: "left" | "right") => TState) | undefined, ): (node: BinaryExpression) => TResult; -/** @internal */ /** * Creates a state machine that walks a `BinaryExpression` using the heap to reduce call-stack depth on a large tree. * @param onEnter Callback evaluated when entering a `BinaryExpression`. Returns new user-defined state to associate with the node while walking. @@ -1283,6 +1295,8 @@ class BinaryExpressionStateMachine { * @param onExit Callback evaluated when exiting a `BinaryExpression`. The result returned will either be folded into the parent's state, or returned from the walker if at the top frame. * @param foldState Callback evaluated when the result from a nested `onExit` should be folded into the state of that node's parent. * @returns A function that walks a `BinaryExpression` node using the above callbacks, returning the result of the call to `onExit` from the outermost `BinaryExpression` node. + * + * @internal */ export function createBinaryExpressionTrampoline( onEnter: (node: BinaryExpression, prev: TState | undefined, outerState: TOuterState) => TState, @@ -1332,9 +1346,10 @@ export function elideNodes(factory: NodeFactory, nodes: NodeArra return setTextRange(factory.createNodeArray([], nodes.hasTrailingComma), nodes); } -/** @internal */ /** * Gets the node from which a name should be generated. + * + * @internal */ export function getNodeForGeneratedName(name: GeneratedIdentifier | GeneratedPrivateIdentifier) { if (name.autoGenerateFlags & GeneratedIdentifierFlags.Node) { @@ -1359,14 +1374,16 @@ export function getNodeForGeneratedName(name: GeneratedIdentifier | GeneratedPri return name; } -/** @internal */ /** * Formats a prefix or suffix of a generated name. + * + * @internal */ export function formatGeneratedNamePart(part: string | undefined): string; -/** @internal */ /** * Formats a prefix or suffix of a generated name. If the part is a {@link GeneratedNamePart}, calls {@link generateName} to format the source node. + * + * @internal */ export function formatGeneratedNamePart(part: string | GeneratedNamePart | undefined, generateName: (name: GeneratedIdentifier | GeneratedPrivateIdentifier) => string): string; /** @internal */ @@ -1388,16 +1405,16 @@ function formatIdentifierWorker(node: Identifier | PrivateIdentifier, generateNa idText(node); } -/** @internal */ /** * Formats a generated name. * @param privateName When `true`, inserts a `#` character at the start of the result. * @param prefix The prefix (if any) to include before the base name. * @param baseName The base name for the generated name. * @param suffix The suffix (if any) to include after the base name. + * + * @internal */ export function formatGeneratedName(privateName: boolean, prefix: string | undefined, baseName: string, suffix: string | undefined): string; -/** @internal */ /** * Formats a generated name. * @param privateName When `true`, inserts a `#` character at the start of the result. @@ -1405,6 +1422,8 @@ export function formatGeneratedName(privateName: boolean, prefix: string | undef * @param baseName The base name for the generated name. * @param suffix The suffix (if any) to include after the base name. * @param generateName Called to format the source node of {@link prefix} when it is a {@link GeneratedNamePart}. + * + * @internal */ export function formatGeneratedName(privateName: boolean, prefix: string | GeneratedNamePart | undefined, baseName: string | Identifier | PrivateIdentifier, suffix: string | GeneratedNamePart | undefined, generateName: (name: GeneratedIdentifier | GeneratedPrivateIdentifier) => string): string; /** @internal */ @@ -1416,9 +1435,10 @@ export function formatGeneratedName(privateName: boolean, prefix: string | Gener } -/** @internal */ /** * Creates a private backing field for an `accessor` {@link PropertyDeclaration}. + * + * @internal */ export function createAccessorPropertyBackingField(factory: NodeFactory, node: PropertyDeclaration, modifiers: ModifiersArray | undefined, initializer: Expression | undefined) { return factory.updatePropertyDeclaration( @@ -1431,9 +1451,10 @@ export function createAccessorPropertyBackingField(factory: NodeFactory, node: P ); } -/** @internal */ /** * Creates a {@link GetAccessorDeclaration} that reads from a private backing field. + * + * @internal */ export function createAccessorPropertyGetRedirector(factory: NodeFactory, node: PropertyDeclaration, modifiers: ModifiersArray | undefined, name: PropertyName) { return factory.createGetAccessorDeclaration( @@ -1452,9 +1473,10 @@ export function createAccessorPropertyGetRedirector(factory: NodeFactory, node: ); } -/** @internal */ /** * Creates a {@link SetAccessorDeclaration} that writes to a private backing field. + * + * @internal */ export function createAccessorPropertySetRedirector(factory: NodeFactory, node: PropertyDeclaration, modifiers: ModifiersArray | undefined, name: PropertyName) { return factory.createSetAccessorDeclaration( diff --git a/src/compiler/moduleNameResolver.ts b/src/compiler/moduleNameResolver.ts index f3dae4caab765..7ef6fd8ec57a4 100644 --- a/src/compiler/moduleNameResolver.ts +++ b/src/compiler/moduleNameResolver.ts @@ -19,13 +19,13 @@ import { tryParsePatterns, tryRemoveExtension, version, Version, versionMajorMinor, VersionRange, } from "./_namespaces/ts"; -/* @internal */ +/** @internal */ export function trace(host: ModuleResolutionHost, message: DiagnosticMessage, ...args: any[]): void; export function trace(host: ModuleResolutionHost): void { host.trace!(formatMessage.apply(undefined, arguments)); } -/* @internal */ +/** @internal */ export function isTraceEnabled(compilerOptions: CompilerOptions, host: ModuleResolutionHost): boolean { return !!compilerOptions.traceResolution && host.trace !== undefined; } @@ -127,7 +127,7 @@ function createResolvedModuleWithFailedLookupLocations( }; } -/*@internal*/ +/** @internal */ interface ModuleResolutionState { host: ModuleResolutionHost; compilerOptions: CompilerOptions; @@ -142,8 +142,10 @@ interface ModuleResolutionState { reportDiagnostic: DiagnosticReporter; } -/** Just the fields that we use for module resolution. */ -/*@internal*/ +/** Just the fields that we use for module resolution. + * + * @internal + */ interface PackageJsonPathFields { typings?: string; types?: string; @@ -223,7 +225,7 @@ function readPackageJsonTypesVersionsField(jsonContent: PackageJson, state: Modu return typesVersions; } -/*@internal*/ +/** @internal */ interface VersionPaths { version: string; paths: MapLike; @@ -262,7 +264,7 @@ function readPackageJsonTypesVersionPaths(jsonContent: PackageJson, state: Modul let typeScriptVersion: Version | undefined; -/* @internal */ +/** @internal */ export function getPackageJsonTypesVersionsPaths(typesVersions: MapLike>) { if (!typeScriptVersion) typeScriptVersion = new Version(version); @@ -565,7 +567,7 @@ export function getAutomaticTypeDirectiveNames(options: CompilerOptions, host: M } export interface TypeReferenceDirectiveResolutionCache extends PerDirectoryResolutionCache, PackageJsonInfoCache { - /*@internal*/ clearAllExceptPackageJsonInfoCache(): void; + /** @internal */ clearAllExceptPackageJsonInfoCache(): void; } export interface ModeAwareCache { @@ -593,7 +595,7 @@ export interface PerDirectoryResolutionCache { export interface ModuleResolutionCache extends PerDirectoryResolutionCache, NonRelativeModuleNameResolutionCache, PackageJsonInfoCache { getPackageJsonInfoCache(): PackageJsonInfoCache; - /*@internal*/ clearAllExceptPackageJsonInfoCache(): void; + /** @internal */ clearAllExceptPackageJsonInfoCache(): void; } /** @@ -605,10 +607,10 @@ export interface NonRelativeModuleNameResolutionCache extends PackageJsonInfoCac } export interface PackageJsonInfoCache { - /*@internal*/ getPackageJsonInfo(packageJsonPath: string): PackageJsonInfo | boolean | undefined; - /*@internal*/ setPackageJsonInfo(packageJsonPath: string, info: PackageJsonInfo | boolean): void; - /*@internal*/ entries(): [Path, PackageJsonInfo | boolean][]; - /*@internal*/ getInternalMap(): ESMap | undefined; + /** @internal */ getPackageJsonInfo(packageJsonPath: string): PackageJsonInfo | boolean | undefined; + /** @internal */ setPackageJsonInfo(packageJsonPath: string, info: PackageJsonInfo | boolean): void; + /** @internal */ entries(): [Path, PackageJsonInfo | boolean][]; + /** @internal */ getInternalMap(): ESMap | undefined; clear(): void; } @@ -617,7 +619,7 @@ export interface PerModuleNameCache { set(directory: string, result: ResolvedModuleWithFailedLookupLocations): void; } -/*@internal*/ +/** @internal */ export interface CacheWithRedirects { getOwnMap: () => ESMap; redirectsMap: ESMap>; @@ -627,7 +629,7 @@ export interface CacheWithRedirects { setOwnMap(newOwnMap: ESMap): void; } -/*@internal*/ +/** @internal */ export function createCacheWithRedirects(options?: CompilerOptions): CacheWithRedirects { let ownMap: ESMap = new Map(); const redirectsMap = new Map>(); @@ -752,7 +754,7 @@ function createPerDirectoryResolutionCache(currentDirectory: string, getCanon } } -/* @internal */ +/** @internal */ export function createModeAwareCache(): ModeAwareCache { const underlying = new Map(); type ModeAwareCacheKey = string & { __modeAwareCacheKey: any; }; @@ -792,18 +794,18 @@ export function createModeAwareCache(): ModeAwareCache { } } -/* @internal */ +/** @internal */ export function getResolutionName(entry: FileReference | StringLiteralLike) { // We lower-case all type references because npm automatically lowercases all packages. See GH#9824. return isStringLiteralLike(entry) ? entry.text : entry.fileName.toLowerCase(); } -/* @internal */ +/** @internal */ export function getResolutionMode(entry: FileReference | StringLiteralLike, file: SourceFile) { return isStringLiteralLike(entry) ? getModeForUsageLocation(file, entry) : entry.resolutionMode || file.impliedNodeFormat; } -/* @internal */ +/** @internal */ export function zipToModeAwareCache(file: SourceFile, keys: readonly StringLiteralLike[] | readonly FileReference[], values: readonly V[]): ModeAwareCache { Debug.assert(keys.length === values.length); const map = createModeAwareCache(); @@ -819,7 +821,7 @@ export function createModuleResolutionCache( getCanonicalFileName: (s: string) => string, options?: CompilerOptions ): ModuleResolutionCache; -/*@internal*/ +/** @internal */ export function createModuleResolutionCache( currentDirectory: string, getCanonicalFileName: GetCanonicalFileName, @@ -946,7 +948,7 @@ export function createTypeReferenceDirectiveResolutionCache( options?: CompilerOptions, packageJsonInfoCache?: PackageJsonInfoCache, ): TypeReferenceDirectiveResolutionCache; -/*@internal*/ +/** @internal */ export function createTypeReferenceDirectiveResolutionCache( currentDirectory: string, getCanonicalFileName: GetCanonicalFileName, @@ -1276,8 +1278,9 @@ function tryLoadModuleUsingBaseUrl(extensions: Extensions, moduleName: string, l * Expose resolution logic to allow us to use Node module resolution logic from arbitrary locations. * No way to do this with `require()`: https://github.com/nodejs/node/issues/5963 * Throws an error if the module can't be resolved. + * + * @internal */ -/* @internal */ export function resolveJSModule(moduleName: string, initialDir: string, host: ModuleResolutionHost): string { const { resolvedModule, failedLookupLocations } = tryResolveJSModuleWorker(moduleName, initialDir, host); if (!resolvedModule) { @@ -1286,7 +1289,7 @@ export function resolveJSModule(moduleName: string, initialDir: string, host: Mo return resolvedModule.resolvedFileName; } -/* @internal */ +/** @internal */ enum NodeResolutionFeatures { None = 0, // resolving `#local` names in your own package.json @@ -1358,7 +1361,7 @@ function tryResolveJSModuleWorker(moduleName: string, initialDir: string, host: } export function nodeModuleNameResolver(moduleName: string, containingFile: string, compilerOptions: CompilerOptions, host: ModuleResolutionHost, cache?: ModuleResolutionCache, redirectedReference?: ResolvedProjectReference): ResolvedModuleWithFailedLookupLocations; -/* @internal */ export function nodeModuleNameResolver(moduleName: string, containingFile: string, compilerOptions: CompilerOptions, host: ModuleResolutionHost, cache?: ModuleResolutionCache, redirectedReference?: ResolvedProjectReference, lookupConfig?: boolean): ResolvedModuleWithFailedLookupLocations; // eslint-disable-line @typescript-eslint/unified-signatures +/** @internal */ export function nodeModuleNameResolver(moduleName: string, containingFile: string, compilerOptions: CompilerOptions, host: ModuleResolutionHost, cache?: ModuleResolutionCache, redirectedReference?: ResolvedProjectReference, lookupConfig?: boolean): ResolvedModuleWithFailedLookupLocations; // eslint-disable-line @typescript-eslint/unified-signatures export function nodeModuleNameResolver(moduleName: string, containingFile: string, compilerOptions: CompilerOptions, host: ModuleResolutionHost, cache?: ModuleResolutionCache, redirectedReference?: ResolvedProjectReference, lookupConfig?: boolean): ResolvedModuleWithFailedLookupLocations { let extensions; if (lookupConfig) { @@ -1524,9 +1527,9 @@ function nodeLoadModuleByRelativeName(extensions: Extensions, candidate: string, return undefined; } -/*@internal*/ +/** @internal */ export const nodeModulesPathPart = "/node_modules/"; -/*@internal*/ +/** @internal */ export function pathContainsNodeModules(path: string): boolean { return stringContains(path, nodeModulesPathPart); } @@ -1540,8 +1543,9 @@ export function pathContainsNodeModules(path: string): boolean { * For `/node_modules/foo/bar.d.ts` this is packageDirectory: "foo" * For `/node_modules/@types/foo/bar/index.d.ts` this is packageDirectory: "@types/foo" * For `/node_modules/foo/bar/index.d.ts` this is packageDirectory: "foo" + * + * @internal */ -/* @internal */ export function parseNodeModuleFromPath(resolved: string): string | undefined { const path = normalizePath(resolved); const idx = path.lastIndexOf(nodeModulesPathPart); @@ -1717,7 +1721,7 @@ function loadNodeModuleFromDirectory(extensions: Extensions, candidate: string, return withPackageId(packageInfo, loadNodeModuleFromDirectoryWorker(extensions, candidate, onlyRecordFailures, state, packageJsonContent, versionPaths)); } -/* @internal */ +/** @internal */ export function getEntrypointsFromPackageJsonInfo( packageJsonInfo: PackageJsonInfo, options: CompilerOptions, @@ -1822,7 +1826,7 @@ function loadEntrypointsFromExportMap( } } -/*@internal*/ +/** @internal */ export function getTemporaryModuleResolutionState(packageJsonInfoCache: PackageJsonInfoCache | undefined, host: ModuleResolutionHost, options: CompilerOptions): ModuleResolutionState { return { host, @@ -1838,12 +1842,12 @@ export function getTemporaryModuleResolutionState(packageJsonInfoCache: PackageJ }; } -/*@internal*/ +/** @internal */ export interface PackageJsonInfo { packageDirectory: string; contents: PackageJsonInfoContents; } -/*@internal*/ +/** @internal */ export interface PackageJsonInfoContents { packageJsonContent: PackageJsonPathFields; versionPaths: VersionPaths | undefined; @@ -1853,8 +1857,9 @@ export interface PackageJsonInfoContents { /** * A function for locating the package.json scope for a given path + * + * @internal */ -/*@internal*/ export function getPackageScopeForPath(fileName: string, state: ModuleResolutionState): PackageJsonInfo | undefined { const parts = getPathComponents(fileName); parts.pop(); @@ -1868,7 +1873,7 @@ export interface PackageJsonInfoContents { return undefined; } -/*@internal*/ +/** @internal */ export function getPackageJsonInfo(packageDirectory: string, onlyRecordFailures: boolean, state: ModuleResolutionState): PackageJsonInfo | undefined { const { host, traceEnabled } = state; const packageJsonPath = combinePaths(packageDirectory, "package.json"); @@ -2014,7 +2019,7 @@ function extensionIsOk(extensions: Extensions, extension: Extension): boolean { } } -/* @internal */ +/** @internal */ export function parsePackageName(moduleName: string): { packageName: string, rest: string } { let idx = moduleName.indexOf(directorySeparator); if (moduleName[0] === "@") { @@ -2023,7 +2028,7 @@ export function parsePackageName(moduleName: string): { packageName: string, res return idx === -1 ? { packageName: moduleName, rest: "" } : { packageName: moduleName.slice(0, idx), rest: moduleName.slice(idx + 1) }; } -/* @internal */ +/** @internal */ export function allKeysStartWithDot(obj: MapLike) { return every(getOwnKeys(obj), k => startsWith(k, ".")); } @@ -2404,7 +2409,7 @@ function getLoadModuleFromTargetImportOrExport(extensions: Extensions, state: Mo } } -/* @internal */ +/** @internal */ export function isApplicableVersionedTypesKey(conditions: readonly string[], key: string) { if (conditions.indexOf("types") === -1) return false; // only apply versioned types conditions if the types condition is applied if (!startsWith(key, "types@")) return false; @@ -2574,12 +2579,12 @@ function mangleScopedPackageNameWithTrace(packageName: string, state: ModuleReso return mangled; } -/* @internal */ +/** @internal */ export function getTypesPackageName(packageName: string): string { return `@types/${mangleScopedPackageName(packageName)}`; } -/* @internal */ +/** @internal */ export function mangleScopedPackageName(packageName: string): string { if (startsWith(packageName, "@")) { const replaceSlash = packageName.replace(directorySeparator, mangledScopedPackageSeparator); @@ -2590,7 +2595,7 @@ export function mangleScopedPackageName(packageName: string): string { return packageName; } -/* @internal */ +/** @internal */ export function getPackageNameFromTypesPackageName(mangledName: string): string { const withoutAtTypePrefix = removePrefix(mangledName, "@types/"); if (withoutAtTypePrefix !== mangledName) { @@ -2599,7 +2604,7 @@ export function getPackageNameFromTypesPackageName(mangledName: string): string return mangledName; } -/* @internal */ +/** @internal */ export function unmangleScopedPackageName(typesPackageName: string): string { return stringContains(typesPackageName, mangledScopedPackageSeparator) ? "@" + typesPackageName.replace(mangledScopedPackageSeparator, directorySeparator) : @@ -2681,8 +2686,9 @@ export function classicNameResolver(moduleName: string, containingFile: string, /** * A host may load a module from a global cache of typings. * This is the minumum code needed to expose that functionality; the rest is in the host. + * + * @internal */ -/* @internal */ export function loadModuleFromGlobalCache(moduleName: string, projectName: string | undefined, compilerOptions: CompilerOptions, host: ModuleResolutionHost, globalCache: string, packageJsonInfoCache: PackageJsonInfoCache): ResolvedModuleWithFailedLookupLocations { const traceEnabled = isTraceEnabled(compilerOptions, host); if (traceEnabled) { diff --git a/src/compiler/moduleSpecifiers.ts b/src/compiler/moduleSpecifiers.ts index 27075cf9e4577..b6ddd551cf9c6 100644 --- a/src/compiler/moduleSpecifiers.ts +++ b/src/compiler/moduleSpecifiers.ts @@ -180,8 +180,11 @@ function tryGetModuleSpecifiersFromCacheWorker( return [cached?.moduleSpecifiers, moduleSourceFile, cached?.modulePaths, cache]; } -/** @internal */ -/** Returns an import for each symlink and for the realpath. */ +/** + * Returns an import for each symlink and for the realpath. + * + * @internal + */ export function getModuleSpecifiers( moduleSymbol: Symbol, checker: TypeChecker, diff --git a/src/compiler/parser.ts b/src/compiler/parser.ts index 2701742cf3f2a..f26231d59137f 100644 --- a/src/compiler/parser.ts +++ b/src/compiler/parser.ts @@ -89,8 +89,9 @@ let SourceFileConstructor: new (kind: SyntaxKind, pos?: number, end?: number) => /** * NOTE: You should not use this, it is only exported to support `createNode` in `~/src/deprecatedCompat/deprecations.ts`. + * + * @internal */ -/* @internal */ export const parseBaseNodeFactory: BaseNodeFactory = { createBaseSourceFileNode: kind => new (SourceFileConstructor || (SourceFileConstructor = objectAllocator.getSourceFileConstructor()))(kind, -1, -1), createBaseIdentifierNode: kind => new (IdentifierConstructor || (IdentifierConstructor = objectAllocator.getIdentifierConstructor()))(kind, -1, -1), @@ -99,7 +100,7 @@ export const parseBaseNodeFactory: BaseNodeFactory = { createBaseNode: kind => new (NodeConstructor || (NodeConstructor = objectAllocator.getNodeConstructor()))(kind, -1, -1), }; -/* @internal */ +/** @internal */ export const parseNodeFactory = createNodeFactory(NodeFactoryFlags.NoParenthesizerRules, parseBaseNodeFactory); function visitNode(cbNode: (node: Node) => T, node: Node | undefined): T | undefined { @@ -120,14 +121,14 @@ function visitNodes(cbNode: (node: Node) => T, cbNodes: ((node: NodeArray(node: Node, cbNode: (node: Node) => T | undefine return fn === undefined ? undefined : fn(node, cbNode, cbNodes); } -/** @internal */ /** * Invokes a callback for each child of the given node. The 'cbNode' callback is invoked for all child nodes * stored in properties. If a 'cbNodes' callback is specified, it is invoked for embedded arrays; additionally, @@ -929,6 +929,8 @@ export function forEachChild(node: Node, cbNode: (node: Node) => T | undefine * * @remarks Unlike `forEachChild`, `forEachChildRecursively` handles recursively invoking the traversal on each child node found, * and while doing so, handles traversing the structure without relying on the callstack to encode the tree structure. + * + * @internal */ export function forEachChildRecursively(rootNode: Node, cbNode: (node: Node, parent: Node) => T | "skip" | undefined, cbNodes?: (nodes: NodeArray, parent: Node) => T | "skip" | undefined): T | undefined { const queue: (Node | NodeArray)[] = gatherPossibleChildren(rootNode); @@ -993,8 +995,8 @@ export interface CreateSourceFileOptions { * check specified by `isFileProbablyExternalModule` will be used to set the field. */ setExternalModuleIndicator?: (file: SourceFile) => void; - /*@internal*/ packageJsonLocations?: readonly string[]; - /*@internal*/ packageJsonScope?: PackageJsonInfo; + /** @internal */ packageJsonLocations?: readonly string[]; + /** @internal */ packageJsonScope?: PackageJsonInfo; } function setExternalModuleIndicator(sourceFile: SourceFile) { @@ -1065,7 +1067,7 @@ export function updateSourceFile(sourceFile: SourceFile, newText: string, textCh return newSourceFile; } -/* @internal */ +/** @internal */ export function parseIsolatedJSDocComment(content: string, start?: number, length?: number) { const result = Parser.JSDocParser.parseIsolatedJSDocComment(content, start, length); if (result && result.jsDoc) { @@ -1077,7 +1079,7 @@ export function parseIsolatedJSDocComment(content: string, start?: number, lengt return result; } -/* @internal */ +/** @internal */ // Exposed only for testing. export function parseJSDocTypeExpressionForTests(content: string, start?: number, length?: number) { return Parser.JSDocParser.parseJSDocTypeExpressionForTests(content, start, length); @@ -9775,7 +9777,7 @@ export function isDeclarationFileName(fileName: string): boolean { return fileExtensionIsOneOf(fileName, supportedDeclarationExtensions); } -/*@internal*/ +/** @internal */ export interface PragmaContext { languageVersion: ScriptTarget; pragmas?: PragmaMap; @@ -9802,7 +9804,7 @@ function parseResolutionMode(mode: string | undefined, pos: number, end: number, return undefined; } -/*@internal*/ +/** @internal */ export function processCommentPragmas(context: PragmaContext, sourceText: string): void { const pragmas: PragmaPseudoMapEntry[] = []; @@ -9827,10 +9829,10 @@ export function processCommentPragmas(context: PragmaContext, sourceText: string } } -/*@internal*/ +/** @internal */ type PragmaDiagnosticReporter = (pos: number, length: number, message: DiagnosticMessage) => void; -/*@internal*/ +/** @internal */ export function processPragmasIntoFields(context: PragmaContext, reportDiagnostic: PragmaDiagnosticReporter): void { context.checkJsDirective = undefined; context.referencedFiles = []; diff --git a/src/compiler/path.ts b/src/compiler/path.ts index 6bdb17f88ad3f..7f84ae19c6a9b 100644 --- a/src/compiler/path.ts +++ b/src/compiler/path.ts @@ -4,11 +4,12 @@ import { identity, lastOrUndefined, Path, some, startsWith, stringContains, } from "./_namespaces/ts"; -/** @internal */ /** * Internally, we represent paths as strings with '/' as the directory separator. * When we make system calls (eg: LanguageServiceHost.getDirectory()), * we expect the host to correctly handle paths in our specified format. + * + * @internal */ export const directorySeparator = "/"; /** @internal */ @@ -18,41 +19,44 @@ const backslashRegExp = /\\/g; //// Path Tests -/** @internal */ /** * Determines whether a charCode corresponds to `/` or `\`. + * + * @internal */ export function isAnyDirectorySeparator(charCode: number): boolean { return charCode === CharacterCodes.slash || charCode === CharacterCodes.backslash; } -/** @internal */ /** * Determines whether a path starts with a URL scheme (e.g. starts with `http://`, `ftp://`, `file://`, etc.). + * + * @internal */ export function isUrl(path: string) { return getEncodedRootLength(path) < 0; } -/** @internal */ /** * Determines whether a path is an absolute disk path (e.g. starts with `/`, or a dos path * like `c:`, `c:\` or `c:/`). + * + * @internal */ export function isRootedDiskPath(path: string) { return getEncodedRootLength(path) > 0; } -/** @internal */ /** * Determines whether a path consists only of a path root. + * + * @internal */ export function isDiskPathRoot(path: string) { const rootLength = getEncodedRootLength(path); return rootLength > 0 && rootLength === path.length; } -/** @internal */ /** * Determines whether a path starts with an absolute path component (i.e. `/`, `c:/`, `file://`, etc.). * @@ -67,23 +71,27 @@ export function isDiskPathRoot(path: string) { * pathIsAbsolute("path/to/file.ext") === false * pathIsAbsolute("./path/to/file.ext") === false * ``` + * + * @internal */ export function pathIsAbsolute(path: string): boolean { return getEncodedRootLength(path) !== 0; } -/** @internal */ /** * Determines whether a path starts with a relative path component (i.e. `.` or `..`). + * + * @internal */ export function pathIsRelative(path: string): boolean { return /^\.\.?($|[\\/])/.test(path); } -/** @internal */ /** * Determines whether a path is neither relative nor absolute, e.g. "path/to/file". * Also known misleadingly as "non-relative". + * + * @internal */ export function pathIsBareSpecifier(path: string): boolean { return !pathIsAbsolute(path) && !pathIsRelative(path); @@ -110,9 +118,10 @@ export function fileExtensionIsOneOf(path: string, extensions: readonly string[] return false; } -/** @internal */ /** * Determines whether a path has a trailing separator (`/` or `\\`). + * + * @internal */ export function hasTrailingDirectorySeparator(path: string) { return path.length > 0 && isAnyDirectorySeparator(path.charCodeAt(path.length - 1)); @@ -195,7 +204,6 @@ function getEncodedRootLength(path: string): number { return 0; } -/** @internal */ /** * Returns length of the root part of a path or URL (i.e. length of "/", "x:/", "//server/share/, file:///user/files"). * @@ -220,13 +228,14 @@ function getEncodedRootLength(path: string): number { * getRootLength("http://server") === 13 // "http://server" * getRootLength("http://server/path") === 14 // "http://server/" * ``` + * + * @internal */ export function getRootLength(path: string) { const rootLength = getEncodedRootLength(path); return rootLength < 0 ? ~rootLength : rootLength; } -/** @internal */ /** * Returns the path except for its basename. Semantics align with NodeJS's `path.dirname` * except that we support URLs as well. @@ -247,9 +256,10 @@ export function getRootLength(path: string) { * getDirectoryPath("http://typescriptlang.org/") === "http://typescriptlang.org/" * getDirectoryPath("http://typescriptlang.org") === "http://typescriptlang.org" * ``` + * + * @internal */ export function getDirectoryPath(path: Path): Path; -/** @internal */ /** * Returns the path except for its basename. Semantics align with NodeJS's `path.dirname` * except that we support URLs as well. @@ -278,6 +288,8 @@ export function getDirectoryPath(path: Path): Path; * getDirectoryPath("file:///") === "file:///" * getDirectoryPath("file://") === "file://" * ``` + * + * @internal */ export function getDirectoryPath(path: string): string; /** @internal */ @@ -294,7 +306,6 @@ export function getDirectoryPath(path: string): string { return path.slice(0, Math.max(rootLength, path.lastIndexOf(directorySeparator))); } -/** @internal */ /** * Returns the path except for its containing directory name. * Semantics align with NodeJS's `path.basename` except that we support URL's as well. @@ -323,9 +334,10 @@ export function getDirectoryPath(path: string): string { * getBaseFileName("file:///") === "" * getBaseFileName("file://") === "" * ``` + * + * @internal */ export function getBaseFileName(path: string): string; -/** @internal */ /** * Gets the portion of a path following the last (non-terminal) separator (`/`). * Semantics align with NodeJS's `path.basename` except that we support URL's as well. @@ -337,6 +349,8 @@ export function getBaseFileName(path: string): string; * getBaseFileName("/path/to/file.js", [".ext", ".js"], true) === "file" * getBaseFileName("/path/to/file.ext", ".EXT", false) === "file.ext" * ``` + * + * @internal */ export function getBaseFileName(path: string, extensions: string | readonly string[], ignoreCase: boolean): string; /** @internal */ @@ -376,7 +390,6 @@ function getAnyExtensionFromPathWorker(path: string, extensions: string | readon return ""; } -/** @internal */ /** * Gets the file extension for a path. * @@ -386,9 +399,10 @@ function getAnyExtensionFromPathWorker(path: string, extensions: string | readon * getAnyExtensionFromPath("/path/to/file") === "" * getAnyExtensionFromPath("/path/to.ext/file") === "" * ``` + * + * @internal */ export function getAnyExtensionFromPath(path: string): string; -/** @internal */ /** * Gets the file extension for a path, provided it is one of the provided extensions. * @@ -397,6 +411,8 @@ export function getAnyExtensionFromPath(path: string): string; * getAnyExtensionFromPath("/path/to/file.js", ".ext", true) === "" * getAnyExtensionFromPath("/path/to/file.js", [".ext", ".js"], true) === ".js" * getAnyExtensionFromPath("/path/to/file.ext", ".EXT", false) === "" + * + * @internal */ export function getAnyExtensionFromPath(path: string, extensions: string | readonly string[], ignoreCase: boolean): string; /** @internal */ @@ -421,7 +437,6 @@ function pathComponents(path: string, rootLength: number) { return [root, ...rest]; } -/** @internal */ /** * Parse a path into an array containing a root component (at index 0) and zero or more path * components (at indices > 0). The result is not normalized. @@ -451,6 +466,9 @@ function pathComponents(path: string, rootLength: number) { * getPathComponents("file:///path/to/") === ["file:///", "path", "to"] * getPathComponents("file:///") === ["file:///"] * getPathComponents("file://") === ["file://"] + * ``` + * + * @internal */ export function getPathComponents(path: string, currentDirectory = "") { path = combinePaths(currentDirectory, path); @@ -459,7 +477,6 @@ export function getPathComponents(path: string, currentDirectory = "") { //// Path Formatting -/** @internal */ /** * Formats a parsed path consisting of a root component (at index 0) and zero or more path * segments (at indices > 0). @@ -467,6 +484,8 @@ export function getPathComponents(path: string, currentDirectory = "") { * ```ts * getPathFromPathComponents(["/", "path", "to", "file.ext"]) === "/path/to/file.ext" * ``` + * + * @internal */ export function getPathFromPathComponents(pathComponents: readonly string[]) { if (pathComponents.length === 0) return ""; @@ -477,9 +496,10 @@ export function getPathFromPathComponents(pathComponents: readonly string[]) { //// Path Normalization -/** @internal */ /** * Normalize path separators, converting `\` into `/`. + * + * @internal */ export function normalizeSlashes(path: string): string { return path.indexOf("\\") !== -1 @@ -487,10 +507,11 @@ export function normalizeSlashes(path: string): string { : path; } -/** @internal */ /** * Reduce an array of path components to a more simplified path by navigating any * `"."` or `".."` entries in the path. + * + * @internal */ export function reducePathComponents(components: readonly string[]) { if (!some(components)) return []; @@ -513,7 +534,6 @@ export function reducePathComponents(components: readonly string[]) { return reduced; } -/** @internal */ /** * Combines paths. If a path is absolute, it replaces any previous path. Relative paths are not simplified. * @@ -531,6 +551,8 @@ export function reducePathComponents(components: readonly string[]) { * combinePaths("file:///path", "to", "file.ext") === "file:///path/to/file.ext" * combinePaths("file:///path", "file:///to", "file.ext") === "file:///to/file.ext" * ``` + * + * @internal */ export function combinePaths(path: string, ...paths: (string | undefined)[]): string { if (path) path = normalizeSlashes(path); @@ -547,7 +569,6 @@ export function combinePaths(path: string, ...paths: (string | undefined)[]): st return path; } -/** @internal */ /** * Combines and resolves paths. If a path is absolute, it replaces any previous path. Any * `.` and `..` path components are resolved. Trailing directory separators are preserved. @@ -557,12 +578,13 @@ export function combinePaths(path: string, ...paths: (string | undefined)[]): st * resolvePath("/path", "to", "file.ext/") === "path/to/file.ext/" * resolvePath("/path", "dir", "..", "to", "file.ext") === "path/to/file.ext" * ``` + * + * @internal */ export function resolvePath(path: string, ...paths: (string | undefined)[]): string { return normalizePath(some(paths) ? combinePaths(path, ...paths) : normalizeSlashes(path)); } -/** @internal */ /** * Parse a path into an array containing a root component (at index 0) and zero or more path * components (at indices > 0). The result is normalized. @@ -572,6 +594,8 @@ export function resolvePath(path: string, ...paths: (string | undefined)[]): str * ```ts * getNormalizedPathComponents("to/dir/../file.ext", "/path/") === ["/", "path", "to", "file.ext"] * ``` + * + * @internal */ export function getNormalizedPathComponents(path: string, currentDirectory: string | undefined) { return reducePathComponents(getPathComponents(path, currentDirectory)); @@ -622,7 +646,6 @@ export function toPath(fileName: string, basePath: string | undefined, getCanoni //// Path Mutation -/** @internal */ /** * Removes a trailing directory separator from a path, if it does not already have one. * @@ -630,6 +653,8 @@ export function toPath(fileName: string, basePath: string | undefined, getCanoni * removeTrailingDirectorySeparator("/path/to/file.ext") === "/path/to/file.ext" * removeTrailingDirectorySeparator("/path/to/file.ext/") === "/path/to/file.ext" * ``` + * + * @internal */ export function removeTrailingDirectorySeparator(path: Path): Path; /** @internal */ @@ -643,7 +668,6 @@ export function removeTrailingDirectorySeparator(path: string) { return path; } -/** @internal */ /** * Adds a trailing directory separator to a path, if it does not already have one. * @@ -651,6 +675,8 @@ export function removeTrailingDirectorySeparator(path: string) { * ensureTrailingDirectorySeparator("/path/to/file.ext") === "/path/to/file.ext/" * ensureTrailingDirectorySeparator("/path/to/file.ext/") === "/path/to/file.ext/" * ``` + * + * @internal */ export function ensureTrailingDirectorySeparator(path: Path): Path; /** @internal */ @@ -664,7 +690,6 @@ export function ensureTrailingDirectorySeparator(path: string) { return path; } -/** @internal */ /** * Ensures a path is either absolute (prefixed with `/` or `c:`) or dot-relative (prefixed * with `./` or `../`) so as not to be confused with an unprefixed module name. @@ -675,21 +700,23 @@ export function ensureTrailingDirectorySeparator(path: string) { * ensurePathIsNonModuleName("../path/to/file.ext") === "../path/to/file.ext" * ensurePathIsNonModuleName("path/to/file.ext") === "./path/to/file.ext" * ``` + * + * @internal */ export function ensurePathIsNonModuleName(path: string): string { return !pathIsAbsolute(path) && !pathIsRelative(path) ? "./" + path : path; } -/** @internal */ /** * Changes the extension of a path to the provided extension. * * ```ts * changeAnyExtension("/path/to/file.ext", ".js") === "/path/to/file.js" * ``` + * + * @internal */ export function changeAnyExtension(path: string, ext: string): string; -/** @internal */ /** * Changes the extension of a path to the provided extension if it has one of the provided extensions. * @@ -698,6 +725,8 @@ export function changeAnyExtension(path: string, ext: string): string; * changeAnyExtension("/path/to/file.ext", ".js", ".ts") === "/path/to/file.ext" * changeAnyExtension("/path/to/file.ext", ".js", [".ext", ".ts"]) === "/path/to/file.js" * ``` + * + * @internal */ export function changeAnyExtension(path: string, ext: string, extensions: string | readonly string[], ignoreCase: boolean): string; /** @internal */ @@ -747,25 +776,28 @@ function comparePathsWorker(a: string, b: string, componentComparer: (a: string, return compareValues(aComponents.length, bComponents.length); } -/** @internal */ /** * Performs a case-sensitive comparison of two paths. Path roots are always compared case-insensitively. + * + * @internal */ export function comparePathsCaseSensitive(a: string, b: string) { return comparePathsWorker(a, b, compareStringsCaseSensitive); } -/** @internal */ /** * Performs a case-insensitive comparison of two paths. + * + * @internal */ export function comparePathsCaseInsensitive(a: string, b: string) { return comparePathsWorker(a, b, compareStringsCaseInsensitive); } -/** @internal */ /** * Compare two paths using the provided case sensitivity. + * + * @internal */ export function comparePaths(a: string, b: string, ignoreCase?: boolean): Comparison; /** @internal */ @@ -782,9 +814,10 @@ export function comparePaths(a: string, b: string, currentDirectory?: string | b return comparePathsWorker(a, b, getStringComparer(ignoreCase)); } -/** @internal */ /** * Determines whether a `parent` path contains a `child` path using the provide case sensitivity. + * + * @internal */ export function containsPath(parent: string, child: string, ignoreCase?: boolean): boolean; /** @internal */ @@ -817,12 +850,13 @@ export function containsPath(parent: string, child: string, currentDirectory?: s return true; } -/** @internal */ /** * Determines whether `fileName` starts with the specified `directoryName` using the provided path canonicalization callback. * Comparison is case-sensitive between the canonical paths. * * Use `containsPath` if file names are not already reduced and absolute. + * + * @internal */ export function startsWithDirectory(fileName: string, directoryName: string, getCanonicalFileName: GetCanonicalFileName): boolean { const canonicalFileName = getCanonicalFileName(fileName); @@ -857,14 +891,16 @@ export function getPathComponentsRelativeTo(from: string, to: string, stringEqua return ["", ...relative, ...components]; } -/** @internal */ /** * Gets a relative path that can be used to traverse between `from` and `to`. + * + * @internal */ export function getRelativePathFromDirectory(from: string, to: string, ignoreCase: boolean): string; -/** @internal */ /** * Gets a relative path that can be used to traverse between `from` and `to`. + * + * @internal */ export function getRelativePathFromDirectory(fromDirectory: string, to: string, getCanonicalFileName: GetCanonicalFileName): string; // eslint-disable-line @typescript-eslint/unified-signatures /** @internal */ @@ -908,9 +944,10 @@ export function getRelativePathToDirectoryOrUrl(directoryPathOrUrl: string, rela //// Path Traversal -/** @internal */ /** * Calls `callback` on `directory` and every ancestor directory it has, returning the first defined result. + * + * @internal */ export function forEachAncestorDirectory(directory: Path, callback: (directory: Path) => T | undefined): T | undefined; /** @internal */ diff --git a/src/compiler/perfLogger.ts b/src/compiler/perfLogger.ts index eb225b9ce4904..34a59208d68f0 100644 --- a/src/compiler/perfLogger.ts +++ b/src/compiler/perfLogger.ts @@ -38,6 +38,9 @@ catch (e) { etwModule = undefined; } -/** @internal */ -/** Performance logger that will generate ETW events if possible - check for `logEvent` member, as `etwModule` will be `{}` when browserified */ +/** + * Performance logger that will generate ETW events if possible - check for `logEvent` member, as `etwModule` will be `{}` when browserified + * + * @internal + */ export const perfLogger: PerfLogger = etwModule && etwModule.logEvent ? etwModule : nullLogger; diff --git a/src/compiler/performance.ts b/src/compiler/performance.ts index 859dab41340b7..774f0880e0668 100644 --- a/src/compiler/performance.ts +++ b/src/compiler/performance.ts @@ -54,11 +54,12 @@ const marks = new Map(); const counts = new Map(); const durations = new Map(); -/** @internal */ /** * Marks a performance event. * * @param markName The name of the mark. + * + * @internal */ export function mark(markName: string) { if (enabled) { @@ -69,7 +70,6 @@ export function mark(markName: string) { } } -/** @internal */ /** * Adds a performance measurement with the specified name. * @@ -78,6 +78,8 @@ export function mark(markName: string) { * profiler was enabled is used. * @param endMarkName The name of the ending mark. If not supplied, the current timestamp is * used. + * + * @internal */ export function measure(measureName: string, startMarkName?: string, endMarkName?: string) { if (enabled) { @@ -89,31 +91,34 @@ export function measure(measureName: string, startMarkName?: string, endMarkName } } -/** @internal */ /** * Gets the number of times a marker was encountered. * * @param markName The name of the mark. + * + * @internal */ export function getCount(markName: string) { return counts.get(markName) || 0; } -/** @internal */ /** * Gets the total duration of all measurements with the supplied name. * * @param measureName The name of the measure whose durations should be accumulated. + * + * @internal */ export function getDuration(measureName: string) { return durations.get(measureName) || 0; } -/** @internal */ /** * Iterate over each measure, performing some action * * @param cb The action to perform for each measure + * + * @internal */ export function forEachMeasure(cb: (measureName: string, duration: number) => void) { durations.forEach((duration, measureName) => cb(measureName, duration)); @@ -144,16 +149,20 @@ export function clearMarks(name?: string) { performanceImpl?.clearMarks(name); } -/** @internal */ /** * Indicates whether the performance API is enabled. + * + * @internal */ export function isEnabled() { return enabled; } -/** @internal */ -/** Enables (and resets) performance measurements for the compiler. */ +/** + * Enables (and resets) performance measurements for the compiler. + * + * @internal + */ export function enable(system: System = sys) { if (!enabled) { enabled = true; @@ -172,8 +181,11 @@ export function enable(system: System = sys) { return true; } -/** @internal */ -/** Disables performance measurements for the compiler. */ +/** + * Disables performance measurements for the compiler. + * + * @internal + */ export function disable() { if (enabled) { marks.clear(); diff --git a/src/compiler/performanceCore.ts b/src/compiler/performanceCore.ts index 15d3c41994d90..ce65f1d8894d6 100644 --- a/src/compiler/performanceCore.ts +++ b/src/compiler/performanceCore.ts @@ -135,9 +135,12 @@ export function tryGetNativePerformanceHooks() { return nativePerformanceHooks; } -/** @internal */ -/** Gets a timestamp with (at least) ms resolution */ +/** + * Gets a timestamp with (at least) ms resolution + * + * @internal + */ export const timestamp = nativePerformance ? () => nativePerformance.now() : Date.now ? Date.now : - () => +(new Date()); \ No newline at end of file + () => +(new Date()); diff --git a/src/compiler/program.ts b/src/compiler/program.ts index 679e7e639f6c5..0bd0f22ca3a0a 100644 --- a/src/compiler/program.ts +++ b/src/compiler/program.ts @@ -74,7 +74,7 @@ export function resolveTripleslashReference(moduleName: string, containingFile: return normalizePath(referencedFileName); } -/* @internal */ +/** @internal */ export function computeCommonSourceDirectoryOfFilenames(fileNames: readonly string[], currentDirectory: string, getCanonicalFileName: GetCanonicalFileName): string { let commonPathComponents: string[] | undefined; const failed = forEach(fileNames, sourceFile => { @@ -124,7 +124,7 @@ export function createCompilerHost(options: CompilerOptions, setParentNodes?: bo return createCompilerHostWorker(options, setParentNodes); } -/*@internal*/ +/** @internal */ export function createGetSourceFile( readFile: ProgramHost["readFile"], getCompilerOptions: () => CompilerOptions, @@ -148,7 +148,7 @@ export function createGetSourceFile( }; } -/*@internal*/ +/** @internal */ export function createWriteFileMeasuringIO( actualWriteFile: (path: string, data: string, writeByteOrderMark: boolean) => void, createDirectory: (path: string) => void, @@ -181,7 +181,7 @@ export function createWriteFileMeasuringIO( }; } -/*@internal*/ +/** @internal */ export function createCompilerHostWorker(options: CompilerOptions, setParentNodes?: boolean, system = sys): CompilerHost { const existingDirectories = new Map(); const getCanonicalFileName = createGetCanonicalFileName(system.useCaseSensitiveFileNames); @@ -229,7 +229,7 @@ export function createCompilerHostWorker(options: CompilerOptions, setParentNode return compilerHost; } -/*@internal*/ +/** @internal */ interface CompilerHostLikeForCache { fileExists(fileName: string): boolean; readFile(fileName: string, encoding?: string): string | undefined; @@ -238,7 +238,7 @@ interface CompilerHostLikeForCache { writeFile?: WriteFileCallback; } -/*@internal*/ +/** @internal */ export function changeCompilerHostLikeToUseCache( host: CompilerHostLikeForCache, toPath: (fileName: string) => Path, @@ -354,7 +354,7 @@ export function changeCompilerHostLikeToUseCache( } export function getPreEmitDiagnostics(program: Program, sourceFile?: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; -/*@internal*/ export function getPreEmitDiagnostics(program: BuilderProgram, sourceFile?: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; // eslint-disable-line @typescript-eslint/unified-signatures +/** @internal */ export function getPreEmitDiagnostics(program: BuilderProgram, sourceFile?: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; // eslint-disable-line @typescript-eslint/unified-signatures export function getPreEmitDiagnostics(program: Program | BuilderProgram, sourceFile?: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[] { let diagnostics: Diagnostic[] | undefined; diagnostics = addRange(diagnostics, program.getConfigFileParsingDiagnostics()); @@ -480,7 +480,7 @@ function formatCodeSpan(file: SourceFile, start: number, length: number, indent: return context; } -/* @internal */ +/** @internal */ export function formatLocation(file: SourceFile, start: number, host: FormatDiagnosticsHost, color = formatColorAndReset) { const { line: firstLine, character: firstLineChar } = getLineAndCharacterOfPosition(file, start); // TODO: GH#18217 const relativeFileName = host ? convertToRelativePath(file.fileName, host.getCurrentDirectory(), fileName => host.getCanonicalFileName(fileName)) : file.fileName; @@ -553,7 +553,7 @@ export function flattenDiagnosticMessageText(diag: string | DiagnosticMessageCha return result; } -/* @internal */ +/** @internal */ export function loadWithTypeDirectiveCache(names: string[] | readonly FileReference[], containingFile: string, redirectedReference: ResolvedProjectReference | undefined, containingFileMode: SourceFile["impliedNodeFormat"], loader: (name: string, containingFile: string, redirectedReference: ResolvedProjectReference | undefined, resolutionMode: SourceFile["impliedNodeFormat"]) => T): T[] { if (names.length === 0) { return []; @@ -585,8 +585,8 @@ export function loadWithTypeDirectiveCache(names: string[] | readonly FileRef * @internal */ export interface SourceFileImportsList { - /* @internal */ imports: SourceFile["imports"]; - /* @internal */ moduleAugmentations: SourceFile["moduleAugmentations"]; + /** @internal */ imports: SourceFile["imports"]; + /** @internal */ moduleAugmentations: SourceFile["moduleAugmentations"]; impliedNodeFormat?: SourceFile["impliedNodeFormat"]; } @@ -616,7 +616,7 @@ export function getModeForResolutionAtIndex(file: SourceFileImportsList, index: return getModeForUsageLocation(file, getModuleNameStringLiteralAt(file, index)); } -/* @internal */ +/** @internal */ export function isExclusivelyTypeOnlyImportOrExport(decl: ImportDeclaration | ExportDeclaration) { if (isExportDeclaration(decl)) { return decl.isTypeOnly; @@ -663,7 +663,7 @@ export function getModeForUsageLocation(file: {impliedNodeFormat?: SourceFile["i return exprParentParent && isImportEqualsDeclaration(exprParentParent) ? ModuleKind.CommonJS : ModuleKind.ESNext; } -/* @internal */ +/** @internal */ export function getResolutionModeOverrideForClause(clause: AssertClause | undefined, grammarErrorOnNode?: (node: Node, diagnostic: DiagnosticMessage) => void) { if (!clause) return undefined; if (length(clause.elements) !== 1) { @@ -684,7 +684,7 @@ export function getResolutionModeOverrideForClause(clause: AssertClause | undefi return elem.value.text === "import" ? ModuleKind.ESNext : ModuleKind.CommonJS; } -/* @internal */ +/** @internal */ export function loadWithModeAwareCache(names: readonly StringLiteralLike[] | readonly string[], containingFile: SourceFile, containingFileName: string, redirectedReference: ResolvedProjectReference | undefined, resolutionInfo: ModuleResolutionInfo | undefined, loader: (name: string, resolverMode: ModuleKind.CommonJS | ModuleKind.ESNext | undefined, containingFileName: string, redirectedReference: ResolvedProjectReference | undefined) => T): T[] { if (names.length === 0) { return []; @@ -711,7 +711,7 @@ export function loadWithModeAwareCache(names: readonly StringLiteralLike[] | return resolutions; } -/* @internal */ +/** @internal */ export function forEachResolvedProjectReference( resolvedProjectReferences: readonly (ResolvedProjectReference | undefined)[] | undefined, cb: (resolvedProjectReference: ResolvedProjectReference, parent: ResolvedProjectReference | undefined) => T | undefined @@ -756,7 +756,7 @@ function forEachProjectReference( } } -/* @internal */ +/** @internal */ export const inferredTypesContainingFile = "__inferred type names__.ts"; interface DiagnosticCache { @@ -764,7 +764,7 @@ interface DiagnosticCache { allDiagnostics?: readonly T[]; } -/*@internal*/ +/** @internal */ export function isReferencedFile(reason: FileIncludeReason | undefined): reason is ReferencedFile { switch (reason?.kind) { case FileIncludeKind.Import: @@ -777,7 +777,7 @@ export function isReferencedFile(reason: FileIncludeReason | undefined): reason } } -/*@internal*/ +/** @internal */ export interface ReferenceFileLocation { file: SourceFile; pos: number; @@ -785,19 +785,19 @@ export interface ReferenceFileLocation { packageId: PackageId | undefined; } -/*@internal*/ +/** @internal */ export interface SyntheticReferenceFileLocation { file: SourceFile; packageId: PackageId | undefined; text: string; } -/*@internal*/ +/** @internal */ export function isReferenceFileLocation(location: ReferenceFileLocation | SyntheticReferenceFileLocation): location is ReferenceFileLocation { return (location as ReferenceFileLocation).pos !== undefined; } -/*@internal*/ +/** @internal */ export function getReferencedFileLocation(getSourceFileByPath: (path: Path) => SourceFile | undefined, ref: ReferencedFile): ReferenceFileLocation | SyntheticReferenceFileLocation { const file = Debug.checkDefined(getSourceFileByPath(ref.file)); const { kind, index } = ref; @@ -828,8 +828,9 @@ export function getReferencedFileLocation(getSourceFileByPath: (path: Path) => S /** * Determines if program structure is upto date or needs to be recreated + * + * @internal */ -/* @internal */ export function isProgramUptoDate( program: Program | undefined, rootFileNames: string[], @@ -935,7 +936,7 @@ export function getImpliedNodeFormatForFile(fileName: Path, packageJsonInfoCache return typeof result === "object" ? result.impliedNodeFormat : result; } -/*@internal*/ +/** @internal */ export function getImpliedNodeFormatForFileWorker( fileName: string, packageJsonInfoCache: PackageJsonInfoCache | undefined, @@ -4307,10 +4308,10 @@ function updateHostForUseSourceOfProjectReferenceRedirect(host: HostForUseSource } } -/*@internal*/ +/** @internal */ export const emitSkippedWithNoDiagnostics: EmitResult = { diagnostics: emptyArray, sourceMaps: undefined, emittedFiles: undefined, emitSkipped: true }; -/*@internal*/ +/** @internal */ export function handleNoEmitOptions( program: Program | T, sourceFile: SourceFile | undefined, @@ -4351,12 +4352,12 @@ export function handleNoEmitOptions( return { diagnostics, sourceMaps: undefined, emittedFiles, emitSkipped: true }; } -/*@internal*/ +/** @internal */ export function filterSemanticDiagnostics(diagnostic: readonly Diagnostic[], option: CompilerOptions): readonly Diagnostic[] { return filter(diagnostic, d => !d.skippedOn || !option[d.skippedOn]); } -/*@internal*/ +/** @internal */ interface CompilerHostLike { useCaseSensitiveFileNames(): boolean; getCurrentDirectory(): string; @@ -4367,7 +4368,7 @@ interface CompilerHostLike { onUnRecoverableConfigFileDiagnostic?: DiagnosticReporter; } -/* @internal */ +/** @internal */ export function parseConfigHostFromCompilerHostLike(host: CompilerHostLike, directoryStructureHost: DirectoryStructureHost = host): ParseConfigFileHost { return { fileExists: f => directoryStructureHost.fileExists(f), @@ -4388,7 +4389,7 @@ export function parseConfigHostFromCompilerHostLike(host: CompilerHostLike, dire fileExists(fileName: string): boolean; } -/* @internal */ +/** @internal */ export function createPrependNodes( projectReferences: readonly ProjectReference[] | undefined, getCommandLine: (ref: ProjectReference, index: number) => ParsedCommandLine | undefined, @@ -4423,11 +4424,12 @@ export function resolveProjectReferencePath(hostOrRef: ResolveProjectReferencePa return resolveConfigFileProjectName(passedInRef.path); } -/* @internal */ /** * Returns a DiagnosticMessage if we won't include a resolved module due to its extension. * The DiagnosticMessage's parameters are the imported module name, and the filename it resolved to. * This returns a diagnostic even if the module will be an untyped module. + * + * @internal */ export function getResolutionDiagnostic(options: CompilerOptions, { extension }: ResolvedModuleFull): DiagnosticMessage | undefined { switch (extension) { @@ -4467,7 +4469,7 @@ function getModuleNames({ imports, moduleAugmentations }: SourceFile): StringLit return res; } -/* @internal */ +/** @internal */ export function getModuleNameStringLiteralAt({ imports, moduleAugmentations }: SourceFileImportsList, index: number): StringLiteralLike { if (index < imports.length) return imports[index]; let augIndex = imports.length; diff --git a/src/compiler/resolutionCache.ts b/src/compiler/resolutionCache.ts index 7a54771f36b5d..9d7b5274aa910 100644 --- a/src/compiler/resolutionCache.ts +++ b/src/compiler/resolutionCache.ts @@ -18,8 +18,11 @@ import { stringContains, trace, unorderedRemoveItem, WatchDirectoryFlags, } from "./_namespaces/ts"; -/** @internal */ -/** This is the cache of module/typedirectives resolution that can be retained across program */ +/** + * This is the cache of module/typedirectives resolution that can be retained across program + * + * @internal + */ export interface ResolutionCache { startRecordingFilesWithChangedResolutions(): void; finishRecordingFilesWithChangedResolutions(): Path[] | undefined; @@ -132,12 +135,13 @@ export function removeIgnoredPath(path: Path): Path | undefined { path; } -/** @internal */ /** * Filter out paths like * "/", "/user", "/user/username", "/user/username/folderAtRoot", * "c:/", "c:/users", "c:/users/username", "c:/users/username/folderAtRoot", "c:/folderAtRoot" * @param dirPath + * + * @internal */ export function canWatchDirectoryOrFile(dirPath: Path) { const rootLength = getRootLength(dirPath); diff --git a/src/compiler/scanner.ts b/src/compiler/scanner.ts index 107b1680480cd..ee1439635cd78 100644 --- a/src/compiler/scanner.ts +++ b/src/compiler/scanner.ts @@ -7,12 +7,12 @@ import { export type ErrorCallback = (message: DiagnosticMessage, length: number) => void; -/* @internal */ +/** @internal */ export function tokenIsIdentifierOrKeyword(token: SyntaxKind): boolean { return token >= SyntaxKind.Identifier; } -/* @internal */ +/** @internal */ export function tokenIsIdentifierOrKeywordOrGreaterThan(token: SyntaxKind): boolean { return token === SyntaxKind.GreaterThanToken || tokenIsIdentifierOrKeyword(token); } @@ -27,16 +27,16 @@ export interface Scanner { hasUnicodeEscape(): boolean; hasExtendedUnicodeEscape(): boolean; hasPrecedingLineBreak(): boolean; - /* @internal */ + /** @internal */ hasPrecedingJSDocComment(): boolean; isIdentifier(): boolean; isReservedWord(): boolean; isUnterminated(): boolean; - /* @internal */ + /** @internal */ getNumericLiteralFlags(): TokenFlags; - /* @internal */ + /** @internal */ getCommentDirectives(): CommentDirective[] | undefined; - /* @internal */ + /** @internal */ getTokenFlags(): TokenFlags; reScanGreaterToken(): SyntaxKind; reScanSlashToken(): SyntaxKind; @@ -56,7 +56,7 @@ export interface Scanner { scan(): SyntaxKind; getText(): string; - /* @internal */ + /** @internal */ clearCommentDirectives(): void; // Sets the text for the scanner to scan. An optional subrange starting point and length // can be provided to have the scanner only scan a portion of the text. @@ -65,7 +65,7 @@ export interface Scanner { setScriptTarget(scriptTarget: ScriptTarget): void; setLanguageVariant(variant: LanguageVariant): void; setTextPos(textPos: number): void; - /* @internal */ + /** @internal */ setInJSDocType(inType: boolean): void; // Invokes the provided callback then unconditionally restores the scanner to the state it // was in immediately prior to invoking the callback. The result of invoking the callback @@ -333,7 +333,7 @@ function lookupInUnicodeMap(code: number, map: readonly number[]): boolean { return false; } -/* @internal */ export function isUnicodeIdentifierStart(code: number, languageVersion: ScriptTarget | undefined) { +/** @internal */ export function isUnicodeIdentifierStart(code: number, languageVersion: ScriptTarget | undefined) { return languageVersion! >= ScriptTarget.ES2015 ? lookupInUnicodeMap(code, unicodeESNextIdentifierStart) : languageVersion === ScriptTarget.ES5 ? lookupInUnicodeMap(code, unicodeES5IdentifierStart) : @@ -360,12 +360,12 @@ export function tokenToString(t: SyntaxKind): string | undefined { return tokenStrings[t]; } -/* @internal */ +/** @internal */ export function stringToToken(s: string): SyntaxKind | undefined { return textToToken.get(s); } -/* @internal */ +/** @internal */ export function computeLineStarts(text: string): number[] { const result: number[] = []; let pos = 0; @@ -396,7 +396,7 @@ export function computeLineStarts(text: string): number[] { } export function getPositionOfLineAndCharacter(sourceFile: SourceFileLike, line: number, character: number): number; -/* @internal */ +/** @internal */ export function getPositionOfLineAndCharacter(sourceFile: SourceFileLike, line: number, character: number, allowEdits?: true): number; // eslint-disable-line @typescript-eslint/unified-signatures export function getPositionOfLineAndCharacter(sourceFile: SourceFileLike, line: number, character: number, allowEdits?: true): number { return sourceFile.getPositionOfLineAndCharacter ? @@ -404,7 +404,7 @@ export function getPositionOfLineAndCharacter(sourceFile: SourceFileLike, line: computePositionOfLineAndCharacter(getLineStarts(sourceFile), line, character, sourceFile.text, allowEdits); } -/* @internal */ +/** @internal */ export function computePositionOfLineAndCharacter(lineStarts: readonly number[], line: number, character: number, debugText?: string, allowEdits?: true): number { if (line < 0 || line >= lineStarts.length) { if (allowEdits) { @@ -432,12 +432,12 @@ export function computePositionOfLineAndCharacter(lineStarts: readonly number[], return res; } -/* @internal */ +/** @internal */ export function getLineStarts(sourceFile: SourceFileLike): readonly number[] { return sourceFile.lineMap || (sourceFile.lineMap = computeLineStarts(sourceFile.text)); } -/* @internal */ +/** @internal */ export function computeLineAndCharacterOfPosition(lineStarts: readonly number[], position: number): LineAndCharacter { const lineNumber = computeLineOfPosition(lineStarts, position); return { @@ -534,7 +534,7 @@ function isCodePoint(code: number): boolean { return code <= 0x10FFFF; } -/* @internal */ +/** @internal */ export function isOctalDigit(ch: number): boolean { return ch >= CharacterCodes._0 && ch <= CharacterCodes._7; } @@ -566,7 +566,7 @@ export function couldStartTrivia(text: string, pos: number): boolean { } } -/* @internal */ +/** @internal */ export function skipTrivia(text: string, pos: number, stopAfterLineBreak?: boolean, stopAtComments?: boolean, inJSDoc?: boolean): number { if (positionIsSynthesized(pos)) { return pos; @@ -720,14 +720,14 @@ function scanConflictMarkerTrivia(text: string, pos: number, error?: (diag: Diag const shebangTriviaRegex = /^#!.*/; -/*@internal*/ +/** @internal */ export function isShebangTrivia(text: string, pos: number) { // Shebangs check must only be done at the start of the file Debug.assert(pos === 0); return shebangTriviaRegex.test(text); } -/*@internal*/ +/** @internal */ export function scanShebangTrivia(text: string, pos: number) { const shebang = shebangTriviaRegex.exec(text)![0]; pos = pos + shebang.length; @@ -918,7 +918,7 @@ export function isIdentifierPart(ch: number, languageVersion: ScriptTarget | und ch > CharacterCodes.maxAsciiCharacter && isUnicodeIdentifierPart(ch, languageVersion); } -/* @internal */ +/** @internal */ export function isIdentifierText(name: string, languageVersion: ScriptTarget | undefined, identifierVariant?: LanguageVariant): boolean { let ch = codePointAt(name, 0); if (!isIdentifierStart(ch, languageVersion)) { @@ -2616,7 +2616,7 @@ export function createScanner(languageVersion: ScriptTarget, } } -/* @internal */ +/** @internal */ const codePointAt: (s: string, i: number) => number = (String.prototype as any).codePointAt ? (s, i) => (s as any).codePointAt(i) : function codePointAt(str, i): number { // from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/codePointAt const size = str.length; @@ -2637,7 +2637,7 @@ const codePointAt: (s: string, i: number) => number = (String.prototype as any). return first; }; -/* @internal */ +/** @internal */ function charSize(ch: number) { if (ch >= 0x10000) { return 2; @@ -2661,7 +2661,7 @@ function utf16EncodeAsStringFallback(codePoint: number) { const utf16EncodeAsStringWorker: (codePoint: number) => string = (String as any).fromCodePoint ? codePoint => (String as any).fromCodePoint(codePoint) : utf16EncodeAsStringFallback; -/* @internal */ +/** @internal */ export function utf16EncodeAsString(codePoint: number) { return utf16EncodeAsStringWorker(codePoint); } diff --git a/src/compiler/semver.ts b/src/compiler/semver.ts index 0500ba87f827b..c91595719b743 100644 --- a/src/compiler/semver.ts +++ b/src/compiler/semver.ts @@ -30,9 +30,10 @@ const buildPartRegExp = /^[a-z0-9-]+$/i; // > Numeric identifiers MUST NOT include leading zeroes. const numericIdentifierRegExp = /^(0|[1-9]\d*)$/; -/** @internal */ /** * Describes a precise semantic version number, https://semver.org + * + * @internal */ export class Version { static readonly zero = new Version(0, 0, 0, ["0"]); @@ -185,9 +186,10 @@ function comparePrereleaseIdentifiers(left: readonly string[], right: readonly s return compareValues(left.length, right.length); } -/** @internal */ /** * Describes a semantic version range, per https://github.com/npm/node-semver#ranges + * + * @internal */ export class VersionRange { private _alternatives: readonly (readonly Comparator[])[]; diff --git a/src/compiler/sourcemap.ts b/src/compiler/sourcemap.ts index 6cab9ab9876e2..c4a34595e75f1 100644 --- a/src/compiler/sourcemap.ts +++ b/src/compiler/sourcemap.ts @@ -353,9 +353,10 @@ export function getLineInfo(text: string, lineStarts: readonly number[]): LineIn }; } -/** @internal */ /** * Tries to find the sourceMappingURL comment at the end of a file. + * + * @internal */ export function tryGetSourceMappingURL(lineInfo: LineInfo) { for (let index = lineInfo.getLineCount() - 1; index >= 0; index--) { diff --git a/src/compiler/symbolWalker.ts b/src/compiler/symbolWalker.ts index 905443939fd94..71277f27d7d5c 100644 --- a/src/compiler/symbolWalker.ts +++ b/src/compiler/symbolWalker.ts @@ -4,8 +4,6 @@ import { SyntaxKind, Type, TypeFlags, TypeParameter, TypePredicate, TypeQueryNode, TypeReference, UnionOrIntersectionType, } from "./_namespaces/ts"; -/** @internal */ - /** @internal */ export function createGetSymbolWalker( getRestTypeOfSignature: (sig: Signature) => Type, @@ -193,4 +191,4 @@ export function createGetSymbolWalker( return false; } } -} \ No newline at end of file +} diff --git a/src/compiler/sys.ts b/src/compiler/sys.ts index 45404e759648f..01b48505c84be 100644 --- a/src/compiler/sys.ts +++ b/src/compiler/sys.ts @@ -14,8 +14,9 @@ declare function clearTimeout(handle: any): void; /** * djb2 hashing algorithm * http://www.cse.yorku.ca/~oz/hash.html + * + * @internal */ -/* @internal */ export function generateDjb2Hash(data: string): string { let acc = 5381; for (let i = 0; i < data.length; i++) { @@ -28,8 +29,9 @@ export function generateDjb2Hash(data: string): string { * Set a high stack trace limit to provide more information in case of an error. * Called for command-line and server use cases. * Not called if TypeScript is used as a library. + * + * @internal */ -/* @internal */ export function setStackTraceLimit() { if ((Error as any).stackTraceLimit < 100) { // Also tests that we won't set the property if it doesn't exist. (Error as any).stackTraceLimit = 100; @@ -50,22 +52,22 @@ interface WatchedFile { mtime: Date; } -/* @internal */ +/** @internal */ export enum PollingInterval { High = 2000, Medium = 500, Low = 250 } -/* @internal */ +/** @internal */ export type HostWatchFile = (fileName: string, callback: FileWatcherCallback, pollingInterval: PollingInterval, options: WatchOptions | undefined) => FileWatcher; -/* @internal */ +/** @internal */ export type HostWatchDirectory = (fileName: string, callback: DirectoryWatcherCallback, recursive: boolean, options: WatchOptions | undefined) => FileWatcher; -/* @internal */ +/** @internal */ export const missingFileModifiedTime = new Date(0); // Any subsequent modification will occur after this time -/* @internal */ +/** @internal */ export function getModifiedTime(host: { getModifiedTime: NonNullable; }, fileName: string) { return host.getModifiedTime(fileName) || missingFileModifiedTime; } @@ -86,7 +88,7 @@ function createPollingIntervalBasedLevels(levels: Levels) { const defaultChunkLevels: Levels = { Low: 32, Medium: 64, High: 256 }; let pollingChunkSize = createPollingIntervalBasedLevels(defaultChunkLevels); -/* @internal */ +/** @internal */ export let unchangedPollThresholds = createPollingIntervalBasedLevels(defaultChunkLevels); function setCustomPollingValues(system: System) { @@ -483,7 +485,7 @@ function onWatchedFileStat(watchedFile: WatchedFile, modifiedTime: Date): boolea return false; } -/*@internal*/ +/** @internal */ export function getFileWatcherEventKind(oldTime: number, newTime: number) { return oldTime === 0 ? FileWatcherEventKind.Created @@ -492,17 +494,17 @@ export function getFileWatcherEventKind(oldTime: number, newTime: number) { : FileWatcherEventKind.Changed; } -/*@internal*/ +/** @internal */ export const ignoredPaths = ["/node_modules/.", "/.git", "/.#"]; let curSysLog: (s: string) => void = noop; // eslint-disable-line prefer-const -/*@internal*/ +/** @internal */ export function sysLog(s: string) { return curSysLog(s); } -/*@internal*/ +/** @internal */ export function setSysLog(logger: typeof sysLog) { curSysLog = logger; } @@ -769,17 +771,17 @@ function createDirectoryWatcherSupportingRecursive({ } } -/*@internal*/ +/** @internal */ export type FsWatchCallback = (eventName: "rename" | "change", relativeFileName: string | undefined, modifiedTime?: Date) => void; -/*@internal*/ +/** @internal */ export type FsWatch = (fileOrDirectory: string, entryKind: FileSystemEntryKind, callback: FsWatchCallback, recursive: boolean, fallbackPollingInterval: PollingInterval, fallbackOptions: WatchOptions | undefined) => FileWatcher; -/*@internal*/ +/** @internal */ export interface FsWatchWorkerWatcher extends FileWatcher { on(eventName: string, listener: () => void): void; } -/*@internal*/ +/** @internal */ export type FsWatchWorker = (fileOrDirectory: string, recursive: boolean, callback: FsWatchCallback) => FsWatchWorkerWatcher; -/*@internal*/ +/** @internal */ export const enum FileSystemEntryKind { File, Directory, @@ -840,10 +842,10 @@ function createFsWatchCallbackForDirectoryWatcherCallback( }; } -/*@internal*/ +/** @internal */ export type FileSystemEntryExists = (fileorDirectrory: string, entryKind: FileSystemEntryKind) => boolean; -/*@internal*/ +/** @internal */ export interface CreateSystemWatchFunctions { // Polling watch file pollingWatchFileWorker: HostWatchFile; @@ -867,7 +869,7 @@ export interface CreateSystemWatchFunctions { sysLog: (s: string) => void; } -/*@internal*/ +/** @internal */ export function createSystemWatchFunctions({ pollingWatchFileWorker, getModifiedTime, @@ -1238,8 +1240,9 @@ export function createSystemWatchFunctions({ /** * patch writefile to create folder before writing the file + * + * @internal */ -/*@internal*/ export function patchWriteFileEnsuringDirectory(sys: System) { // patch writefile to create folder before writing the file const originalWriteFile = sys.writeFile; @@ -1253,10 +1256,10 @@ export function patchWriteFileEnsuringDirectory(sys: System) { path => sys.directoryExists(path)); } -/*@internal*/ +/** @internal */ export type BufferEncoding = "ascii" | "utf8" | "utf-8" | "utf16le" | "ucs2" | "ucs-2" | "base64" | "latin1" | "binary" | "hex"; -/*@internal*/ +/** @internal */ interface NodeBuffer extends Uint8Array { constructor: any; write(str: string, encoding?: BufferEncoding): number; @@ -1332,7 +1335,7 @@ interface NodeBuffer extends Uint8Array { values(): IterableIterator; } -/*@internal*/ +/** @internal */ interface Buffer extends NodeBuffer { } // TODO: GH#18217 Methods on System are often used as if they are certainly defined @@ -1372,26 +1375,26 @@ export interface System { createSHA256Hash?(data: string): string; getMemoryUsage?(): number; exit(exitCode?: number): void; - /*@internal*/ enableCPUProfiler?(path: string, continuation: () => void): boolean; - /*@internal*/ disableCPUProfiler?(continuation: () => void): boolean; - /*@internal*/ cpuProfilingEnabled?(): boolean; + /** @internal */ enableCPUProfiler?(path: string, continuation: () => void): boolean; + /** @internal */ disableCPUProfiler?(continuation: () => void): boolean; + /** @internal */ cpuProfilingEnabled?(): boolean; realpath?(path: string): string; - /*@internal*/ getEnvironmentVariable(name: string): string; - /*@internal*/ tryEnableSourceMapsForHost?(): void; - /*@internal*/ debugMode?: boolean; + /** @internal */ getEnvironmentVariable(name: string): string; + /** @internal */ tryEnableSourceMapsForHost?(): void; + /** @internal */ debugMode?: boolean; setTimeout?(callback: (...args: any[]) => void, ms: number, ...args: any[]): any; clearTimeout?(timeoutId: any): void; clearScreen?(): void; - /*@internal*/ setBlocking?(): void; + /** @internal */ setBlocking?(): void; base64decode?(input: string): string; base64encode?(input: string): string; - /*@internal*/ bufferFrom?(input: string, encoding?: string): Buffer; - /*@internal*/ require?(baseDir: string, moduleName: string): RequireResult; + /** @internal */ bufferFrom?(input: string, encoding?: string): Buffer; + /** @internal */ require?(baseDir: string, moduleName: string): RequireResult; // For testing - /*@internal*/ now?(): Date; - /*@internal*/ disableUseFileVersionAsSignature?: boolean; - /*@internal*/ storeFilesChangingSignatureDuringEmit?: boolean; + /** @internal */ now?(): Date; + /** @internal */ disableUseFileVersionAsSignature?: boolean; + /** @internal */ storeFilesChangingSignatureDuringEmit?: boolean; } export interface FileWatcher { @@ -1973,7 +1976,7 @@ export let sys: System = (() => { return sys!; })(); -/*@internal*/ +/** @internal */ export function setSys(s: System) { sys = s; } diff --git a/src/compiler/transformer.ts b/src/compiler/transformer.ts index 78f9ba9c67147..6e20641d369b2 100644 --- a/src/compiler/transformer.ts +++ b/src/compiler/transformer.ts @@ -159,7 +159,6 @@ export function noEmitNotification(hint: EmitHint, node: Node, callback: (hint: callback(hint, node); } -/** @internal */ /** * Transforms an array of SourceFiles by passing them through each transformer. * @@ -169,6 +168,8 @@ export function noEmitNotification(hint: EmitHint, node: Node, callback: (hint: * @param nodes An array of nodes to transform. * @param transforms An array of `TransformerFactory` callbacks. * @param allowDtsFiles A value indicating whether to allow the transformation of .d.ts files. + * + * @internal */ export function transformNodes(resolver: EmitResolver | undefined, host: EmitHost | undefined, factory: NodeFactory, options: CompilerOptions, nodes: readonly T[], transformers: readonly TransformerFactory[], allowDtsFiles: boolean): TransformationResult { const enabledSyntaxKindFeatures = new Array(SyntaxKind.Count); diff --git a/src/compiler/transformers/classFields.ts b/src/compiler/transformers/classFields.ts index 1f2c3ce4c0049..5141d77afc7bf 100644 --- a/src/compiler/transformers/classFields.ts +++ b/src/compiler/transformers/classFields.ts @@ -159,13 +159,14 @@ const enum ClassFacts { NeedsSubstitutionForThisInClassStaticField = 1 << 3, } -/** @internal */ /** * Transforms ECMAScript Class Syntax. * TypeScript parameter property syntax is transformed in the TypeScript transformer. * For now, this transforms public field declarations using TypeScript class semantics, * where declarations are elided and initializers are transformed as assignments in the constructor. * When --useDefineForClassFields is on, this transforms to ECMAScript semantics, with Object.defineProperty. + * + * @internal */ export function transformClassFields(context: TransformationContext) { const { diff --git a/src/compiler/transformers/declarations.ts b/src/compiler/transformers/declarations.ts index babd5dcb098a0..095d395c5bd9b 100644 --- a/src/compiler/transformers/declarations.ts +++ b/src/compiler/transformers/declarations.ts @@ -62,7 +62,7 @@ export function isInternalDeclaration(node: Node, currentSourceFile: SourceFile) const commentRanges = previousSibling ? concatenate( // to handle - // ... parameters, /* @internal */ + // ... parameters, /** @internal */ // public param: string getTrailingCommentRanges(text, skipTrivia(text, previousSibling.end + 1, /* stopAfterLineBreak */ false, /* stopAtComments */ true)), getLeadingCommentRanges(text, node.pos) @@ -85,12 +85,13 @@ const declarationEmitNodeBuilderFlags = NodeBuilderFlags.GenerateNamesForShadowedTypeParams | NodeBuilderFlags.NoTruncation; -/** @internal */ /** * Transforms a ts file into a .d.ts file * This process requires type information, which is retrieved through the emit resolver. Because of this, * in many places this transformer assumes it will be operating on parse tree nodes directly. * This means that _no transforms should be allowed to occur before this one_. + * + * @internal */ export function transformDeclarations(context: TransformationContext) { const throwDiagnostic = () => Debug.fail("Diagnostic emitted without context"); diff --git a/src/compiler/transformers/destructuring.ts b/src/compiler/transformers/destructuring.ts index 3198bdead1099..b4f4739a803bd 100644 --- a/src/compiler/transformers/destructuring.ts +++ b/src/compiler/transformers/destructuring.ts @@ -34,7 +34,6 @@ export const enum FlattenLevel { ObjectRest, } -/** @internal */ /** * Flattens a DestructuringAssignment or a VariableDeclaration to an expression. * @@ -45,6 +44,8 @@ export const enum FlattenLevel { * @param needsValue An optional value indicating whether the value from the right-hand-side of * the destructuring assignment is needed as part of a larger expression. * @param createAssignmentCallback An optional callback used to create the assignment expression. + * + * @internal */ export function flattenDestructuringAssignment( node: VariableDeclaration | DestructuringAssignment, @@ -174,7 +175,6 @@ function bindingOrAssignmentPatternContainsNonLiteralComputedName(pattern: Bindi return !!forEach(getElementsOfBindingOrAssignmentPattern(pattern), bindingOrAssignmentElementContainsNonLiteralComputedName); } -/** @internal */ /** * Flattens a VariableDeclaration or ParameterDeclaration to one or more variable declarations. * @@ -185,6 +185,8 @@ function bindingOrAssignmentPatternContainsNonLiteralComputedName(pattern: Bindi * @param skipInitializer A value indicating whether to ignore the initializer of `node`. * @param hoistTempVariables Indicates whether temporary variables should not be recorded in-line. * @param level Indicates the extent to which flattening should occur. + * + * @internal */ export function flattenDestructuringBinding( node: VariableDeclaration | ParameterDeclaration, diff --git a/src/compiler/transformers/es2017.ts b/src/compiler/transformers/es2017.ts index 061bdf0801531..ba7508d1dab4a 100644 --- a/src/compiler/transformers/es2017.ts +++ b/src/compiler/transformers/es2017.ts @@ -819,8 +819,11 @@ export function transformES2017(context: TransformationContext) { } } -/** @internal */ -/** Creates a variable named `_super` with accessor properties for the given property names. */ +/** + * Creates a variable named `_super` with accessor properties for the given property names. + * + * @internal + */ export function createSuperAccessVariableStatement(factory: NodeFactory, resolver: EmitResolver, node: FunctionLikeDeclaration, names: Set<__String>) { // Create a variable declaration with a getter/setter (if binding) definition for each name: // const _super = Object.create(null, { x: { get: () => super.x, set: (v) => super.x = v }, ... }); diff --git a/src/compiler/transformers/es5.ts b/src/compiler/transformers/es5.ts index 60c876af4b33c..cd7eb47d1e618 100644 --- a/src/compiler/transformers/es5.ts +++ b/src/compiler/transformers/es5.ts @@ -5,11 +5,12 @@ import { SourceFile, stringToToken, SyntaxKind, TransformationContext, } from "../_namespaces/ts"; -/** @internal */ /** * Transforms ES5 syntax into ES3 syntax. * * @param context Context and state information for the transformation. + * + * @internal */ export function transformES5(context: TransformationContext) { const { factory } = context; diff --git a/src/compiler/transformers/legacyDecorators.ts b/src/compiler/transformers/legacyDecorators.ts index 1bbb5aa65fb13..52ddcf5a62d1a 100644 --- a/src/compiler/transformers/legacyDecorators.ts +++ b/src/compiler/transformers/legacyDecorators.ts @@ -720,4 +720,4 @@ export function transformLegacyDecorators(context: TransformationContext) { return undefined; } -} \ No newline at end of file +} diff --git a/src/compiler/transformers/typeSerializer.ts b/src/compiler/transformers/typeSerializer.ts index cd06f183cbd11..7548d159c5aca 100644 --- a/src/compiler/transformers/typeSerializer.ts +++ b/src/compiler/transformers/typeSerializer.ts @@ -586,4 +586,4 @@ export function createRuntimeTypeSerializer(context: TransformationContext): Run getGlobalConstructorWithFallback(name) : factory.createIdentifier(name); } -} \ No newline at end of file +} diff --git a/src/compiler/transformers/utilities.ts b/src/compiler/transformers/utilities.ts index f33ab90eb0104..4460f4fc45936 100644 --- a/src/compiler/transformers/utilities.ts +++ b/src/compiler/transformers/utilities.ts @@ -274,11 +274,12 @@ function multiMapSparseArrayAdd(map: V[][], key: number, value: V): V[] { return values; } -/** @internal */ /** * Used in the module transformer to check if an expression is reasonably without sideeffect, * and thus better to copy into multiple places rather than to cache in a temporary variable * - this is mostly subjective beyond the requirement that the expression not be sideeffecting + * + * @internal */ export function isSimpleCopiableExpression(expression: Expression) { return isStringLiteralLike(expression) || @@ -287,11 +288,12 @@ export function isSimpleCopiableExpression(expression: Expression) { isIdentifier(expression); } -/** @internal */ /** * A simple inlinable expression is an expression which can be copied into multiple locations * without risk of repeating any sideeffects and whose value could not possibly change between * any such locations + * + * @internal */ export function isSimpleInlineableExpression(expression: Expression) { return !isIdentifier(expression) && isSimpleCopiableExpression(expression); @@ -325,9 +327,10 @@ export function getNonAssignmentOperatorForCompoundAssignment(kind: CompoundAssi } } -/** @internal */ /** * @returns Contained super() call from descending into the statement ignoring parentheses, if that call exists. + * + * @internal */ export function getSuperCallFromStatement(statement: Statement) { if (!isExpressionStatement(statement)) { @@ -340,9 +343,10 @@ export function getSuperCallFromStatement(statement: Statement) { : undefined; } -/** @internal */ /** * @returns The index (after prologue statements) of a super call, or -1 if not found. + * + * @internal */ export function findSuperStatementIndex(statements: NodeArray, indexAfterLastPrologueStatement: number) { for (let i = indexAfterLastPrologueStatement; i < statements.length; i += 1) { @@ -356,12 +360,13 @@ export function findSuperStatementIndex(statements: NodeArray, indexA return -1; } -/** @internal */ /** * Gets all the static or all the instance property declarations of a class * * @param node The class node. * @param isStatic A value indicating whether to get properties from the static or instance side of the class. + * + * @internal */ export function getProperties(node: ClassExpression | ClassDeclaration, requireInitializer: true, isStatic: boolean): readonly InitializedPropertyDeclaration[]; /** @internal */ @@ -400,23 +405,25 @@ function isStaticPropertyDeclaration(member: ClassElement) { return isPropertyDeclaration(member) && hasStaticModifier(member); } -/** @internal */ /** * Gets a value indicating whether a class element is either a static or an instance property declaration with an initializer. * * @param member The class element node. * @param isStatic A value indicating whether the member should be a static or instance member. + * + * @internal */ export function isInitializedProperty(member: ClassElement): member is PropertyDeclaration & { initializer: Expression; } { return member.kind === SyntaxKind.PropertyDeclaration && (member as PropertyDeclaration).initializer !== undefined; } -/** @internal */ /** * Gets a value indicating whether a class element is a private instance method or accessor. * * @param member The class element node. + * + * @internal */ export function isNonStaticMethodOrAccessorWithPrivateName(member: ClassElement): member is PrivateIdentifierMethodDeclaration | PrivateIdentifierAccessorDeclaration | PrivateIdentifierAutoAccessorPropertyDeclaration { return !isStatic(member) && (isMethodOrAccessor(member) || isAutoAccessorPropertyDeclaration(member)) && isPrivateIdentifier(member.name); @@ -450,12 +457,13 @@ function getDecoratorsOfParameters(node: FunctionLikeDeclaration | undefined) { return decorators; } -/** @internal */ /** * Gets an AllDecorators object containing the decorators for the class and the decorators for the * parameters of the constructor of the class. * * @param node The class node. + * + * @internal */ export function getAllDecoratorsOfClass(node: ClassLikeDeclaration): AllDecorators | undefined { const decorators = getDecorators(node); @@ -470,12 +478,13 @@ export function getAllDecoratorsOfClass(node: ClassLikeDeclaration): AllDecorato }; } -/** @internal */ /** * Gets an AllDecorators object containing the decorators for the member and its parameters. * * @param parent The class node that contains the member. * @param member The class member. + * + * @internal */ export function getAllDecoratorsOfClassElement(member: ClassElement, parent: ClassLikeDeclaration): AllDecorators | undefined { switch (member.kind) { diff --git a/src/compiler/tsbuild.ts b/src/compiler/tsbuild.ts index c3138ae18d8d1..ad96f6e39428a 100644 --- a/src/compiler/tsbuild.ts +++ b/src/compiler/tsbuild.ts @@ -175,4 +175,4 @@ export function resolveConfigFileProjectName(project: string): ResolvedConfigFil } return combinePaths(project, "tsconfig.json") as ResolvedConfigFileName; -} \ No newline at end of file +} diff --git a/src/compiler/tsbuildPublic.ts b/src/compiler/tsbuildPublic.ts index 820cbf210e8fc..6ec55766ba0a1 100644 --- a/src/compiler/tsbuildPublic.ts +++ b/src/compiler/tsbuildPublic.ts @@ -36,15 +36,15 @@ export interface BuildOptions { force?: boolean; verbose?: boolean; - /*@internal*/ clean?: boolean; - /*@internal*/ watch?: boolean; - /*@internal*/ help?: boolean; - - /*@internal*/ preserveWatchOutput?: boolean; - /*@internal*/ listEmittedFiles?: boolean; - /*@internal*/ listFiles?: boolean; - /*@internal*/ explainFiles?: boolean; - /*@internal*/ pretty?: boolean; + /** @internal */ clean?: boolean; + /** @internal */ watch?: boolean; + /** @internal */ help?: boolean; + + /** @internal */ preserveWatchOutput?: boolean; + /** @internal */ listEmittedFiles?: boolean; + /** @internal */ listFiles?: boolean; + /** @internal */ explainFiles?: boolean; + /** @internal */ pretty?: boolean; incremental?: boolean; assumeChangesOnlyAffectDirectDependencies?: boolean; declaration?: boolean; @@ -54,11 +54,11 @@ export interface BuildOptions { inlineSourceMap?: boolean; traceResolution?: boolean; - /* @internal */ diagnostics?: boolean; - /* @internal */ extendedDiagnostics?: boolean; - /* @internal */ locale?: string; - /* @internal */ generateCpuProfile?: string; - /* @internal */ generateTrace?: string; + /** @internal */ diagnostics?: boolean; + /** @internal */ extendedDiagnostics?: boolean; + /** @internal */ locale?: string; + /** @internal */ generateCpuProfile?: string; + /** @internal */ generateTrace?: string; [option: string]: CompilerOptionsValue | undefined; } @@ -85,7 +85,7 @@ enum BuildResultFlags { AnyErrors = ConfigFileErrors | SyntaxErrors | TypeErrors | DeclarationEmitErrors | EmitErrors } -/*@internal*/ +/** @internal */ export type ResolvedConfigFilePath = ResolvedConfigFileName & Path; function getOrCreateValueFromConfigFileMap(configFileMap: ESMap, resolved: ResolvedConfigFilePath, createT: () => T): T { @@ -102,8 +102,11 @@ function getOrCreateValueMapFromConfigFileMap(configFileMap return getOrCreateValueFromConfigFileMap(configFileMap, resolved, () => new Map()); } -/*@internal*/ -/** Helper to use now method instead of current date for testing purposes to get consistent baselines */ +/** + * Helper to use now method instead of current date for testing purposes to get consistent baselines + * + * @internal + */ export function getCurrentTime(host: { now?(): Date; }) { return host.now ? host.now() : new Date(); } @@ -135,11 +138,11 @@ export interface SolutionBuilderHostBase extends Progr // TODO: To do better with watch mode and normal build mode api that creates program and emits files // This currently helps enable --diagnostics and --extendedDiagnostics afterProgramEmitAndDiagnostics?(program: T): void; - /*@internal*/ beforeEmitBundle?(config: ParsedCommandLine): void; - /*@internal*/ afterEmitBundle?(config: ParsedCommandLine): void; + /** @internal */ beforeEmitBundle?(config: ParsedCommandLine): void; + /** @internal */ afterEmitBundle?(config: ParsedCommandLine): void; // For testing - /*@internal*/ now?(): Date; + /** @internal */ now?(): Date; } export interface SolutionBuilderHost extends SolutionBuilderHostBase { @@ -149,22 +152,22 @@ export interface SolutionBuilderHost extends SolutionB export interface SolutionBuilderWithWatchHost extends SolutionBuilderHostBase, WatchHost { } -/*@internal*/ +/** @internal */ export type BuildOrder = readonly ResolvedConfigFileName[]; -/*@internal*/ +/** @internal */ export interface CircularBuildOrder { buildOrder: BuildOrder; circularDiagnostics: readonly Diagnostic[]; } -/*@internal*/ +/** @internal */ export type AnyBuildOrder = BuildOrder | CircularBuildOrder; -/*@internal*/ +/** @internal */ export function isCircularBuildOrder(buildOrder: AnyBuildOrder): buildOrder is CircularBuildOrder { return !!buildOrder && !!(buildOrder as CircularBuildOrder).buildOrder; } -/*@internal*/ +/** @internal */ export function getBuildOrderFromAnyBuildOrder(anyBuildOrder: AnyBuildOrder): BuildOrder { return isCircularBuildOrder(anyBuildOrder) ? anyBuildOrder.buildOrder : anyBuildOrder; } @@ -177,12 +180,12 @@ export interface SolutionBuilder { getNextInvalidatedProject(cancellationToken?: CancellationToken): InvalidatedProject | undefined; // Currently used for testing but can be made public if needed: - /*@internal*/ getBuildOrder(): AnyBuildOrder; + /** @internal */ getBuildOrder(): AnyBuildOrder; // Testing only - /*@internal*/ getUpToDateStatusOfProject(project: string): UpToDateStatus; - /*@internal*/ invalidateProject(configFilePath: ResolvedConfigFilePath, reloadLevel?: ConfigFileProgramReloadLevel): void; - /*@internal*/ close(): void; + /** @internal */ getUpToDateStatusOfProject(project: string): UpToDateStatus; + /** @internal */ invalidateProject(configFilePath: ResolvedConfigFilePath, reloadLevel?: ConfigFileProgramReloadLevel): void; + /** @internal */ close(): void; } /** @@ -688,8 +691,8 @@ export enum InvalidatedProjectKind { export interface InvalidatedProjectBase { readonly kind: InvalidatedProjectKind; readonly project: ResolvedConfigFileName; - /*@internal*/ readonly projectPath: ResolvedConfigFilePath; - /*@internal*/ readonly buildOrder: readonly ResolvedConfigFileName[]; + /** @internal */ readonly projectPath: ResolvedConfigFilePath; + /** @internal */ readonly buildOrder: readonly ResolvedConfigFileName[]; /** * To dispose this project and ensure that all the necessary actions are taken and state is updated accordingly */ diff --git a/src/compiler/types.ts b/src/compiler/types.ts index 92ace11d28430..53150ba778fec 100644 --- a/src/compiler/types.ts +++ b/src/compiler/types.ts @@ -8,7 +8,7 @@ import { // arbitrary file name can be converted to Path via toPath function export type Path = string & { __pathBrand: any }; -/* @internal */ +/** @internal */ export type MatchingKeys = K extends (TRecord[K] extends TMatch ? K : never) ? K : never; export interface TextRange { @@ -464,8 +464,8 @@ export const enum SyntaxKind { LastJSDocNode = JSDocPropertyTag, FirstJSDocTagNode = JSDocTag, LastJSDocTagNode = JSDocPropertyTag, - /* @internal */ FirstContextualKeyword = AbstractKeyword, - /* @internal */ LastContextualKeyword = OfKeyword, + /** @internal */ FirstContextualKeyword = AbstractKeyword, + /** @internal */ LastContextualKeyword = OfKeyword, } export type TriviaSyntaxKind = @@ -672,7 +672,7 @@ export type KeywordTypeSyntaxKind = | SyntaxKind.VoidKeyword ; -/* @internal */ +/** @internal */ export type TypeNodeSyntaxKind = | KeywordTypeSyntaxKind | SyntaxKind.TypePredicate @@ -789,15 +789,15 @@ export const enum NodeFlags { // removal, it is likely that users will add the import anyway. // The advantage of this approach is its simplicity. For the case of batch compilation, // we guarantee that users won't have to pay the price of walking the tree if a dynamic import isn't used. - /* @internal */ PossiblyContainsDynamicImport = 1 << 21, - /* @internal */ PossiblyContainsImportMeta = 1 << 22, + /** @internal */ PossiblyContainsDynamicImport = 1 << 21, + /** @internal */ PossiblyContainsImportMeta = 1 << 22, JSDoc = 1 << 23, // If node was parsed inside jsdoc - /* @internal */ Ambient = 1 << 24, // If node was inside an ambient context -- a declaration file, or inside something with the `declare` modifier. - /* @internal */ InWithStatement = 1 << 25, // If any ancestor of node was the `statement` of a WithStatement (not the `expression`) + /** @internal */ Ambient = 1 << 24, // If node was inside an ambient context -- a declaration file, or inside something with the `declare` modifier. + /** @internal */ InWithStatement = 1 << 25, // If any ancestor of node was the `statement` of a WithStatement (not the `expression`) JsonFile = 1 << 26, // If node was parsed in a Json - /* @internal */ TypeCached = 1 << 27, // If a type was cached for node at any point - /* @internal */ Deprecated = 1 << 28, // If has '@deprecated' JSDoc tag + /** @internal */ TypeCached = 1 << 27, // If a type was cached for node at any point + /** @internal */ Deprecated = 1 << 28, // If has '@deprecated' JSDoc tag BlockScoped = Let | Const, @@ -813,7 +813,7 @@ export const enum NodeFlags { // Represents all flags that are potentially set once and // never cleared on SourceFiles which get re-used in between incremental parses. // See the comment above on `PossiblyContainsDynamicImport` and `PossiblyContainsImportMeta`. - /* @internal */ PermanentlySetIncrementalFlags = PossiblyContainsDynamicImport | PossiblyContainsImportMeta, + /** @internal */ PermanentlySetIncrementalFlags = PossiblyContainsDynamicImport | PossiblyContainsImportMeta, } export const enum ModifierFlags { @@ -860,7 +860,7 @@ export const enum JsxFlags { IntrinsicElement = IntrinsicNamedElement | IntrinsicIndexedElement, } -/* @internal */ +/** @internal */ export const enum RelationComparisonResult { Succeeded = 1 << 0, // Should be truthy Failed = 1 << 1, @@ -871,30 +871,30 @@ export const enum RelationComparisonResult { ReportsMask = ReportsUnmeasurable | ReportsUnreliable } -/* @internal */ +/** @internal */ export type NodeId = number; export interface Node extends ReadonlyTextRange { readonly kind: SyntaxKind; readonly flags: NodeFlags; - /* @internal */ modifierFlagsCache: ModifierFlags; - /* @internal */ readonly transformFlags: TransformFlags; // Flags for transforms - /* @internal */ id?: NodeId; // Unique id (used to look up NodeLinks) + /** @internal */ modifierFlagsCache: ModifierFlags; + /** @internal */ readonly transformFlags: TransformFlags; // Flags for transforms + /** @internal */ id?: NodeId; // Unique id (used to look up NodeLinks) readonly parent: Node; // Parent node (initialized by binding) - /* @internal */ original?: Node; // The original node if this is an updated node. - /* @internal */ symbol: Symbol; // Symbol declared by node (initialized by binding) - /* @internal */ locals?: SymbolTable; // Locals associated with node (initialized by binding) - /* @internal */ nextContainer?: Node; // Next container in declaration order (initialized by binding) - /* @internal */ localSymbol?: Symbol; // Local symbol declared by node (initialized by binding only for exported nodes) - /* @internal */ flowNode?: FlowNode; // Associated FlowNode (initialized by binding) - /* @internal */ emitNode?: EmitNode; // Associated EmitNode (initialized by transforms) - /* @internal */ contextualType?: Type; // Used to temporarily assign a contextual type during overload resolution - /* @internal */ inferenceContext?: InferenceContext; // Inference context for contextual type + /** @internal */ original?: Node; // The original node if this is an updated node. + /** @internal */ symbol: Symbol; // Symbol declared by node (initialized by binding) + /** @internal */ locals?: SymbolTable; // Locals associated with node (initialized by binding) + /** @internal */ nextContainer?: Node; // Next container in declaration order (initialized by binding) + /** @internal */ localSymbol?: Symbol; // Local symbol declared by node (initialized by binding only for exported nodes) + /** @internal */ flowNode?: FlowNode; // Associated FlowNode (initialized by binding) + /** @internal */ emitNode?: EmitNode; // Associated EmitNode (initialized by transforms) + /** @internal */ contextualType?: Type; // Used to temporarily assign a contextual type during overload resolution + /** @internal */ inferenceContext?: InferenceContext; // Inference context for contextual type } export interface JSDocContainer { - /* @internal */ jsDoc?: JSDoc[]; // JSDoc that directly precedes this node - /* @internal */ jsDocCache?: readonly JSDocTag[]; // Cache for getJSDocTags + /** @internal */ jsDoc?: JSDoc[]; // JSDoc that directly precedes this node + /** @internal */ jsDocCache?: readonly JSDocTag[]; // Cache for getJSDocTags } // Ideally, `ForEachChildNodes` and `VisitEachChildNodes` would not differ. @@ -902,7 +902,7 @@ export interface JSDocContainer { // On the other hand, `visitEachChild` actually processes `Identifier`s (which really *shouldn't* have children, // but are constructed as if they could for faked-up `QualifiedName`s in the language service.) -/* @internal */ +/** @internal */ export type ForEachChildNodes = | HasChildren | MissingDeclaration @@ -943,13 +943,13 @@ export type ForEachChildNodes = | JSDocOverrideTag ; -/* @internal */ +/** @internal */ export type VisitEachChildNodes = | HasChildren | Identifier ; -/* @internal */ +/** @internal */ export type HasChildren = | QualifiedName | ComputedPropertyName @@ -1167,7 +1167,7 @@ export type HasType = // NOTE: Changing the following list requires changes to: // - `canHaveIllegalType` in factory/utilities.ts -/* @internal */ +/** @internal */ export type HasIllegalType = | ConstructorDeclaration | SetAccessorDeclaration @@ -1175,7 +1175,7 @@ export type HasIllegalType = // NOTE: Changing the following list requires changes to: // - `canHaveIllegalTypeParameters` in factory/utilities.ts -/* @internal */ +/** @internal */ export type HasIllegalTypeParameters = | ConstructorDeclaration | SetAccessorDeclaration @@ -1206,7 +1206,7 @@ export type HasExpressionInitializer = | EnumMember ; -/* @internal */ +/** @internal */ export type HasIllegalExpressionInitializer = | PropertySignature ; @@ -1226,7 +1226,7 @@ export type HasDecorators = // NOTE: Changing the following list requires changes to: // - `canHaveIllegalDecorators` in factory/utilities.ts -/* @internal */ +/** @internal */ export type HasIllegalDecorators = | PropertyAssignment | ShorthandPropertyAssignment @@ -1280,7 +1280,7 @@ export type HasModifiers = // NOTE: Changing the following list requires changes to: // - `canHaveIllegalModifiers` in factory/utilities.ts -/* @internal */ +/** @internal */ export type HasIllegalModifiers = | ClassStaticBlockDeclaration | PropertyAssignment @@ -1290,15 +1290,15 @@ export type HasIllegalModifiers = | NamespaceExportDeclaration ; -/* @internal */ +/** @internal */ export interface MutableNodeArray extends Array, TextRange { hasTrailingComma: boolean; - /* @internal */ transformFlags: TransformFlags; // Flags for transforms, possibly undefined + /** @internal */ transformFlags: TransformFlags; // Flags for transforms, possibly undefined } export interface NodeArray extends ReadonlyArray, ReadonlyTextRange { readonly hasTrailingComma: boolean; - /* @internal */ transformFlags: TransformFlags; // Flags for transforms, possibly undefined + /** @internal */ transformFlags: TransformFlags; // Flags for transforms, possibly undefined } // TODO(rbuckton): Constraint 'TKind' to 'TokenSyntaxKind' @@ -1403,11 +1403,11 @@ export type ModifiersArray = NodeArray; export const enum GeneratedIdentifierFlags { // Kinds None = 0, // Not automatically generated. - /*@internal*/ Auto = 1, // Automatically generated identifier. - /*@internal*/ Loop = 2, // Automatically generated identifier with a preference for '_i'. - /*@internal*/ Unique = 3, // Unique name based on the 'text' property. - /*@internal*/ Node = 4, // Unique name based on the node in the 'original' property. - /*@internal*/ KindMask = 7, // Mask to extract the kind of identifier from its flags. + /** @internal */ Auto = 1, // Automatically generated identifier. + /** @internal */ Loop = 2, // Automatically generated identifier with a preference for '_i'. + /** @internal */ Unique = 3, // Unique name based on the 'text' property. + /** @internal */ Node = 4, // Unique name based on the node in the 'original' property. + /** @internal */ KindMask = 7, // Mask to extract the kind of identifier from its flags. // Flags ReservedInNestedScopes = 1 << 3, // Reserve the generated name in nested scopes @@ -1424,15 +1424,15 @@ export interface Identifier extends PrimaryExpression, Declaration { */ readonly escapedText: __String; readonly originalKeywordKind?: SyntaxKind; // Original syntaxKind which get set so that we can report an error later - /*@internal*/ readonly autoGenerateFlags?: GeneratedIdentifierFlags; // Specifies whether to auto-generate the text for an identifier. - /*@internal*/ readonly autoGenerateId?: number; // Ensures unique generated identifiers get unique names, but clones get the same name. - /*@internal*/ readonly autoGeneratePrefix?: string | GeneratedNamePart; - /*@internal*/ readonly autoGenerateSuffix?: string; - /*@internal*/ generatedImportReference?: ImportSpecifier; // Reference to the generated import specifier this identifier refers to + /** @internal */ readonly autoGenerateFlags?: GeneratedIdentifierFlags; // Specifies whether to auto-generate the text for an identifier. + /** @internal */ readonly autoGenerateId?: number; // Ensures unique generated identifiers get unique names, but clones get the same name. + /** @internal */ readonly autoGeneratePrefix?: string | GeneratedNamePart; + /** @internal */ readonly autoGenerateSuffix?: string; + /** @internal */ generatedImportReference?: ImportSpecifier; // Reference to the generated import specifier this identifier refers to isInJSDocNamespace?: boolean; // if the node is a member in a JSDoc namespace - /*@internal*/ typeArguments?: NodeArray; // Only defined on synthesized nodes. Though not syntactically valid, used in emitting diagnostics, quickinfo, and signature help. - /*@internal*/ jsdocDotPos?: number; // Identifier occurs in JSDoc-style generic: Id. - /*@internal*/ hasExtendedUnicodeEscape?: boolean; + /** @internal */ typeArguments?: NodeArray; // Only defined on synthesized nodes. Though not syntactically valid, used in emitting diagnostics, quickinfo, and signature help. + /** @internal */ jsdocDotPos?: number; // Identifier occurs in JSDoc-style generic: Id. + /**@internal*/ hasExtendedUnicodeEscape?: boolean; } // Transient identifier node (marked by id === -1) @@ -1440,7 +1440,7 @@ export interface TransientIdentifier extends Identifier { resolvedSymbol: Symbol; } -/*@internal*/ +/** @internal */ export interface GeneratedIdentifier extends Identifier { autoGenerateFlags: GeneratedIdentifierFlags; } @@ -1449,7 +1449,7 @@ export interface QualifiedName extends Node { readonly kind: SyntaxKind.QualifiedName; readonly left: EntityName; readonly right: Identifier; - /*@internal*/ jsdocDotPos?: number; // QualifiedName occurs in JSDoc-style generic: Id1.Id2. + /** @internal */ jsdocDotPos?: number; // QualifiedName occurs in JSDoc-style generic: Id1.Id2. } export type EntityName = Identifier | QualifiedName; @@ -1476,28 +1476,28 @@ export interface NamedDeclaration extends Declaration { readonly name?: DeclarationName; } -/* @internal */ +/** @internal */ export interface DynamicNamedDeclaration extends NamedDeclaration { readonly name: ComputedPropertyName; } -/* @internal */ +/** @internal */ export interface DynamicNamedBinaryExpression extends BinaryExpression { readonly left: ElementAccessExpression; } -/* @internal */ +/** @internal */ // A declaration that supports late-binding (used in checker) export interface LateBoundDeclaration extends DynamicNamedDeclaration { readonly name: LateBoundName; } -/* @internal */ +/** @internal */ export interface LateBoundBinaryExpressionDeclaration extends DynamicNamedBinaryExpression { readonly left: LateBoundElementAccessExpression; } -/* @internal */ +/** @internal */ export interface LateBoundElementAccessExpression extends ElementAccessExpression { readonly argumentExpression: EntityNameExpression; } @@ -1518,18 +1518,18 @@ export interface PrivateIdentifier extends PrimaryExpression { // escaping not strictly necessary // avoids gotchas in transforms and utils readonly escapedText: __String; - /*@internal*/ readonly autoGenerateFlags?: GeneratedIdentifierFlags; // Specifies whether to auto-generate the text for an identifier. - /*@internal*/ readonly autoGenerateId?: number; // Ensures unique generated identifiers get unique names, but clones get the same name. - /*@internal*/ readonly autoGeneratePrefix?: string | GeneratedNamePart; - /*@internal*/ readonly autoGenerateSuffix?: string; + /** @internal */ readonly autoGenerateFlags?: GeneratedIdentifierFlags; // Specifies whether to auto-generate the text for an identifier. + /** @internal */ readonly autoGenerateId?: number; // Ensures unique generated identifiers get unique names, but clones get the same name. + /** @internal */ readonly autoGeneratePrefix?: string | GeneratedNamePart; + /** @internal */ readonly autoGenerateSuffix?: string; } -/*@internal*/ +/** @internal */ export interface GeneratedPrivateIdentifier extends PrivateIdentifier { autoGenerateFlags: GeneratedIdentifierFlags; } -/* @internal */ +/** @internal */ // A name that supports late-binding (used in checker) export interface LateBoundName extends ComputedPropertyName { readonly expression: EntityNameExpression; @@ -1560,7 +1560,7 @@ export interface SignatureDeclarationBase extends NamedDeclaration, JSDocContain readonly typeParameters?: NodeArray | undefined; readonly parameters: NodeArray; readonly type?: TypeNode | undefined; - /* @internal */ typeArguments?: NodeArray; // Used for quick info, replaces typeParameters for instantiated signatures + /** @internal */ typeArguments?: NodeArray; // Used for quick info, replaces typeParameters for instantiated signatures } export type SignatureDeclaration = @@ -1597,7 +1597,7 @@ export interface VariableDeclaration extends NamedDeclaration, JSDocContainer { readonly initializer?: Expression; // Optional initializer } -/* @internal */ +/** @internal */ export type InitializedVariableDeclaration = VariableDeclaration & { readonly initializer: Expression }; export interface VariableDeclarationList extends Node { @@ -1626,7 +1626,7 @@ export interface BindingElement extends NamedDeclaration { readonly initializer?: Expression; // Optional initializer } -/*@internal*/ +/** @internal */ export type BindingElementGrandparent = BindingElement["parent"]["parent"]; export interface PropertySignature extends TypeElement, JSDocContainer { @@ -1637,7 +1637,7 @@ export interface PropertySignature extends TypeElement, JSDocContainer { readonly type?: TypeNode; // Optional type annotation // The following properties are used only to report grammar errors - /* @internal */ readonly initializer?: Expression | undefined; // A property signature cannot have an initializer + /** @internal */ readonly initializer?: Expression | undefined; // A property signature cannot have an initializer } export interface PropertyDeclaration extends ClassElement, JSDocContainer { @@ -1655,29 +1655,29 @@ export interface AutoAccessorPropertyDeclaration extends PropertyDeclaration { _autoAccessorBrand: any; } -/*@internal*/ +/** @internal */ export interface PrivateIdentifierPropertyDeclaration extends PropertyDeclaration { name: PrivateIdentifier; } -/*@internal*/ +/** @internal */ export interface PrivateIdentifierAutoAccessorPropertyDeclaration extends AutoAccessorPropertyDeclaration { name: PrivateIdentifier; } -/*@internal*/ +/** @internal */ export interface PrivateIdentifierMethodDeclaration extends MethodDeclaration { name: PrivateIdentifier; } -/*@internal*/ +/** @internal */ export interface PrivateIdentifierGetAccessorDeclaration extends GetAccessorDeclaration { name: PrivateIdentifier; } -/*@internal*/ +/** @internal */ export interface PrivateIdentifierSetAccessorDeclaration extends SetAccessorDeclaration { name: PrivateIdentifier; } -/*@internal*/ +/** @internal */ export type PrivateIdentifierAccessorDeclaration = PrivateIdentifierGetAccessorDeclaration | PrivateIdentifierSetAccessorDeclaration; -/*@internal*/ +/** @internal */ export type PrivateClassElementDeclaration = | PrivateIdentifierPropertyDeclaration | PrivateIdentifierAutoAccessorPropertyDeclaration @@ -1685,7 +1685,7 @@ export type PrivateClassElementDeclaration = | PrivateIdentifierGetAccessorDeclaration | PrivateIdentifierSetAccessorDeclaration; -/* @internal */ +/** @internal */ export type InitializedPropertyDeclaration = PropertyDeclaration & { readonly initializer: Expression }; export interface ObjectLiteralElement extends NamedDeclaration { @@ -1709,10 +1709,10 @@ export interface PropertyAssignment extends ObjectLiteralElement, JSDocContainer readonly initializer: Expression; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; // property assignment cannot have decorators - /* @internal */ readonly modifiers?: NodeArray | undefined; // property assignment cannot have modifiers - /* @internal */ readonly questionToken?: QuestionToken | undefined; // property assignment cannot have a question token - /* @internal */ readonly exclamationToken?: ExclamationToken | undefined; // property assignment cannot have an exclamation token + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; // property assignment cannot have decorators + /** @internal */ readonly modifiers?: NodeArray | undefined; // property assignment cannot have modifiers + /** @internal */ readonly questionToken?: QuestionToken | undefined; // property assignment cannot have a question token + /** @internal */ readonly exclamationToken?: ExclamationToken | undefined; // property assignment cannot have an exclamation token } export interface ShorthandPropertyAssignment extends ObjectLiteralElement, JSDocContainer { @@ -1725,10 +1725,10 @@ export interface ShorthandPropertyAssignment extends ObjectLiteralElement, JSDoc readonly objectAssignmentInitializer?: Expression; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; // shorthand property assignment cannot have decorators - /* @internal */ readonly modifiers?: NodeArray | undefined; // shorthand property assignment cannot have modifiers - /* @internal */ readonly questionToken?: QuestionToken | undefined; // shorthand property assignment cannot have a question token - /* @internal */ readonly exclamationToken?: ExclamationToken | undefined; // shorthand property assignment cannot have an exclamation token + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; // shorthand property assignment cannot have decorators + /** @internal */ readonly modifiers?: NodeArray | undefined; // shorthand property assignment cannot have modifiers + /** @internal */ readonly questionToken?: QuestionToken | undefined; // shorthand property assignment cannot have a question token + /** @internal */ readonly exclamationToken?: ExclamationToken | undefined; // shorthand property assignment cannot have an exclamation token } export interface SpreadAssignment extends ObjectLiteralElement, JSDocContainer { @@ -1785,8 +1785,8 @@ export interface FunctionLikeDeclarationBase extends SignatureDeclarationBase { readonly questionToken?: QuestionToken | undefined; readonly exclamationToken?: ExclamationToken | undefined; readonly body?: Block | Expression | undefined; - /* @internal */ endFlowNode?: FlowNode; - /* @internal */ returnFlowNode?: FlowNode; + /** @internal */ endFlowNode?: FlowNode; + /** @internal */ returnFlowNode?: FlowNode; } export type FunctionLikeDeclaration = @@ -1807,7 +1807,7 @@ export interface FunctionDeclaration extends FunctionLikeDeclarationBase, Declar readonly body?: FunctionBody; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; // functions cannot have decorators + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; // functions cannot have decorators } export interface MethodSignature extends SignatureDeclarationBase, TypeElement { @@ -1834,7 +1834,7 @@ export interface MethodDeclaration extends FunctionLikeDeclarationBase, ClassEle readonly body?: FunctionBody | undefined; // The following properties are used only to report grammar errors - /* @internal */ readonly exclamationToken?: ExclamationToken | undefined; // A method cannot have an exclamation token + /** @internal */ readonly exclamationToken?: ExclamationToken | undefined; // A method cannot have an exclamation token } export interface ConstructorDeclaration extends FunctionLikeDeclarationBase, ClassElement, JSDocContainer { @@ -1844,9 +1844,9 @@ export interface ConstructorDeclaration extends FunctionLikeDeclarationBase, Cla readonly body?: FunctionBody | undefined; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; // A constructor cannot have decorators - /* @internal */ readonly typeParameters?: NodeArray; // A constructor cannot have type parameters - /* @internal */ readonly type?: TypeNode; // A constructor cannot have a return type annotation + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; // A constructor cannot have decorators + /** @internal */ readonly typeParameters?: NodeArray; // A constructor cannot have type parameters + /** @internal */ readonly type?: TypeNode; // A constructor cannot have a return type annotation } /** For when we encounter a semicolon in a class declaration. ES6 allows these as class elements. */ @@ -1865,7 +1865,7 @@ export interface GetAccessorDeclaration extends FunctionLikeDeclarationBase, Cla readonly body?: FunctionBody; // The following properties are used only to report grammar errors - /* @internal */ readonly typeParameters?: NodeArray | undefined; // A get accessor cannot have type parameters + /** @internal */ readonly typeParameters?: NodeArray | undefined; // A get accessor cannot have type parameters } // See the comment on MethodDeclaration for the intuition behind SetAccessorDeclaration being a @@ -1878,8 +1878,8 @@ export interface SetAccessorDeclaration extends FunctionLikeDeclarationBase, Cla readonly body?: FunctionBody; // The following properties are used only to report grammar errors - /* @internal */ readonly typeParameters?: NodeArray | undefined; // A set accessor cannot have type parameters - /* @internal */ readonly type?: TypeNode | undefined; // A set accessor cannot have a return type + /** @internal */ readonly typeParameters?: NodeArray | undefined; // A set accessor cannot have type parameters + /** @internal */ readonly type?: TypeNode | undefined; // A set accessor cannot have a return type } export type AccessorDeclaration = GetAccessorDeclaration | SetAccessorDeclaration; @@ -1891,7 +1891,7 @@ export interface IndexSignatureDeclaration extends SignatureDeclarationBase, Cla readonly type: TypeNode; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export interface ClassStaticBlockDeclaration extends ClassElement, JSDocContainer { @@ -1899,19 +1899,19 @@ export interface ClassStaticBlockDeclaration extends ClassElement, JSDocContaine readonly parent: ClassDeclaration | ClassExpression; readonly body: Block; - /* @internal */ endFlowNode?: FlowNode; - /* @internal */ returnFlowNode?: FlowNode; + /** @internal */ endFlowNode?: FlowNode; + /** @internal */ returnFlowNode?: FlowNode; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; - /* @internal */ readonly modifiers?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly modifiers?: NodeArray | undefined; } export interface TypeNode extends Node { _typeNodeBrand: any; } -/* @internal */ +/** @internal */ export interface TypeNode extends Node { readonly kind: TypeNodeSyntaxKind; } @@ -1935,7 +1935,7 @@ export interface ImportTypeNode extends NodeWithTypeArguments { readonly qualifier?: EntityName; } -/* @internal */ +/** @internal */ export type LiteralImportTypeNode = ImportTypeNode & { readonly argument: LiteralTypeNode & { readonly literal: StringLiteral } }; export interface ThisTypeNode extends TypeNode { @@ -1953,7 +1953,7 @@ export interface FunctionTypeNode extends FunctionOrConstructorTypeNodeBase { readonly kind: SyntaxKind.FunctionType; // The following properties are used only to report grammar errors - /* @internal */ readonly modifiers?: NodeArray | undefined; + /** @internal */ readonly modifiers?: NodeArray | undefined; } export interface ConstructorTypeNode extends FunctionOrConstructorTypeNodeBase { @@ -2055,7 +2055,7 @@ export interface TypeOperatorNode extends TypeNode { readonly type: TypeNode; } -/* @internal */ +/** @internal */ export interface UniqueTypeOperatorNode extends TypeOperatorNode { readonly operator: SyntaxKind.UniqueKeyword; } @@ -2084,9 +2084,13 @@ export interface LiteralTypeNode extends TypeNode { export interface StringLiteral extends LiteralExpression, Declaration { readonly kind: SyntaxKind.StringLiteral; - /* @internal */ readonly textSourceNode?: Identifier | StringLiteralLike | NumericLiteral | PrivateIdentifier; // Allows a StringLiteral to get its text from another node (used by transforms). - /** Note: this is only set when synthesizing a node, not during parsing. */ - /* @internal */ readonly singleQuote?: boolean; + /** @internal */ readonly textSourceNode?: Identifier | StringLiteralLike | NumericLiteral | PrivateIdentifier; // Allows a StringLiteral to get its text from another node (used by transforms). + /** + * Note: this is only set when synthesizing a node, not during parsing. + * + * @internal + */ + readonly singleQuote?: boolean; } export type StringLiteralLike = StringLiteral | NoSubstitutionTemplateLiteral; @@ -2506,7 +2510,7 @@ export interface LiteralLikeNode extends Node { export interface TemplateLiteralLikeNode extends LiteralLikeNode { rawText?: string; - /* @internal */ + /** @internal */ templateFlags?: TokenFlags; } @@ -2523,42 +2527,42 @@ export interface RegularExpressionLiteral extends LiteralExpression { export interface NoSubstitutionTemplateLiteral extends LiteralExpression, TemplateLiteralLikeNode, Declaration { readonly kind: SyntaxKind.NoSubstitutionTemplateLiteral; - /* @internal */ + /** @internal */ templateFlags?: TokenFlags; } export const enum TokenFlags { None = 0, - /* @internal */ + /** @internal */ PrecedingLineBreak = 1 << 0, - /* @internal */ + /** @internal */ PrecedingJSDocComment = 1 << 1, - /* @internal */ + /** @internal */ Unterminated = 1 << 2, - /* @internal */ + /** @internal */ ExtendedUnicodeEscape = 1 << 3, Scientific = 1 << 4, // e.g. `10e2` Octal = 1 << 5, // e.g. `0777` HexSpecifier = 1 << 6, // e.g. `0x00000000` BinarySpecifier = 1 << 7, // e.g. `0b0110010000000000` OctalSpecifier = 1 << 8, // e.g. `0o777` - /* @internal */ + /** @internal */ ContainsSeparator = 1 << 9, // e.g. `0b1100_0101` - /* @internal */ + /** @internal */ UnicodeEscape = 1 << 10, - /* @internal */ + /** @internal */ ContainsInvalidEscape = 1 << 11, // e.g. `\uhello` - /* @internal */ + /** @internal */ BinaryOrOctalSpecifier = BinarySpecifier | OctalSpecifier, - /* @internal */ + /** @internal */ NumericLiteralFlags = Scientific | Octal | HexSpecifier | BinaryOrOctalSpecifier | ContainsSeparator, - /* @internal */ + /** @internal */ TemplateLiteralLikeFlags = ContainsInvalidEscape, } export interface NumericLiteral extends LiteralExpression, Declaration { readonly kind: SyntaxKind.NumericLiteral; - /* @internal */ + /** @internal */ readonly numericLiteralFlags: TokenFlags; } @@ -2578,21 +2582,21 @@ export type LiteralToken = export interface TemplateHead extends TemplateLiteralLikeNode { readonly kind: SyntaxKind.TemplateHead; readonly parent: TemplateExpression | TemplateLiteralTypeNode; - /* @internal */ + /** @internal */ templateFlags?: TokenFlags; } export interface TemplateMiddle extends TemplateLiteralLikeNode { readonly kind: SyntaxKind.TemplateMiddle; readonly parent: TemplateSpan | TemplateLiteralTypeSpan; - /* @internal */ + /** @internal */ templateFlags?: TokenFlags; } export interface TemplateTail extends TemplateLiteralLikeNode { readonly kind: SyntaxKind.TemplateTail; readonly parent: TemplateSpan | TemplateLiteralTypeSpan; - /* @internal */ + /** @internal */ templateFlags?: TokenFlags; } @@ -2632,7 +2636,7 @@ export interface ParenthesizedExpression extends PrimaryExpression, JSDocContain readonly expression: Expression; } -/* @internal */ +/** @internal */ export interface JSDocTypeAssertion extends ParenthesizedExpression { readonly _jsDocTypeAssertionBrand: never; } @@ -2640,7 +2644,7 @@ export interface JSDocTypeAssertion extends ParenthesizedExpression { export interface ArrayLiteralExpression extends PrimaryExpression { readonly kind: SyntaxKind.ArrayLiteralExpression; readonly elements: NodeArray; - /* @internal */ + /** @internal */ multiLine?: boolean; } @@ -2663,7 +2667,7 @@ export interface ObjectLiteralExpressionBase ext // An ObjectLiteralExpression is the declaration node for an anonymous symbol. export interface ObjectLiteralExpression extends ObjectLiteralExpressionBase { readonly kind: SyntaxKind.ObjectLiteralExpression; - /* @internal */ + /** @internal */ multiLine?: boolean; } @@ -2678,7 +2682,7 @@ export interface PropertyAccessExpression extends MemberExpression, NamedDeclara readonly name: MemberName; } -/*@internal*/ +/** @internal */ export interface PrivateIdentifierPropertyAccessExpression extends PropertyAccessExpression { readonly name: PrivateIdentifier; } @@ -2688,7 +2692,7 @@ export interface PropertyAccessChain extends PropertyAccessExpression { readonly name: MemberName; } -/* @internal */ +/** @internal */ export interface PropertyAccessChainRoot extends PropertyAccessChain { readonly questionDotToken: QuestionDotToken; } @@ -2715,7 +2719,7 @@ export interface ElementAccessChain extends ElementAccessExpression { _optionalChainBrand: any; } -/* @internal */ +/** @internal */ export interface ElementAccessChainRoot extends ElementAccessChain { readonly questionDotToken: QuestionDotToken; } @@ -2739,7 +2743,7 @@ export interface CallChain extends CallExpression { _optionalChainBrand: any; } -/* @internal */ +/** @internal */ export interface CallChainRoot extends CallChain { readonly questionDotToken: QuestionDotToken; } @@ -2751,7 +2755,7 @@ export type OptionalChain = | NonNullChain ; -/* @internal */ +/** @internal */ export type OptionalChainRoot = | PropertyAccessChainRoot | ElementAccessChainRoot @@ -2832,7 +2836,7 @@ export interface TaggedTemplateExpression extends MemberExpression { readonly tag: LeftHandSideExpression; readonly typeArguments?: NodeArray; readonly template: TemplateLiteral; - /*@internal*/ questionDotToken?: QuestionDotToken; // NOTE: Invalid syntax, only used to report a grammar error. + /** @internal */ questionDotToken?: QuestionDotToken; // NOTE: Invalid syntax, only used to report a grammar error. } export type CallLikeExpression = @@ -2883,7 +2887,7 @@ export interface MetaProperty extends PrimaryExpression { readonly name: Identifier; } -/* @internal */ +/** @internal */ export interface ImportMetaProperty extends MetaProperty { readonly keywordToken: SyntaxKind.ImportKeyword; readonly name: Identifier & { readonly escapedText: __String & "meta" }; @@ -3020,8 +3024,9 @@ export interface NotEmittedStatement extends Statement { /** * Marks the end of transformed declaration to properly emit exports. + * + * @internal */ -/* @internal */ export interface EndOfDeclarationMarker extends Statement { readonly kind: SyntaxKind.EndOfDeclarationMarker; } @@ -3036,13 +3041,14 @@ export interface CommaListExpression extends Expression { /** * Marks the beginning of a merged transformed declaration. + * + * @internal */ -/* @internal */ export interface MergeDeclarationMarker extends Statement { readonly kind: SyntaxKind.MergeDeclarationMarker; } -/* @internal */ +/** @internal */ export interface SyntheticReferenceExpression extends LeftHandSideExpression { readonly kind: SyntaxKind.SyntheticReferenceExpression; readonly expression: Expression; @@ -3062,8 +3068,8 @@ export interface MissingDeclaration extends DeclarationStatement { readonly name?: Identifier; // The following properties are used only to report grammar errors - /*@internal*/ illegalDecorators?: NodeArray | undefined; - /*@internal*/ modifiers?: NodeArray | undefined; + /** @internal */ illegalDecorators?: NodeArray | undefined; + /** @internal */ modifiers?: NodeArray | undefined; } export type BlockLike = @@ -3076,7 +3082,7 @@ export type BlockLike = export interface Block extends Statement { readonly kind: SyntaxKind.Block; readonly statements: NodeArray; - /*@internal*/ multiLine?: boolean; + /** @internal */ multiLine?: boolean; } export interface VariableStatement extends Statement { @@ -3085,7 +3091,7 @@ export interface VariableStatement extends Statement { readonly declarationList: VariableDeclarationList; // The following properties are used only to report grammar errors - /* @internal*/ illegalDecorators?: NodeArray | undefined; + /** @internal */ illegalDecorators?: NodeArray | undefined; } export interface ExpressionStatement extends Statement { @@ -3093,7 +3099,7 @@ export interface ExpressionStatement extends Statement { readonly expression: Expression; } -/* @internal */ +/** @internal */ export interface PrologueDirective extends ExpressionStatement { readonly expression: StringLiteral; } @@ -3193,14 +3199,14 @@ export interface CaseClause extends Node, JSDocContainer { readonly parent: CaseBlock; readonly expression: Expression; readonly statements: NodeArray; - /* @internal */ fallthroughFlowNode?: FlowNode; + /** @internal */ fallthroughFlowNode?: FlowNode; } export interface DefaultClause extends Node { readonly kind: SyntaxKind.DefaultClause; readonly parent: CaseBlock; readonly statements: NodeArray; - /* @internal */ fallthroughFlowNode?: FlowNode; + /** @internal */ fallthroughFlowNode?: FlowNode; } export type CaseOrDefaultClause = @@ -3299,7 +3305,7 @@ export interface InterfaceDeclaration extends DeclarationStatement, JSDocContain readonly members: NodeArray; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export interface HeritageClause extends Node { @@ -3317,7 +3323,7 @@ export interface TypeAliasDeclaration extends DeclarationStatement, JSDocContain readonly type: TypeNode; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export interface EnumMember extends NamedDeclaration, JSDocContainer { @@ -3336,7 +3342,7 @@ export interface EnumDeclaration extends DeclarationStatement, JSDocContainer { readonly members: NodeArray; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export type ModuleName = @@ -3349,7 +3355,7 @@ export type ModuleBody = | JSDocNamespaceBody ; -/* @internal */ +/** @internal */ export interface AmbientModuleDeclaration extends ModuleDeclaration { readonly body?: ModuleBlock; } @@ -3362,7 +3368,7 @@ export interface ModuleDeclaration extends DeclarationStatement, JSDocContainer readonly body?: ModuleBody | JSDocNamespaceDeclaration; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export type NamespaceBody = @@ -3413,7 +3419,7 @@ export interface ImportEqualsDeclaration extends DeclarationStatement, JSDocCont readonly moduleReference: ModuleReference; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export interface ExternalModuleReference extends Node { @@ -3436,7 +3442,7 @@ export interface ImportDeclaration extends Statement { readonly assertClause?: AssertClause; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export type NamedImportBindings = @@ -3496,8 +3502,8 @@ export interface NamespaceExportDeclaration extends DeclarationStatement, JSDocC readonly name: Identifier; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; - /* @internal */ readonly modifiers?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly modifiers?: NodeArray | undefined; } export interface ExportDeclaration extends DeclarationStatement, JSDocContainer { @@ -3512,7 +3518,7 @@ export interface ExportDeclaration extends DeclarationStatement, JSDocContainer readonly assertClause?: AssertClause; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export interface NamedImports extends Node { @@ -3577,7 +3583,7 @@ export interface ExportAssignment extends DeclarationStatement, JSDocContainer { readonly expression: Expression; // The following properties are used only to report grammar errors - /* @internal */ readonly illegalDecorators?: NodeArray | undefined; + /** @internal */ readonly illegalDecorators?: NodeArray | undefined; } export interface FileReference extends TextRange { @@ -3944,14 +3950,14 @@ export interface AmdDependency { */ export interface SourceFileLike { readonly text: string; - /* @internal */ + /** @internal */ lineMap?: readonly number[]; - /* @internal */ + /** @internal */ getPositionOfLineAndCharacter?(line: number, character: number, allowEdits?: true): number; } -/* @internal */ +/** @internal */ export interface RedirectInfo { /** Source file this redirects to. */ readonly redirectTarget: SourceFile; @@ -3969,27 +3975,33 @@ export interface SourceFile extends Declaration { readonly endOfFileToken: Token; fileName: string; - /* @internal */ path: Path; + /** @internal */ path: Path; text: string; /** Resolved path can be different from path property, * when file is included through project reference is mapped to its output instead of source * in that case resolvedPath = path to output file * path = input file's path + * + * @internal */ - /* @internal */ resolvedPath: Path; + resolvedPath: Path; /** Original file name that can be different from fileName, * when file is included through project reference is mapped to its output instead of source * in that case originalFileName = name of input file * fileName = output file's name + * + * @internal */ - /* @internal */ originalFileName: string; + originalFileName: string; /** * If two source files are for the same version of the same package, one will redirect to the other. * (See `createRedirectSourceFile` in program.ts.) * The redirect will have this set. The redirected-to source file will be in `redirectTargetsMap`. + * + * @internal */ - /* @internal */ redirectInfo?: RedirectInfo; + redirectInfo?: RedirectInfo; amdDependencies: readonly AmdDependency[]; moduleName?: string; @@ -4000,7 +4012,7 @@ export interface SourceFile extends Declaration { isDeclarationFile: boolean; // this map is used by transpiler to supply alternative names for dependencies (i.e. in case of bundling) - /* @internal */ + /** @internal */ renamedDependencies?: ReadonlyESMap; /** @@ -4033,98 +4045,102 @@ export interface SourceFile extends Declaration { * CommonJS-output-format by the node module transformer and type checker, regardless of extension or context. */ impliedNodeFormat?: ModuleKind.ESNext | ModuleKind.CommonJS; - /*@internal*/ packageJsonLocations?: readonly string[]; - /*@internal*/ packageJsonScope?: PackageJsonInfo; + /** @internal */ packageJsonLocations?: readonly string[]; + /** @internal */ packageJsonScope?: PackageJsonInfo; - /* @internal */ scriptKind: ScriptKind; + /** @internal */ scriptKind: ScriptKind; /** * The first "most obvious" node that makes a file an external module. * This is intended to be the first top-level import/export, * but could be arbitrarily nested (e.g. `import.meta`). + * + * @internal */ - /* @internal */ externalModuleIndicator?: Node | true; + externalModuleIndicator?: Node | true; /** * The callback used to set the external module indicator - this is saved to * be later reused during incremental reparsing, which otherwise lacks the information * to set this field + * + * @internal */ - /* @internal */ setExternalModuleIndicator?: (file: SourceFile) => void; + setExternalModuleIndicator?: (file: SourceFile) => void; // The first node that causes this file to be a CommonJS module - /* @internal */ commonJsModuleIndicator?: Node; + /** @internal */ commonJsModuleIndicator?: Node; // JS identifier-declarations that are intended to merge with globals - /* @internal */ jsGlobalAugmentations?: SymbolTable; + /** @internal */ jsGlobalAugmentations?: SymbolTable; - /* @internal */ identifiers: ESMap; // Map from a string to an interned string - /* @internal */ nodeCount: number; - /* @internal */ identifierCount: number; - /* @internal */ symbolCount: number; + /** @internal */ identifiers: ESMap; // Map from a string to an interned string + /** @internal */ nodeCount: number; + /** @internal */ identifierCount: number; + /** @internal */ symbolCount: number; // File-level diagnostics reported by the parser (includes diagnostics about /// references // as well as code diagnostics). - /* @internal */ parseDiagnostics: DiagnosticWithLocation[]; + /** @internal */ parseDiagnostics: DiagnosticWithLocation[]; // File-level diagnostics reported by the binder. - /* @internal */ bindDiagnostics: DiagnosticWithLocation[]; - /* @internal */ bindSuggestionDiagnostics?: DiagnosticWithLocation[]; + /** @internal */ bindDiagnostics: DiagnosticWithLocation[]; + /** @internal */ bindSuggestionDiagnostics?: DiagnosticWithLocation[]; // File-level JSDoc diagnostics reported by the JSDoc parser - /* @internal */ jsDocDiagnostics?: DiagnosticWithLocation[]; + /** @internal */ jsDocDiagnostics?: DiagnosticWithLocation[]; // Stores additional file-level diagnostics reported by the program - /* @internal */ additionalSyntacticDiagnostics?: readonly DiagnosticWithLocation[]; + /** @internal */ additionalSyntacticDiagnostics?: readonly DiagnosticWithLocation[]; // Stores a line map for the file. // This field should never be used directly to obtain line map, use getLineMap function instead. - /* @internal */ lineMap: readonly number[]; - /* @internal */ classifiableNames?: ReadonlySet<__String>; + /** @internal */ lineMap: readonly number[]; + /** @internal */ classifiableNames?: ReadonlySet<__String>; // Comments containing @ts-* directives, in order. - /* @internal */ commentDirectives?: CommentDirective[]; + /** @internal */ commentDirectives?: CommentDirective[]; // Stores a mapping 'external module reference text' -> 'resolved file name' | undefined // It is used to resolve module names in the checker. // Content of this field should never be used directly - use getResolvedModuleFileName/setResolvedModuleFileName functions instead - /* @internal */ resolvedModules?: ModeAwareCache; - /* @internal */ resolvedTypeReferenceDirectiveNames: ModeAwareCache; - /* @internal */ imports: readonly StringLiteralLike[]; + /** @internal */ resolvedModules?: ModeAwareCache; + /** @internal */ resolvedTypeReferenceDirectiveNames: ModeAwareCache; + /** @internal */ imports: readonly StringLiteralLike[]; // Identifier only if `declare global` - /* @internal */ moduleAugmentations: readonly (StringLiteral | Identifier)[]; - /* @internal */ patternAmbientModules?: PatternAmbientModule[]; - /* @internal */ ambientModuleNames: readonly string[]; - /* @internal */ checkJsDirective?: CheckJsDirective; - /* @internal */ version: string; - /* @internal */ pragmas: ReadonlyPragmaMap; - /* @internal */ localJsxNamespace?: __String; - /* @internal */ localJsxFragmentNamespace?: __String; - /* @internal */ localJsxFactory?: EntityName; - /* @internal */ localJsxFragmentFactory?: EntityName; - - /* @internal */ exportedModulesFromDeclarationEmit?: ExportedModulesFromDeclarationEmit; - /* @internal */ endFlowNode?: FlowNode; -} - -/* @internal */ + /** @internal */ moduleAugmentations: readonly (StringLiteral | Identifier)[]; + /** @internal */ patternAmbientModules?: PatternAmbientModule[]; + /** @internal */ ambientModuleNames: readonly string[]; + /** @internal */ checkJsDirective?: CheckJsDirective; + /** @internal */ version: string; + /** @internal */ pragmas: ReadonlyPragmaMap; + /** @internal */ localJsxNamespace?: __String; + /** @internal */ localJsxFragmentNamespace?: __String; + /** @internal */ localJsxFactory?: EntityName; + /** @internal */ localJsxFragmentFactory?: EntityName; + + /** @internal */ exportedModulesFromDeclarationEmit?: ExportedModulesFromDeclarationEmit; + /** @internal */ endFlowNode?: FlowNode; +} + +/** @internal */ export interface CommentDirective { range: TextRange; type: CommentDirectiveType, } -/* @internal */ +/** @internal */ export const enum CommentDirectiveType { ExpectError, Ignore, } -/*@internal*/ +/** @internal */ export type ExportedModulesFromDeclarationEmit = readonly Symbol[]; export interface Bundle extends Node { readonly kind: SyntaxKind.Bundle; readonly prepends: readonly (InputFiles | UnparsedSource)[]; readonly sourceFiles: readonly SourceFile[]; - /* @internal */ syntheticFileReferences?: readonly FileReference[]; - /* @internal */ syntheticTypeReferences?: readonly FileReference[]; - /* @internal */ syntheticLibReferences?: readonly FileReference[]; - /* @internal */ hasNoDefaultLib?: boolean; + /** @internal */ syntheticFileReferences?: readonly FileReference[]; + /** @internal */ syntheticTypeReferences?: readonly FileReference[]; + /** @internal */ syntheticLibReferences?: readonly FileReference[]; + /** @internal */ hasNoDefaultLib?: boolean; } export interface InputFiles extends Node { @@ -4137,9 +4153,9 @@ export interface InputFiles extends Node { declarationText: string; declarationMapPath?: string; declarationMapText?: string; - /*@internal*/ buildInfoPath?: string; - /*@internal*/ buildInfo?: BuildInfo; - /*@internal*/ oldFileOfCurrentEmit?: boolean; + /** @internal */ buildInfoPath?: string; + /** @internal */ buildInfo?: BuildInfo; + /** @internal */ oldFileOfCurrentEmit?: boolean; } export interface UnparsedSource extends Node { @@ -4159,10 +4175,10 @@ export interface UnparsedSource extends Node { sourceMapText?: string; readonly syntheticReferences?: readonly UnparsedSyntheticReference[]; readonly texts: readonly UnparsedSourceText[]; - /*@internal*/ oldFileOfCurrentEmit?: boolean; - /*@internal*/ parsedSourceMap?: RawSourceMap | false | undefined; + /** @internal */ oldFileOfCurrentEmit?: boolean; + /** @internal */ parsedSourceMap?: RawSourceMap | false | undefined; // Adding this to satisfy services, fix later - /*@internal*/ + /** @internal */ getLineAndCharacterOfPosition(pos: number): LineAndCharacter; } @@ -4204,7 +4220,7 @@ export interface UnparsedTextLike extends UnparsedSection { export interface UnparsedSyntheticReference extends UnparsedSection { readonly kind: SyntaxKind.UnparsedSyntheticReference; readonly parent: UnparsedSource; - /*@internal*/ readonly section: BundleFileHasNoDefaultLib | BundleFileReference; + /** @internal */ readonly section: BundleFileHasNoDefaultLib | BundleFileReference; } export interface JsonSourceFile extends SourceFile { @@ -4213,7 +4229,7 @@ export interface JsonSourceFile extends SourceFile { export interface TsConfigSourceFile extends JsonSourceFile { extendedSourceFiles?: string[]; - /*@internal*/ configFileSpecs?: ConfigFileSpecs; + /** @internal */ configFileSpecs?: ConfigFileSpecs; } export interface JsonMinusNumericLiteral extends PrefixUnaryExpression { @@ -4266,10 +4282,10 @@ export interface ParseConfigHost { export type ResolvedConfigFileName = string & { _isResolvedConfigFileName: never }; export interface WriteFileCallbackData { - /*@internal*/ sourceMapUrlPos?: number; - /*@internal*/ buildInfo?: BuildInfo; - /*@internal*/ diagnostics?: readonly DiagnosticWithLocation[]; - /*@internal*/ differsOnlyInMap?: true; + /** @internal */ sourceMapUrlPos?: number; + /** @internal */ buildInfo?: BuildInfo; + /** @internal */ diagnostics?: readonly DiagnosticWithLocation[]; + /** @internal */ differsOnlyInMap?: true; } export type WriteFileCallback = ( fileName: string, @@ -4289,7 +4305,7 @@ export interface CancellationToken { throwIfCancellationRequested(): void; } -/*@internal*/ +/** @internal */ export enum FileIncludeKind { RootFile, SourceFromProjectReference, @@ -4302,49 +4318,49 @@ export enum FileIncludeKind { AutomaticTypeDirectiveFile } -/*@internal*/ +/** @internal */ export interface RootFile { kind: FileIncludeKind.RootFile, index: number; } -/*@internal*/ +/** @internal */ export interface LibFile { kind: FileIncludeKind.LibFile; index?: number; } -/*@internal*/ +/** @internal */ export type ProjectReferenceFileKind = FileIncludeKind.SourceFromProjectReference | FileIncludeKind.OutputFromProjectReference; -/*@internal*/ +/** @internal */ export interface ProjectReferenceFile { kind: ProjectReferenceFileKind; index: number; } -/*@internal*/ +/** @internal */ export type ReferencedFileKind = FileIncludeKind.Import | FileIncludeKind.ReferenceFile | FileIncludeKind.TypeReferenceDirective | FileIncludeKind.LibReferenceDirective; -/*@internal*/ +/** @internal */ export interface ReferencedFile { kind: ReferencedFileKind; file: Path; index: number; } -/*@internal*/ +/** @internal */ export interface AutomaticTypeDirectiveFile { kind: FileIncludeKind.AutomaticTypeDirectiveFile; typeReference: string; packageId: PackageId | undefined; } -/*@internal*/ +/** @internal */ export type FileIncludeReason = RootFile | LibFile | @@ -4352,13 +4368,13 @@ export type FileIncludeReason = ReferencedFile | AutomaticTypeDirectiveFile; -/*@internal*/ +/** @internal */ export const enum FilePreprocessingDiagnosticsKind { FilePreprocessingReferencedDiagnostic, FilePreprocessingFileExplainingDiagnostic } -/*@internal*/ +/** @internal */ export interface FilePreprocessingReferencedDiagnostic { kind: FilePreprocessingDiagnosticsKind.FilePreprocessingReferencedDiagnostic; reason: ReferencedFile; @@ -4366,7 +4382,7 @@ export interface FilePreprocessingReferencedDiagnostic { args?: (string | number | undefined)[]; } -/*@internal*/ +/** @internal */ export interface FilePreprocessingFileExplainingDiagnostic { kind: FilePreprocessingDiagnosticsKind.FilePreprocessingFileExplainingDiagnostic; file?: Path; @@ -4375,10 +4391,10 @@ export interface FilePreprocessingFileExplainingDiagnostic { args?: (string | number | undefined)[]; } -/*@internal*/ +/** @internal */ export type FilePreprocessingDiagnostics = FilePreprocessingReferencedDiagnostic | FilePreprocessingFileExplainingDiagnostic; -/*@internal*/ +/** @internal */ export const enum EmitOnly{ Js, Dts, @@ -4398,12 +4414,13 @@ export interface Program extends ScriptReferenceHost { /** * Get a list of file names that were passed to 'createProgram' or referenced in a * program source file but could not be located. + * + * @internal */ - /* @internal */ getMissingFilePaths(): readonly Path[]; - /* @internal */ + /** @internal */ getModuleResolutionCache(): ModuleResolutionCache | undefined; - /* @internal */ + /** @internal */ getFilesByNameMap(): ESMap; /** @@ -4417,7 +4434,7 @@ export interface Program extends ScriptReferenceHost { * will be invoked when writing the JavaScript and declaration files. */ emit(targetSourceFile?: SourceFile, writeFile?: WriteFileCallback, cancellationToken?: CancellationToken, emitOnlyDtsFiles?: boolean, customTransformers?: CustomTransformers): EmitResult; - /*@internal*/ + /** @internal */ emit(targetSourceFile?: SourceFile, writeFile?: WriteFileCallback, cancellationToken?: CancellationToken, emitOnly?: boolean | EmitOnly, customTransformers?: CustomTransformers, forceDtsEmit?: boolean): EmitResult; // eslint-disable-line @typescript-eslint/unified-signatures getOptionsDiagnostics(cancellationToken?: CancellationToken): readonly Diagnostic[]; @@ -4427,21 +4444,21 @@ export interface Program extends ScriptReferenceHost { getSemanticDiagnostics(sourceFile?: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; getDeclarationDiagnostics(sourceFile?: SourceFile, cancellationToken?: CancellationToken): readonly DiagnosticWithLocation[]; getConfigFileParsingDiagnostics(): readonly Diagnostic[]; - /* @internal */ getSuggestionDiagnostics(sourceFile: SourceFile, cancellationToken?: CancellationToken): readonly DiagnosticWithLocation[]; + /** @internal */ getSuggestionDiagnostics(sourceFile: SourceFile, cancellationToken?: CancellationToken): readonly DiagnosticWithLocation[]; - /* @internal */ getBindAndCheckDiagnostics(sourceFile: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; - /* @internal */ getProgramDiagnostics(sourceFile: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; + /** @internal */ getBindAndCheckDiagnostics(sourceFile: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; + /** @internal */ getProgramDiagnostics(sourceFile: SourceFile, cancellationToken?: CancellationToken): readonly Diagnostic[]; /** * Gets a type checker that can be used to semantically analyze source files in the program. */ getTypeChecker(): TypeChecker; - /* @internal */ getCommonSourceDirectory(): string; + /** @internal */ getCommonSourceDirectory(): string; - /* @internal */ getCachedSemanticDiagnostics(sourceFile?: SourceFile): readonly Diagnostic[] | undefined; + /** @internal */ getCachedSemanticDiagnostics(sourceFile?: SourceFile): readonly Diagnostic[] | undefined; - /* @internal */ getClassifiableNames(): Set<__String>; + /** @internal */ getClassifiableNames(): Set<__String>; getNodeCount(): number; getIdentifierCount(): number; @@ -4450,53 +4467,75 @@ export interface Program extends ScriptReferenceHost { getInstantiationCount(): number; getRelationCacheSizes(): { assignable: number, identity: number, subtype: number, strictSubtype: number }; - /* @internal */ getFileProcessingDiagnostics(): FilePreprocessingDiagnostics[] | undefined; - /* @internal */ getResolvedTypeReferenceDirectives(): ModeAwareCache; + /** @internal */ getFileProcessingDiagnostics(): FilePreprocessingDiagnostics[] | undefined; + /** @internal */ getResolvedTypeReferenceDirectives(): ModeAwareCache; isSourceFileFromExternalLibrary(file: SourceFile): boolean; isSourceFileDefaultLibrary(file: SourceFile): boolean; // For testing purposes only. // This is set on created program to let us know how the program was created using old program - /* @internal */ readonly structureIsReused: StructureIsReused; + /** @internal */ readonly structureIsReused: StructureIsReused; - /* @internal */ getSourceFileFromReference(referencingFile: SourceFile | UnparsedSource, ref: FileReference): SourceFile | undefined; - /* @internal */ getLibFileFromReference(ref: FileReference): SourceFile | undefined; + /** @internal */ getSourceFileFromReference(referencingFile: SourceFile | UnparsedSource, ref: FileReference): SourceFile | undefined; + /** @internal */ getLibFileFromReference(ref: FileReference): SourceFile | undefined; - /** Given a source file, get the name of the package it was imported from. */ - /* @internal */ sourceFileToPackageName: ESMap; - /** Set of all source files that some other source file redirects to. */ - /* @internal */ redirectTargetsMap: MultiMap; - /** Whether any (non-external, non-declaration) source files use `node:`-prefixed module specifiers. */ - /* @internal */ readonly usesUriStyleNodeCoreModules: boolean; - /** Is the file emitted file */ - /* @internal */ isEmittedFile(file: string): boolean; - /* @internal */ getFileIncludeReasons(): MultiMap; - /* @internal */ useCaseSensitiveFileNames(): boolean; + /** + * Given a source file, get the name of the package it was imported from. + * + * @internal + */ + sourceFileToPackageName: ESMap; + /** + * Set of all source files that some other source file redirects to. + * + * @internal + */ + redirectTargetsMap: MultiMap; + /** + * Whether any (non-external, non-declaration) source files use `node:`-prefixed module specifiers. + * + * @internal + */ + readonly usesUriStyleNodeCoreModules: boolean; + /** + * Is the file emitted file + * + * @internal + */ + isEmittedFile(file: string): boolean; + /** @internal */ getFileIncludeReasons(): MultiMap; + /** @internal */ useCaseSensitiveFileNames(): boolean; - /* @internal */ getResolvedModuleWithFailedLookupLocationsFromCache(moduleName: string, containingFile: string, mode?: ModuleKind.CommonJS | ModuleKind.ESNext): ResolvedModuleWithFailedLookupLocations | undefined; + /** @internal */ getResolvedModuleWithFailedLookupLocationsFromCache(moduleName: string, containingFile: string, mode?: ModuleKind.CommonJS | ModuleKind.ESNext): ResolvedModuleWithFailedLookupLocations | undefined; getProjectReferences(): readonly ProjectReference[] | undefined; getResolvedProjectReferences(): readonly (ResolvedProjectReference | undefined)[] | undefined; - /*@internal*/ getProjectReferenceRedirect(fileName: string): string | undefined; - /*@internal*/ getResolvedProjectReferenceToRedirect(fileName: string): ResolvedProjectReference | undefined; - /*@internal*/ forEachResolvedProjectReference(cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined): T | undefined; - /*@internal*/ getResolvedProjectReferenceByPath(projectReferencePath: Path): ResolvedProjectReference | undefined; - /*@internal*/ isSourceOfProjectReferenceRedirect(fileName: string): boolean; - /*@internal*/ getBuildInfo?(bundle: BundleBuildInfo | undefined): BuildInfo; - /*@internal*/ emitBuildInfo(writeFile?: WriteFileCallback, cancellationToken?: CancellationToken): EmitResult; + /** @internal */ getProjectReferenceRedirect(fileName: string): string | undefined; + /** @internal */ getResolvedProjectReferenceToRedirect(fileName: string): ResolvedProjectReference | undefined; + /** @internal */ forEachResolvedProjectReference(cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined): T | undefined; + /** @internal */ getResolvedProjectReferenceByPath(projectReferencePath: Path): ResolvedProjectReference | undefined; + /** @internal */ isSourceOfProjectReferenceRedirect(fileName: string): boolean; + /** @internal */ getBuildInfo?(bundle: BundleBuildInfo | undefined): BuildInfo; + /** @internal */ emitBuildInfo(writeFile?: WriteFileCallback, cancellationToken?: CancellationToken): EmitResult; /** * This implementation handles file exists to be true if file is source of project reference redirect when program is created using useSourceOfProjectReferenceRedirect + * + * @internal */ - /*@internal*/ fileExists(fileName: string): boolean; - /** Call compilerHost.writeFile on host program was created with */ - /*@internal*/ writeFile: WriteFileCallback; + fileExists(fileName: string): boolean; + /** + * Call compilerHost.writeFile on host program was created with + * + * @internal + */ + writeFile: WriteFileCallback; } -/*@internal*/ +/** @internal */ export interface Program extends TypeCheckerHost, ModuleSpecifierResolutionHost { } -/* @internal */ +/** @internal */ export type RedirectTargetsMap = ReadonlyESMap; export interface ResolvedProjectReference { @@ -4505,7 +4544,7 @@ export interface ResolvedProjectReference { references?: readonly (ResolvedProjectReference | undefined)[]; } -/* @internal */ +/** @internal */ export const enum StructureIsReused { Not, SafeModules, @@ -4528,7 +4567,7 @@ export interface CustomTransformers { afterDeclarations?: (TransformerFactory | CustomTransformerFactory)[]; } -/*@internal*/ +/** @internal */ export interface EmitTransformers { scriptTransformers: readonly TransformerFactory[]; declarationTransformers: readonly TransformerFactory[]; @@ -4549,7 +4588,7 @@ export interface SourceMapSpan { sourceIndex: number; } -/* @internal */ +/** @internal */ export interface SourceMapEmitResult { inputSourceFileNames: readonly string[]; // Input source file (which one can use on program to get the file), 1:1 mapping with the sourceMap.sources list sourceMap: RawSourceMap; @@ -4583,10 +4622,10 @@ export interface EmitResult { /** Contains declaration emit diagnostics */ diagnostics: readonly Diagnostic[]; emittedFiles?: string[]; // Array of files the compiler wrote to disk - /* @internal */ sourceMaps?: SourceMapEmitResult[]; // Array of sourceMapData if compiler emitted sourcemaps + /** @internal */ sourceMaps?: SourceMapEmitResult[]; // Array of sourceMapData if compiler emitted sourcemaps } -/* @internal */ +/** @internal */ export interface TypeCheckerHost extends ModuleSpecifierResolutionHost { getCompilerOptions(): CompilerOptions; @@ -4601,54 +4640,60 @@ export interface TypeCheckerHost extends ModuleSpecifierResolutionHost { export interface TypeChecker { getTypeOfSymbolAtLocation(symbol: Symbol, node: Node): Type; - /* @internal */ getTypeOfSymbol(symbol: Symbol): Type; + /** @internal */ getTypeOfSymbol(symbol: Symbol): Type; getDeclaredTypeOfSymbol(symbol: Symbol): Type; getPropertiesOfType(type: Type): Symbol[]; getPropertyOfType(type: Type, propertyName: string): Symbol | undefined; getPrivateIdentifierPropertyOfType(leftType: Type, name: string, location: Node): Symbol | undefined; - /* @internal */ getTypeOfPropertyOfType(type: Type, propertyName: string): Type | undefined; + /** @internal */ getTypeOfPropertyOfType(type: Type, propertyName: string): Type | undefined; getIndexInfoOfType(type: Type, kind: IndexKind): IndexInfo | undefined; getIndexInfosOfType(type: Type): readonly IndexInfo[]; getIndexInfosOfIndexSymbol: (indexSymbol: Symbol) => IndexInfo[]; getSignaturesOfType(type: Type, kind: SignatureKind): readonly Signature[]; getIndexTypeOfType(type: Type, kind: IndexKind): Type | undefined; - /* @internal */ getIndexType(type: Type): Type; + /** @internal */ getIndexType(type: Type): Type; getBaseTypes(type: InterfaceType): BaseType[]; getBaseTypeOfLiteralType(type: Type): Type; getWidenedType(type: Type): Type; - /* @internal */ + /** @internal */ getPromisedTypeOfPromise(promise: Type, errorNode?: Node): Type | undefined; - /* @internal */ + /** @internal */ getAwaitedType(type: Type): Type | undefined; getReturnTypeOfSignature(signature: Signature): Type; /** * Gets the type of a parameter at a given position in a signature. * Returns `any` if the index is not valid. + * + * @internal */ - /* @internal */ getParameterType(signature: Signature, parameterIndex: number): Type; - /* @internal */ getParameterIdentifierNameAtPosition(signature: Signature, parameterIndex: number): [parameterName: __String, isRestParameter: boolean] | undefined; + getParameterType(signature: Signature, parameterIndex: number): Type; + /** @internal */ getParameterIdentifierNameAtPosition(signature: Signature, parameterIndex: number): [parameterName: __String, isRestParameter: boolean] | undefined; getNullableType(type: Type, flags: TypeFlags): Type; getNonNullableType(type: Type): Type; - /* @internal */ getNonOptionalType(type: Type): Type; - /* @internal */ isNullableType(type: Type): boolean; + /** @internal */ getNonOptionalType(type: Type): Type; + /** @internal */ isNullableType(type: Type): boolean; getTypeArguments(type: TypeReference): readonly Type[]; // TODO: GH#18217 `xToDeclaration` calls are frequently asserted as defined. /** Note that the resulting nodes cannot be checked. */ typeToTypeNode(type: Type, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): TypeNode | undefined; - /* @internal */ typeToTypeNode(type: Type, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, tracker?: SymbolTracker): TypeNode | undefined; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ typeToTypeNode(type: Type, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, tracker?: SymbolTracker): TypeNode | undefined; // eslint-disable-line @typescript-eslint/unified-signatures /** Note that the resulting nodes cannot be checked. */ signatureToSignatureDeclaration(signature: Signature, kind: SyntaxKind, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): SignatureDeclaration & {typeArguments?: NodeArray} | undefined; - /* @internal */ signatureToSignatureDeclaration(signature: Signature, kind: SyntaxKind, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, tracker?: SymbolTracker): SignatureDeclaration & {typeArguments?: NodeArray} | undefined; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ signatureToSignatureDeclaration(signature: Signature, kind: SyntaxKind, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, tracker?: SymbolTracker): SignatureDeclaration & {typeArguments?: NodeArray} | undefined; // eslint-disable-line @typescript-eslint/unified-signatures /** Note that the resulting nodes cannot be checked. */ indexInfoToIndexSignatureDeclaration(indexInfo: IndexInfo, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): IndexSignatureDeclaration | undefined; - /* @internal */ indexInfoToIndexSignatureDeclaration(indexInfo: IndexInfo, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, tracker?: SymbolTracker): IndexSignatureDeclaration | undefined; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ indexInfoToIndexSignatureDeclaration(indexInfo: IndexInfo, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, tracker?: SymbolTracker): IndexSignatureDeclaration | undefined; // eslint-disable-line @typescript-eslint/unified-signatures /** Note that the resulting nodes cannot be checked. */ symbolToEntityName(symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): EntityName | undefined; /** Note that the resulting nodes cannot be checked. */ symbolToExpression(symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): Expression | undefined; - /** Note that the resulting nodes cannot be checked. */ - /* @internal */ symbolToNode(symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): Node | undefined; + /** + * Note that the resulting nodes cannot be checked. + * + * @internal + */ + symbolToNode(symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): Node | undefined; /** Note that the resulting nodes cannot be checked. */ symbolToTypeParameterDeclarations(symbol: Symbol, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): NodeArray | undefined; /** Note that the resulting nodes cannot be checked. */ @@ -4658,7 +4703,7 @@ export interface TypeChecker { getSymbolsInScope(location: Node, meaning: SymbolFlags): Symbol[]; getSymbolAtLocation(node: Node): Symbol | undefined; - /* @internal */ getIndexInfosAtLocation(node: Node): readonly IndexInfo[] | undefined; + /** @internal */ getIndexInfosAtLocation(node: Node): readonly IndexInfo[] | undefined; getSymbolsOfParameterPropertyDeclaration(parameter: ParameterDeclaration, parameterName: string): Symbol[]; /** * The function returns the value (local variable) symbol of an identifier in the short-hand property assignment. @@ -4686,10 +4731,10 @@ export interface TypeChecker { symbolToString(symbol: Symbol, enclosingDeclaration?: Node, meaning?: SymbolFlags, flags?: SymbolFormatFlags): string; typePredicateToString(predicate: TypePredicate, enclosingDeclaration?: Node, flags?: TypeFormatFlags): string; - /* @internal */ writeSignature(signature: Signature, enclosingDeclaration?: Node, flags?: TypeFormatFlags, kind?: SignatureKind, writer?: EmitTextWriter): string; - /* @internal */ writeType(type: Type, enclosingDeclaration?: Node, flags?: TypeFormatFlags, writer?: EmitTextWriter): string; - /* @internal */ writeSymbol(symbol: Symbol, enclosingDeclaration?: Node, meaning?: SymbolFlags, flags?: SymbolFormatFlags, writer?: EmitTextWriter): string; - /* @internal */ writeTypePredicate(predicate: TypePredicate, enclosingDeclaration?: Node, flags?: TypeFormatFlags, writer?: EmitTextWriter): string; + /** @internal */ writeSignature(signature: Signature, enclosingDeclaration?: Node, flags?: TypeFormatFlags, kind?: SignatureKind, writer?: EmitTextWriter): string; + /** @internal */ writeType(type: Type, enclosingDeclaration?: Node, flags?: TypeFormatFlags, writer?: EmitTextWriter): string; + /** @internal */ writeSymbol(symbol: Symbol, enclosingDeclaration?: Node, meaning?: SymbolFlags, flags?: SymbolFormatFlags, writer?: EmitTextWriter): string; + /** @internal */ writeTypePredicate(predicate: TypePredicate, enclosingDeclaration?: Node, flags?: TypeFormatFlags, writer?: EmitTextWriter): string; getFullyQualifiedName(symbol: Symbol): string; getAugmentedPropertiesOfType(type: Type): Symbol[]; @@ -4697,12 +4742,12 @@ export interface TypeChecker { getRootSymbols(symbol: Symbol): readonly Symbol[]; getSymbolOfExpando(node: Node, allowDeclaration: boolean): Symbol | undefined; getContextualType(node: Expression): Type | undefined; - /* @internal */ getContextualType(node: Expression, contextFlags?: ContextFlags): Type | undefined; // eslint-disable-line @typescript-eslint/unified-signatures - /* @internal */ getContextualTypeForObjectLiteralElement(element: ObjectLiteralElementLike): Type | undefined; - /* @internal */ getContextualTypeForArgumentAtIndex(call: CallLikeExpression, argIndex: number): Type | undefined; - /* @internal */ getContextualTypeForJsxAttribute(attribute: JsxAttribute | JsxSpreadAttribute): Type | undefined; - /* @internal */ isContextSensitive(node: Expression | MethodDeclaration | ObjectLiteralElementLike | JsxAttributeLike): boolean; - /* @internal */ getTypeOfPropertyOfContextualType(type: Type, name: __String): Type | undefined; + /** @internal */ getContextualType(node: Expression, contextFlags?: ContextFlags): Type | undefined; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ getContextualTypeForObjectLiteralElement(element: ObjectLiteralElementLike): Type | undefined; + /** @internal */ getContextualTypeForArgumentAtIndex(call: CallLikeExpression, argIndex: number): Type | undefined; + /** @internal */ getContextualTypeForJsxAttribute(attribute: JsxAttribute | JsxSpreadAttribute): Type | undefined; + /** @internal */ isContextSensitive(node: Expression | MethodDeclaration | ObjectLiteralElementLike | JsxAttributeLike): boolean; + /** @internal */ getTypeOfPropertyOfContextualType(type: Type, name: __String): Type | undefined; /** * returns unknownSignature in the case of an error. @@ -4710,31 +4755,39 @@ export interface TypeChecker { * @param argumentCount Apparent number of arguments, passed in case of a possibly incomplete call. This should come from an ArgumentListInfo. See `signatureHelp.ts`. */ getResolvedSignature(node: CallLikeExpression, candidatesOutArray?: Signature[], argumentCount?: number): Signature | undefined; - /* @internal */ getResolvedSignatureForSignatureHelp(node: CallLikeExpression, candidatesOutArray?: Signature[], argumentCount?: number): Signature | undefined; - /* @internal */ getResolvedSignatureForStringLiteralCompletions(call: CallLikeExpression, editingArgument: Node, candidatesOutArray: Signature[]): Signature | undefined; - /* @internal */ getExpandedParameters(sig: Signature): readonly (readonly Symbol[])[]; - /* @internal */ hasEffectiveRestParameter(sig: Signature): boolean; - /* @internal */ containsArgumentsReference(declaration: SignatureDeclaration): boolean; + /** @internal */ getResolvedSignatureForSignatureHelp(node: CallLikeExpression, candidatesOutArray?: Signature[], argumentCount?: number): Signature | undefined; + /** @internal */ getResolvedSignatureForStringLiteralCompletions(call: CallLikeExpression, editingArgument: Node, candidatesOutArray: Signature[]): Signature | undefined; + /** @internal */ getExpandedParameters(sig: Signature): readonly (readonly Symbol[])[]; + /** @internal */ hasEffectiveRestParameter(sig: Signature): boolean; + /** @internal */ containsArgumentsReference(declaration: SignatureDeclaration): boolean; getSignatureFromDeclaration(declaration: SignatureDeclaration): Signature | undefined; isImplementationOfOverload(node: SignatureDeclaration): boolean | undefined; isUndefinedSymbol(symbol: Symbol): boolean; isArgumentsSymbol(symbol: Symbol): boolean; isUnknownSymbol(symbol: Symbol): boolean; - /* @internal */ getMergedSymbol(symbol: Symbol): Symbol; + /** @internal */ getMergedSymbol(symbol: Symbol): Symbol; getConstantValue(node: EnumMember | PropertyAccessExpression | ElementAccessExpression): string | number | undefined; isValidPropertyAccess(node: PropertyAccessExpression | QualifiedName | ImportTypeNode, propertyName: string): boolean; - /** Exclude accesses to private properties. */ - /* @internal */ isValidPropertyAccessForCompletions(node: PropertyAccessExpression | ImportTypeNode | QualifiedName, type: Type, property: Symbol): boolean; + /** + * Exclude accesses to private properties. + * + * @internal + */ + isValidPropertyAccessForCompletions(node: PropertyAccessExpression | ImportTypeNode | QualifiedName, type: Type, property: Symbol): boolean; /** Follow all aliases to get the original symbol. */ getAliasedSymbol(symbol: Symbol): Symbol; /** Follow a *single* alias to get the immediately aliased symbol. */ getImmediateAliasedSymbol(symbol: Symbol): Symbol | undefined; getExportsOfModule(moduleSymbol: Symbol): Symbol[]; - /** Unlike `getExportsOfModule`, this includes properties of an `export =` value. */ - /* @internal */ getExportsAndPropertiesOfModule(moduleSymbol: Symbol): Symbol[]; - /* @internal */ forEachExportAndPropertyOfModule(moduleSymbol: Symbol, cb: (symbol: Symbol, key: __String) => void): void; + /** + * Unlike `getExportsOfModule`, this includes properties of an `export =` value. + * + * @internal + */ + getExportsAndPropertiesOfModule(moduleSymbol: Symbol): Symbol[]; + /** @internal */ forEachExportAndPropertyOfModule(moduleSymbol: Symbol, cb: (symbol: Symbol, key: __String) => void): void; getJsxIntrinsicTagNamesAt(location: Node): Symbol[]; isOptionalParameter(node: ParameterDeclaration): boolean; getAmbientModules(): Symbol[]; @@ -4743,43 +4796,45 @@ export interface TypeChecker { /** * Unlike `tryGetMemberInModuleExports`, this includes properties of an `export =` value. * Does *not* return properties of primitive types. + * + * @internal */ - /* @internal */ tryGetMemberInModuleExportsAndProperties(memberName: string, moduleSymbol: Symbol): Symbol | undefined; + tryGetMemberInModuleExportsAndProperties(memberName: string, moduleSymbol: Symbol): Symbol | undefined; getApparentType(type: Type): Type; - /* @internal */ getSuggestedSymbolForNonexistentProperty(name: MemberName | string, containingType: Type): Symbol | undefined; - /* @internal */ getSuggestedSymbolForNonexistentJSXAttribute(name: Identifier | string, containingType: Type): Symbol | undefined; - /* @internal */ getSuggestionForNonexistentProperty(name: MemberName | string, containingType: Type): string | undefined; - /* @internal */ getSuggestedSymbolForNonexistentSymbol(location: Node, name: string, meaning: SymbolFlags): Symbol | undefined; - /* @internal */ getSuggestionForNonexistentSymbol(location: Node, name: string, meaning: SymbolFlags): string | undefined; - /* @internal */ getSuggestedSymbolForNonexistentModule(node: Identifier, target: Symbol): Symbol | undefined; - /* @internal */ getSuggestedSymbolForNonexistentClassMember(name: string, baseType: Type): Symbol | undefined; - /* @internal */ getSuggestionForNonexistentExport(node: Identifier, target: Symbol): string | undefined; + /** @internal */ getSuggestedSymbolForNonexistentProperty(name: MemberName | string, containingType: Type): Symbol | undefined; + /** @internal */ getSuggestedSymbolForNonexistentJSXAttribute(name: Identifier | string, containingType: Type): Symbol | undefined; + /** @internal */ getSuggestionForNonexistentProperty(name: MemberName | string, containingType: Type): string | undefined; + /** @internal */ getSuggestedSymbolForNonexistentSymbol(location: Node, name: string, meaning: SymbolFlags): Symbol | undefined; + /** @internal */ getSuggestionForNonexistentSymbol(location: Node, name: string, meaning: SymbolFlags): string | undefined; + /** @internal */ getSuggestedSymbolForNonexistentModule(node: Identifier, target: Symbol): Symbol | undefined; + /** @internal */ getSuggestedSymbolForNonexistentClassMember(name: string, baseType: Type): Symbol | undefined; + /** @internal */ getSuggestionForNonexistentExport(node: Identifier, target: Symbol): string | undefined; getBaseConstraintOfType(type: Type): Type | undefined; getDefaultFromTypeParameter(type: Type): Type | undefined; - /* @internal */ getAnyType(): Type; - /* @internal */ getStringType(): Type; - /* @internal */ getNumberType(): Type; - /* @internal */ getBooleanType(): Type; - /* @internal */ getFalseType(fresh?: boolean): Type; - /* @internal */ getTrueType(fresh?: boolean): Type; - /* @internal */ getVoidType(): Type; - /* @internal */ getUndefinedType(): Type; - /* @internal */ getNullType(): Type; - /* @internal */ getESSymbolType(): Type; - /* @internal */ getNeverType(): Type; - /* @internal */ getOptionalType(): Type; - /* @internal */ getUnionType(types: Type[], subtypeReduction?: UnionReduction): Type; - /* @internal */ createArrayType(elementType: Type): Type; - /* @internal */ getElementTypeOfArrayType(arrayType: Type): Type | undefined; - /* @internal */ createPromiseType(type: Type): Type; - /* @internal */ getPromiseType(): Type; - /* @internal */ getPromiseLikeType(): Type; - /* @internal */ getAsyncIterableType(): Type | undefined; - - /* @internal */ isTypeAssignableTo(source: Type, target: Type): boolean; - /* @internal */ createAnonymousType(symbol: Symbol | undefined, members: SymbolTable, callSignatures: Signature[], constructSignatures: Signature[], indexInfos: IndexInfo[]): Type; - /* @internal */ createSignature( + /** @internal */ getAnyType(): Type; + /** @internal */ getStringType(): Type; + /** @internal */ getNumberType(): Type; + /** @internal */ getBooleanType(): Type; + /** @internal */ getFalseType(fresh?: boolean): Type; + /** @internal */ getTrueType(fresh?: boolean): Type; + /** @internal */ getVoidType(): Type; + /** @internal */ getUndefinedType(): Type; + /** @internal */ getNullType(): Type; + /** @internal */ getESSymbolType(): Type; + /** @internal */ getNeverType(): Type; + /** @internal */ getOptionalType(): Type; + /** @internal */ getUnionType(types: Type[], subtypeReduction?: UnionReduction): Type; + /** @internal */ createArrayType(elementType: Type): Type; + /** @internal */ getElementTypeOfArrayType(arrayType: Type): Type | undefined; + /** @internal */ createPromiseType(type: Type): Type; + /** @internal */ getPromiseType(): Type; + /** @internal */ getPromiseLikeType(): Type; + /** @internal */ getAsyncIterableType(): Type | undefined; + + /** @internal */ isTypeAssignableTo(source: Type, target: Type): boolean; + /** @internal */ createAnonymousType(symbol: Symbol | undefined, members: SymbolTable, callSignatures: Signature[], constructSignatures: Signature[], indexInfos: IndexInfo[]): Type; + /** @internal */ createSignature( declaration: SignatureDeclaration | undefined, typeParameters: readonly TypeParameter[] | undefined, thisParameter: Symbol | undefined, @@ -4789,47 +4844,51 @@ export interface TypeChecker { minArgumentCount: number, flags: SignatureFlags ): Signature; - /* @internal */ createSymbol(flags: SymbolFlags, name: __String): TransientSymbol; - /* @internal */ createIndexInfo(keyType: Type, type: Type, isReadonly: boolean, declaration?: SignatureDeclaration): IndexInfo; - /* @internal */ isSymbolAccessible(symbol: Symbol, enclosingDeclaration: Node | undefined, meaning: SymbolFlags, shouldComputeAliasToMarkVisible: boolean): SymbolAccessibilityResult; - /* @internal */ tryFindAmbientModule(moduleName: string): Symbol | undefined; - /* @internal */ tryFindAmbientModuleWithoutAugmentations(moduleName: string): Symbol | undefined; + /** @internal */ createSymbol(flags: SymbolFlags, name: __String): TransientSymbol; + /** @internal */ createIndexInfo(keyType: Type, type: Type, isReadonly: boolean, declaration?: SignatureDeclaration): IndexInfo; + /** @internal */ isSymbolAccessible(symbol: Symbol, enclosingDeclaration: Node | undefined, meaning: SymbolFlags, shouldComputeAliasToMarkVisible: boolean): SymbolAccessibilityResult; + /** @internal */ tryFindAmbientModule(moduleName: string): Symbol | undefined; + /** @internal */ tryFindAmbientModuleWithoutAugmentations(moduleName: string): Symbol | undefined; - /* @internal */ getSymbolWalker(accept?: (symbol: Symbol) => boolean): SymbolWalker; + /** @internal */ getSymbolWalker(accept?: (symbol: Symbol) => boolean): SymbolWalker; // Should not be called directly. Should only be accessed through the Program instance. - /* @internal */ getDiagnostics(sourceFile?: SourceFile, cancellationToken?: CancellationToken): Diagnostic[]; - /* @internal */ getGlobalDiagnostics(): Diagnostic[]; - /* @internal */ getEmitResolver(sourceFile?: SourceFile, cancellationToken?: CancellationToken): EmitResolver; - - /* @internal */ getNodeCount(): number; - /* @internal */ getIdentifierCount(): number; - /* @internal */ getSymbolCount(): number; - /* @internal */ getTypeCount(): number; - /* @internal */ getInstantiationCount(): number; - /* @internal */ getRelationCacheSizes(): { assignable: number, identity: number, subtype: number, strictSubtype: number }; - /* @internal */ getRecursionIdentity(type: Type): object | undefined; - /* @internal */ getUnmatchedProperties(source: Type, target: Type, requireOptionalProperties: boolean, matchDiscriminantProperties: boolean): IterableIterator; - - /* @internal */ isArrayType(type: Type): boolean; - /* @internal */ isTupleType(type: Type): boolean; - /* @internal */ isArrayLikeType(type: Type): boolean; + /** @internal */ getDiagnostics(sourceFile?: SourceFile, cancellationToken?: CancellationToken): Diagnostic[]; + /** @internal */ getGlobalDiagnostics(): Diagnostic[]; + /** @internal */ getEmitResolver(sourceFile?: SourceFile, cancellationToken?: CancellationToken): EmitResolver; + + /** @internal */ getNodeCount(): number; + /** @internal */ getIdentifierCount(): number; + /** @internal */ getSymbolCount(): number; + /** @internal */ getTypeCount(): number; + /** @internal */ getInstantiationCount(): number; + /** @internal */ getRelationCacheSizes(): { assignable: number, identity: number, subtype: number, strictSubtype: number }; + /** @internal */ getRecursionIdentity(type: Type): object | undefined; + /** @internal */ getUnmatchedProperties(source: Type, target: Type, requireOptionalProperties: boolean, matchDiscriminantProperties: boolean): IterableIterator; + + /** @internal */ isArrayType(type: Type): boolean; + /** @internal */ isTupleType(type: Type): boolean; + /** @internal */ isArrayLikeType(type: Type): boolean; /** * True if `contextualType` should not be considered for completions because * e.g. it specifies `kind: "a"` and obj has `kind: "b"`. + * + * @internal */ - /* @internal */ isTypeInvalidDueToUnionDiscriminant(contextualType: Type, obj: ObjectLiteralExpression | JsxAttributes): boolean; - /* @internal */ getExactOptionalProperties(type: Type): Symbol[]; + isTypeInvalidDueToUnionDiscriminant(contextualType: Type, obj: ObjectLiteralExpression | JsxAttributes): boolean; + /** @internal */ getExactOptionalProperties(type: Type): Symbol[]; /** * For a union, will include a property if it's defined in *any* of the member types. * So for `{ a } | { b }`, this will include both `a` and `b`. * Does not include properties of primitive types. + * + * @internal */ - /* @internal */ getAllPossiblePropertiesOfTypes(type: readonly Type[]): Symbol[]; - /* @internal */ resolveName(name: string, location: Node | undefined, meaning: SymbolFlags, excludeGlobals: boolean): Symbol | undefined; - /* @internal */ getJsxNamespace(location?: Node): string; - /* @internal */ getJsxFragmentFactory(location: Node): string | undefined; + getAllPossiblePropertiesOfTypes(type: readonly Type[]): Symbol[]; + /** @internal */ resolveName(name: string, location: Node | undefined, meaning: SymbolFlags, excludeGlobals: boolean): Symbol | undefined; + /** @internal */ getJsxNamespace(location?: Node): string; + /** @internal */ getJsxFragmentFactory(location: Node): string | undefined; /** * Note that this will return undefined in the following case: @@ -4839,24 +4898,34 @@ export interface TypeChecker { * <> * Where `C` is the symbol we're looking for. * This should be called in a loop climbing parents of the symbol, so we'll get `N`. + * + * @internal */ - /* @internal */ getAccessibleSymbolChain(symbol: Symbol, enclosingDeclaration: Node | undefined, meaning: SymbolFlags, useOnlyExternalAliasing: boolean): Symbol[] | undefined; + getAccessibleSymbolChain(symbol: Symbol, enclosingDeclaration: Node | undefined, meaning: SymbolFlags, useOnlyExternalAliasing: boolean): Symbol[] | undefined; getTypePredicateOfSignature(signature: Signature): TypePredicate | undefined; - /* @internal */ resolveExternalModuleName(moduleSpecifier: Expression): Symbol | undefined; + /** @internal */ resolveExternalModuleName(moduleSpecifier: Expression): Symbol | undefined; /** * An external module with an 'export =' declaration resolves to the target of the 'export =' declaration, * and an external module with no 'export =' declaration resolves to the module itself. + * + * @internal + */ + resolveExternalModuleSymbol(symbol: Symbol): Symbol; + /** + * @param node A location where we might consider accessing `this`. Not necessarily a ThisExpression. + * + * @internal */ - /* @internal */ resolveExternalModuleSymbol(symbol: Symbol): Symbol; - /** @param node A location where we might consider accessing `this`. Not necessarily a ThisExpression. */ - /* @internal */ tryGetThisTypeAt(node: Node, includeGlobalThis?: boolean, container?: Node): Type | undefined; - /* @internal */ getTypeArgumentConstraint(node: TypeNode): Type | undefined; + tryGetThisTypeAt(node: Node, includeGlobalThis?: boolean, container?: Node): Type | undefined; + /** @internal */ getTypeArgumentConstraint(node: TypeNode): Type | undefined; /** * Does *not* get *all* suggestion diagnostics, just the ones that were convenient to report in the checker. * Others are added in computeSuggestionDiagnostics. + * + * @internal */ - /* @internal */ getSuggestionDiagnostics(file: SourceFile, cancellationToken?: CancellationToken): readonly DiagnosticWithLocation[]; + getSuggestionDiagnostics(file: SourceFile, cancellationToken?: CancellationToken): readonly DiagnosticWithLocation[]; /** * Depending on the operation performed, it may be appropriate to throw away the checker @@ -4865,29 +4934,29 @@ export interface TypeChecker { */ runWithCancellationToken(token: CancellationToken, cb: (checker: TypeChecker) => T): T; - /* @internal */ getLocalTypeParametersOfClassOrInterfaceOrTypeAlias(symbol: Symbol): readonly TypeParameter[] | undefined; - /* @internal */ isDeclarationVisible(node: Declaration | AnyImportSyntax): boolean; - /* @internal */ isPropertyAccessible(node: Node, isSuper: boolean, isWrite: boolean, containingType: Type, property: Symbol): boolean; - /* @internal */ getTypeOnlyAliasDeclaration(symbol: Symbol): TypeOnlyAliasDeclaration | undefined; - /* @internal */ getMemberOverrideModifierStatus(node: ClassLikeDeclaration, member: ClassElement): MemberOverrideStatus; - /* @internal */ isTypeParameterPossiblyReferenced(tp: TypeParameter, node: Node): boolean; + /** @internal */ getLocalTypeParametersOfClassOrInterfaceOrTypeAlias(symbol: Symbol): readonly TypeParameter[] | undefined; + /** @internal */ isDeclarationVisible(node: Declaration | AnyImportSyntax): boolean; + /** @internal */ isPropertyAccessible(node: Node, isSuper: boolean, isWrite: boolean, containingType: Type, property: Symbol): boolean; + /** @internal */ getTypeOnlyAliasDeclaration(symbol: Symbol): TypeOnlyAliasDeclaration | undefined; + /** @internal */ getMemberOverrideModifierStatus(node: ClassLikeDeclaration, member: ClassElement): MemberOverrideStatus; + /** @internal */ isTypeParameterPossiblyReferenced(tp: TypeParameter, node: Node): boolean; } -/* @internal */ +/** @internal */ export const enum MemberOverrideStatus { Ok, NeedsOverride, HasInvalidOverride } -/* @internal */ +/** @internal */ export const enum UnionReduction { None = 0, Literal, Subtype, } -/* @internal */ +/** @internal */ export const enum ContextFlags { None = 0, Signature = 1 << 0, // Obtaining contextual signature @@ -4929,11 +4998,11 @@ export const enum NodeBuilderFlags { AllowEmptyTuple = 1 << 19, AllowUniqueESSymbolType = 1 << 20, AllowEmptyIndexInfoType = 1 << 21, - /* @internal */ WriteComputedProps = 1 << 30, // { [E.A]: 1 } + /** @internal */ WriteComputedProps = 1 << 30, // { [E.A]: 1 } // Errors (cont.) AllowNodeModulesRelativePaths = 1 << 26, - /* @internal */ DoNotIncludeSymbolChain = 1 << 27, // Skip looking up and printing an accessible symbol chain + /** @internal */ DoNotIncludeSymbolChain = 1 << 27, // Skip looking up and printing an accessible symbol chain IgnoreErrors = AllowThisInObjectLiteral | AllowQualifiedNameInPlaceOfIdentifier | AllowAnonymousIdentifier | AllowEmptyUnionOrIntersection | AllowEmptyTuple | AllowEmptyIndexInfoType | AllowNodeModulesRelativePaths, @@ -5008,13 +5077,13 @@ export const enum SymbolFormatFlags { UseAliasDefinedOutsideCurrentScope = 1 << 3, // { [E.A]: 1 } - /* @internal */ WriteComputedProps = 1 << 4, + /** @internal */ WriteComputedProps = 1 << 4, // Skip building an accessible symbol chain - /* @internal */ DoNotIncludeSymbolChain = 1 << 5, + /** @internal */ DoNotIncludeSymbolChain = 1 << 5, } -/* @internal */ +/** @internal */ export interface SymbolWalker { /** Note: Return values are not ordered. */ walkType(root: Type): { visitedTypes: readonly Type[], visitedSymbols: readonly Symbol[] }; @@ -5023,7 +5092,7 @@ export interface SymbolWalker { } // This was previously deprecated in our public API, but is still used internally -/* @internal */ +/** @internal */ interface SymbolWriter extends SymbolTracker { writeKeyword(text: string): void; writeOperator(text: string): void; @@ -5039,14 +5108,14 @@ interface SymbolWriter extends SymbolTracker { clear(): void; } -/* @internal */ +/** @internal */ export const enum SymbolAccessibility { Accessible, NotAccessible, CannotBeNamed } -/* @internal */ +/** @internal */ export const enum SyntheticSymbolKind { UnionOrIntersection, Spread @@ -5094,52 +5163,52 @@ export interface AssertsIdentifierTypePredicate extends TypePredicateBase { export type TypePredicate = ThisTypePredicate | IdentifierTypePredicate | AssertsThisTypePredicate | AssertsIdentifierTypePredicate; -/* @internal */ +/** @internal */ export type AnyImportSyntax = ImportDeclaration | ImportEqualsDeclaration; -/* @internal */ +/** @internal */ export type AnyImportOrRequire = AnyImportSyntax | VariableDeclarationInitializedTo; -/* @internal */ +/** @internal */ export type AnyImportOrBareOrAccessedRequire = AnyImportSyntax | VariableDeclarationInitializedTo; -/* @internal */ +/** @internal */ export type AnyImportOrRequireStatement = AnyImportSyntax | RequireVariableStatement; -/* @internal */ +/** @internal */ export type AnyImportOrReExport = AnyImportSyntax | ExportDeclaration; -/* @internal */ +/** @internal */ export interface ValidImportTypeNode extends ImportTypeNode { argument: LiteralTypeNode & { literal: StringLiteral }; } -/* @internal */ +/** @internal */ export type AnyValidImportOrReExport = | (ImportDeclaration | ExportDeclaration) & { moduleSpecifier: StringLiteral } | ImportEqualsDeclaration & { moduleReference: ExternalModuleReference & { expression: StringLiteral } } | RequireOrImportCall | ValidImportTypeNode; -/* @internal */ +/** @internal */ export type RequireOrImportCall = CallExpression & { expression: Identifier, arguments: [StringLiteralLike] }; -/* @internal */ +/** @internal */ export interface VariableDeclarationInitializedTo extends VariableDeclaration { readonly initializer: T; } -/* @internal */ +/** @internal */ export interface RequireVariableStatement extends VariableStatement { readonly declarationList: RequireVariableDeclarationList; } -/* @internal */ +/** @internal */ export interface RequireVariableDeclarationList extends VariableDeclarationList { readonly declarations: NodeArray>; } -/* @internal */ +/** @internal */ export type LateVisibilityPaintedStatement = | AnyImportSyntax | VariableStatement @@ -5150,7 +5219,7 @@ export type LateVisibilityPaintedStatement = | InterfaceDeclaration | EnumDeclaration; -/* @internal */ +/** @internal */ export interface SymbolVisibilityResult { accessibility: SymbolAccessibility; aliasesToMakeVisible?: LateVisibilityPaintedStatement[]; // aliases that need to have this symbol visible @@ -5158,12 +5227,12 @@ export interface SymbolVisibilityResult { errorNode?: Node; // optional node that results in error } -/* @internal */ +/** @internal */ export interface SymbolAccessibilityResult extends SymbolVisibilityResult { errorModuleName?: string; // If the symbol is not visible from module, module's name } -/* @internal */ +/** @internal */ export interface AllAccessorDeclarations { firstAccessor: AccessorDeclaration; secondAccessor: AccessorDeclaration | undefined; @@ -5171,7 +5240,7 @@ export interface AllAccessorDeclarations { setAccessor: SetAccessorDeclaration | undefined; } -/* @internal */ +/** @internal */ export interface AllDecorators { decorators: readonly Decorator[] | undefined; parameters?: readonly (readonly Decorator[] | undefined)[]; @@ -5179,8 +5248,11 @@ export interface AllDecorators { setDecorators?: readonly Decorator[] | undefined; } -/** Indicates how to serialize the name for a TypeReferenceNode when emitting decorator metadata */ -/* @internal */ +/** + * Indicates how to serialize the name for a TypeReferenceNode when emitting decorator metadata + * + * @internal + */ export enum TypeReferenceSerializationKind { // The TypeReferenceNode could not be resolved. // The type name should be emitted using a safe fallback. @@ -5223,7 +5295,7 @@ export enum TypeReferenceSerializationKind { ObjectType, } -/* @internal */ +/** @internal */ export interface EmitResolver { hasGlobalName(name: string): boolean; getReferencedExportContainer(node: Identifier, prefixLocals?: boolean): SourceFile | ModuleDeclaration | EnumDeclaration | undefined; @@ -5298,7 +5370,7 @@ export const enum SymbolFlags { Transient = 1 << 25, // Transient symbol (created during type check) Assignment = 1 << 26, // Assignment treated as declaration (eg `this.prop = 1`) ModuleExports = 1 << 27, // Symbol for CommonJS `module` of `module.exports` - /* @internal */ + /** @internal */ All = FunctionScopedVariable | BlockScopedVariable | Property | EnumMember | Function | Class | Interface | ConstEnum | RegularEnum | ValueModule | NamespaceModule | TypeLiteral | ObjectLiteral | Method | Constructor | GetAccessor | SetAccessor | Signature | TypeParameter | TypeAlias | ExportValue | Alias | Prototype | ExportStar | Optional | Transient, @@ -5346,22 +5418,22 @@ export const enum SymbolFlags { ClassMember = Method | Accessor | Property, - /* @internal */ + /** @internal */ ExportSupportsDefaultModifier = Class | Function | Interface, - /* @internal */ + /** @internal */ ExportDoesNotSupportDefaultModifier = ~ExportSupportsDefaultModifier, - /* @internal */ + /** @internal */ // The set of things we consider semantically classifiable. Used to speed up the LS during // classification. Classifiable = Class | Enum | TypeAlias | Interface | TypeParameter | Module | Alias, - /* @internal */ + /** @internal */ LateBindingContainer = Class | Interface | TypeLiteral | ObjectLiteral | Function, } -/* @internal */ +/** @internal */ export type SymbolId = number; export interface Symbol { @@ -5372,18 +5444,18 @@ export interface Symbol { members?: SymbolTable; // Class, interface or object literal instance members exports?: SymbolTable; // Module exports globalExports?: SymbolTable; // Conditional global UMD exports - /* @internal */ id?: SymbolId; // Unique id (used to look up SymbolLinks) - /* @internal */ mergeId?: number; // Merge id (used to look up merged symbol) - /* @internal */ parent?: Symbol; // Parent symbol - /* @internal */ exportSymbol?: Symbol; // Exported symbol associated with this symbol - /* @internal */ constEnumOnlyModule?: boolean; // True if module contains only const enums or other modules with only const enums - /* @internal */ isReferenced?: SymbolFlags; // True if the symbol is referenced elsewhere. Keeps track of the meaning of a reference in case a symbol is both a type parameter and parameter. - /* @internal */ isReplaceableByMethod?: boolean; // Can this Javascript class property be replaced by a method symbol? - /* @internal */ isAssigned?: boolean; // True if the symbol is a parameter with assignments - /* @internal */ assignmentDeclarationMembers?: ESMap; // detected late-bound assignment declarations associated with the symbol -} - -/* @internal */ + /** @internal */ id?: SymbolId; // Unique id (used to look up SymbolLinks) + /** @internal */ mergeId?: number; // Merge id (used to look up merged symbol) + /** @internal */ parent?: Symbol; // Parent symbol + /** @internal */ exportSymbol?: Symbol; // Exported symbol associated with this symbol + /** @internal */ constEnumOnlyModule?: boolean; // True if module contains only const enums or other modules with only const enums + /** @internal */ isReferenced?: SymbolFlags; // True if the symbol is referenced elsewhere. Keeps track of the meaning of a reference in case a symbol is both a type parameter and parameter. + /** @internal */ isReplaceableByMethod?: boolean; // Can this Javascript class property be replaced by a method symbol? + /** @internal */ isAssigned?: boolean; // True if the symbol is a parameter with assignments + /** @internal */ assignmentDeclarationMembers?: ESMap; // detected late-bound assignment declarations associated with the symbol +} + +/** @internal */ export interface SymbolLinks { immediateTarget?: Symbol; // Immediate target of an alias. May be another alias. Do not access directly, use `checker.getImmediateAliasedSymbol` instead. aliasTarget?: Symbol, // Resolved (non-alias) target of an alias @@ -5432,13 +5504,13 @@ export interface SymbolLinks { filteredIndexSymbolCache?: ESMap //Symbol with applicable declarations } -/* @internal */ +/** @internal */ export const enum EnumKind { Numeric, // Numeric enum (each member has a TypeFlags.Enum type) Literal // Literal enum (each member has a TypeFlags.EnumLiteral type) } -/* @internal */ +/** @internal */ export const enum CheckFlags { Instantiated = 1 << 0, // Instantiated symbol SyntheticProperty = 1 << 1, // Property in union or intersection type @@ -5466,18 +5538,18 @@ export const enum CheckFlags { Partial = ReadPartial | WritePartial } -/* @internal */ +/** @internal */ export interface TransientSymbol extends Symbol, SymbolLinks { checkFlags: CheckFlags; } -/* @internal */ +/** @internal */ export interface MappedSymbol extends TransientSymbol { mappedType: MappedType; keyType: Type; } -/* @internal */ +/** @internal */ export interface ReverseMappedSymbol extends TransientSymbol { propertyType: Type; mappedType: MappedType; @@ -5525,14 +5597,17 @@ export interface UnderscoreEscapedMap extends ESMap<__String, T>, ReadonlyUnd /** SymbolTable based on ES6 Map interface. */ export type SymbolTable = UnderscoreEscapedMap; -/** Used to track a `declare module "foo*"`-like declaration. */ -/* @internal */ +/** + * Used to track a `declare module "foo*"`-like declaration. + * + * @internal + */ export interface PatternAmbientModule { pattern: Pattern; symbol: Symbol; } -/* @internal */ +/** @internal */ export const enum NodeCheckFlags { TypeChecked = 0x00000001, // Node has been type checked LexicalThis = 0x00000002, // Lexical 'this' reference @@ -5561,7 +5636,7 @@ export const enum NodeCheckFlags { InCheckIdentifier = 0x10000000, } -/* @internal */ +/** @internal */ export interface NodeLinks { flags: NodeCheckFlags; // Set of flags specific to Node resolvedType?: Type; // Cached type of type node @@ -5622,21 +5697,21 @@ export const enum TypeFlags { TemplateLiteral = 1 << 27, // Template literal type StringMapping = 1 << 28, // Uppercase/Lowercase type - /* @internal */ + /** @internal */ AnyOrUnknown = Any | Unknown, - /* @internal */ + /** @internal */ Nullable = Undefined | Null, Literal = StringLiteral | NumberLiteral | BigIntLiteral | BooleanLiteral, Unit = Literal | UniqueESSymbol | Nullable, StringOrNumberLiteral = StringLiteral | NumberLiteral, - /* @internal */ + /** @internal */ StringOrNumberLiteralOrUnique = StringLiteral | NumberLiteral | UniqueESSymbol, - /* @internal */ + /** @internal */ DefinitelyFalsy = StringLiteral | NumberLiteral | BigIntLiteral | BooleanLiteral | Void | Undefined | Null, PossiblyFalsy = DefinitelyFalsy | String | Number | BigInt | Boolean, - /* @internal */ + /** @internal */ Intrinsic = Any | Unknown | String | Number | BigInt | Boolean | BooleanLiteral | ESSymbol | Void | Undefined | Null | Never | NonPrimitive, - /* @internal */ + /** @internal */ Primitive = String | Number | BigInt | Boolean | Enum | EnumLiteral | ESSymbol | Void | Undefined | Null | Literal | UniqueESSymbol, StringLike = String | StringLiteral | TemplateLiteral | StringMapping, NumberLike = Number | NumberLiteral | Enum, @@ -5645,9 +5720,9 @@ export const enum TypeFlags { EnumLike = Enum | EnumLiteral, ESSymbolLike = ESSymbol | UniqueESSymbol, VoidLike = Void | Undefined, - /* @internal */ + /** @internal */ DefinitelyNonNullable = StringLike | NumberLike | BigIntLike | BooleanLike | EnumLike | ESSymbolLike | Object | NonPrimitive, - /* @internal */ + /** @internal */ DisjointDomains = NonPrimitive | StringLike | NumberLike | BigIntLike | BooleanLike | ESSymbolLike | VoidLike | Null, UnionOrIntersection = Union | Intersection, StructuredType = Object | Union | Intersection, @@ -5656,78 +5731,78 @@ export const enum TypeFlags { InstantiablePrimitive = Index | TemplateLiteral | StringMapping, Instantiable = InstantiableNonPrimitive | InstantiablePrimitive, StructuredOrInstantiable = StructuredType | Instantiable, - /* @internal */ + /** @internal */ ObjectFlagsType = Any | Nullable | Never | Object | Union | Intersection, - /* @internal */ + /** @internal */ Simplifiable = IndexedAccess | Conditional, - /* @internal */ + /** @internal */ Singleton = Any | Unknown | String | Number | Boolean | BigInt | ESSymbol | Void | Undefined | Null | Never | NonPrimitive, // 'Narrowable' types are types where narrowing actually narrows. // This *should* be every type other than null, undefined, void, and never Narrowable = Any | Unknown | StructuredOrInstantiable | StringLike | NumberLike | BigIntLike | BooleanLike | ESSymbol | UniqueESSymbol | NonPrimitive, // The following flags are aggregated during union and intersection type construction - /* @internal */ + /** @internal */ IncludesMask = Any | Unknown | Primitive | Never | Object | Union | Intersection | NonPrimitive | TemplateLiteral, // The following flags are used for different purposes during union and intersection type construction - /* @internal */ + /** @internal */ IncludesMissingType = TypeParameter, - /* @internal */ + /** @internal */ IncludesNonWideningType = Index, - /* @internal */ + /** @internal */ IncludesWildcard = IndexedAccess, - /* @internal */ + /** @internal */ IncludesEmptyObject = Conditional, - /* @internal */ + /** @internal */ IncludesInstantiable = Substitution, - /* @internal */ + /** @internal */ NotPrimitiveUnion = Any | Unknown | Enum | Void | Never | Object | Intersection | IncludesInstantiable, } export type DestructuringPattern = BindingPattern | ObjectLiteralExpression | ArrayLiteralExpression; -/* @internal */ +/** @internal */ export type TypeId = number; // Properties common to all types export interface Type { flags: TypeFlags; // Flags - /* @internal */ id: TypeId; // Unique ID - /* @internal */ checker: TypeChecker; + /** @internal */ id: TypeId; // Unique ID + /** @internal */ checker: TypeChecker; symbol: Symbol; // Symbol associated with type (if any) pattern?: DestructuringPattern; // Destructuring pattern represented by type (if any) aliasSymbol?: Symbol; // Alias associated with type aliasTypeArguments?: readonly Type[]; // Alias type arguments (if any) - /* @internal */ + /** @internal */ permissiveInstantiation?: Type; // Instantiation with type parameters mapped to wildcard type - /* @internal */ + /** @internal */ restrictiveInstantiation?: Type; // Instantiation with type parameters mapped to unconstrained form - /* @internal */ + /** @internal */ uniqueLiteralFilledInstantiation?: Type; // Instantiation with type parameters mapped to never type - /* @internal */ + /** @internal */ immediateBaseConstraint?: Type; // Immediate base constraint cache - /* @internal */ + /** @internal */ widened?: Type; // Cached widened form of the type } -/* @internal */ +/** @internal */ // Intrinsic types (TypeFlags.Intrinsic) export interface IntrinsicType extends Type { intrinsicName: string; // Name of intrinsic type objectFlags: ObjectFlags; } -/* @internal */ +/** @internal */ export interface NullableType extends IntrinsicType { objectFlags: ObjectFlags; } -/* @internal */ +/** @internal */ export interface FreshableIntrinsicType extends IntrinsicType { freshType: IntrinsicType; // Fresh version of type regularType: IntrinsicType; // Regular version of type } -/* @internal */ +/** @internal */ export type FreshableType = LiteralType | FreshableIntrinsicType; // String literal types (TypeFlags.StringLiteral) @@ -5780,78 +5855,78 @@ export const enum ObjectFlags { JSLiteral = 1 << 12, // Object type declared in JS - disables errors on read/write of nonexisting members FreshLiteral = 1 << 13, // Fresh object literal ArrayLiteral = 1 << 14, // Originates in an array literal - /* @internal */ + /** @internal */ PrimitiveUnion = 1 << 15, // Union of only primitive types - /* @internal */ + /** @internal */ ContainsWideningType = 1 << 16, // Type is or contains undefined or null widening type - /* @internal */ + /** @internal */ ContainsObjectOrArrayLiteral = 1 << 17, // Type is or contains object literal type - /* @internal */ + /** @internal */ NonInferrableType = 1 << 18, // Type is or contains anyFunctionType or silentNeverType - /* @internal */ + /** @internal */ CouldContainTypeVariablesComputed = 1 << 19, // CouldContainTypeVariables flag has been computed - /* @internal */ + /** @internal */ CouldContainTypeVariables = 1 << 20, // Type could contain a type variable ClassOrInterface = Class | Interface, - /* @internal */ + /** @internal */ RequiresWidening = ContainsWideningType | ContainsObjectOrArrayLiteral, - /* @internal */ + /** @internal */ PropagatingFlags = ContainsWideningType | ContainsObjectOrArrayLiteral | NonInferrableType, // Object flags that uniquely identify the kind of ObjectType - /* @internal */ + /** @internal */ ObjectTypeKindMask = ClassOrInterface | Reference | Tuple | Anonymous | Mapped | ReverseMapped | EvolvingArray, // Flags that require TypeFlags.Object ContainsSpread = 1 << 21, // Object literal contains spread operation ObjectRestType = 1 << 22, // Originates in object rest declaration InstantiationExpressionType = 1 << 23, // Originates in instantiation expression - /* @internal */ + /** @internal */ IsClassInstanceClone = 1 << 24, // Type is a clone of a class instance type // Flags that require TypeFlags.Object and ObjectFlags.Reference - /* @internal */ + /** @internal */ IdenticalBaseTypeCalculated = 1 << 25, // has had `getSingleBaseForNonAugmentingSubtype` invoked on it already - /* @internal */ + /** @internal */ IdenticalBaseTypeExists = 1 << 26, // has a defined cachedEquivalentBaseType member // Flags that require TypeFlags.UnionOrIntersection or TypeFlags.Substitution - /* @internal */ + /** @internal */ IsGenericTypeComputed = 1 << 21, // IsGenericObjectType flag has been computed - /* @internal */ + /** @internal */ IsGenericObjectType = 1 << 22, // Union or intersection contains generic object type - /* @internal */ + /** @internal */ IsGenericIndexType = 1 << 23, // Union or intersection contains generic index type - /* @internal */ + /** @internal */ IsGenericType = IsGenericObjectType | IsGenericIndexType, // Flags that require TypeFlags.Union - /* @internal */ + /** @internal */ ContainsIntersections = 1 << 24, // Union contains intersections - /* @internal */ + /** @internal */ IsUnknownLikeUnionComputed = 1 << 25, // IsUnknownLikeUnion flag has been computed - /* @internal */ + /** @internal */ IsUnknownLikeUnion = 1 << 26, // Union of null, undefined, and empty object type - /* @internal */ + /** @internal */ // Flags that require TypeFlags.Intersection - /* @internal */ + /** @internal */ IsNeverIntersectionComputed = 1 << 24, // IsNeverLike flag has been computed - /* @internal */ + /** @internal */ IsNeverIntersection = 1 << 25, // Intersection reduces to never } -/* @internal */ +/** @internal */ export type ObjectFlagsType = NullableType | ObjectType | UnionType | IntersectionType; // Object types (TypeFlags.ObjectType) export interface ObjectType extends Type { objectFlags: ObjectFlags; - /* @internal */ members?: SymbolTable; // Properties by name - /* @internal */ properties?: Symbol[]; // Properties - /* @internal */ callSignatures?: readonly Signature[]; // Call signatures of type - /* @internal */ constructSignatures?: readonly Signature[]; // Construct signatures of type - /* @internal */ indexInfos?: readonly IndexInfo[]; // Index signatures - /* @internal */ objectTypeWithoutAbstractConstructSignatures?: ObjectType; + /** @internal */ members?: SymbolTable; // Properties by name + /** @internal */ properties?: Symbol[]; // Properties + /** @internal */ callSignatures?: readonly Signature[]; // Call signatures of type + /** @internal */ constructSignatures?: readonly Signature[]; // Construct signatures of type + /** @internal */ indexInfos?: readonly IndexInfo[]; // Index signatures + /** @internal */ objectTypeWithoutAbstractConstructSignatures?: ObjectType; } /** Class and interface types (ObjectFlags.Class and ObjectFlags.Interface). */ @@ -5860,11 +5935,11 @@ export interface InterfaceType extends ObjectType { outerTypeParameters: TypeParameter[] | undefined; // Outer type parameters (undefined if none) localTypeParameters: TypeParameter[] | undefined; // Local type parameters (undefined if none) thisType: TypeParameter | undefined; // The "this" type (undefined if none) - /* @internal */ + /** @internal */ resolvedBaseConstructorType?: Type; // Resolved base constructor type of class - /* @internal */ + /** @internal */ resolvedBaseTypes: BaseType[]; // Resolved base types - /* @internal */ + /** @internal */ baseTypesResolved?: boolean; } @@ -5891,26 +5966,26 @@ export interface InterfaceTypeWithDeclaredMembers extends InterfaceType { export interface TypeReference extends ObjectType { target: GenericType; // Type reference target node?: TypeReferenceNode | ArrayTypeNode | TupleTypeNode; - /* @internal */ + /** @internal */ mapper?: TypeMapper; - /* @internal */ + /** @internal */ resolvedTypeArguments?: readonly Type[]; // Resolved type reference type arguments - /* @internal */ + /** @internal */ literalType?: TypeReference; // Clone of type with ObjectFlags.ArrayLiteral set - /* @internal */ + /** @internal */ cachedEquivalentBaseType?: Type; // Only set on references to class or interfaces with a single base type and no augmentations } export interface DeferredTypeReference extends TypeReference { - /* @internal */ + /** @internal */ node: TypeReferenceNode | ArrayTypeNode | TupleTypeNode; - /* @internal */ + /** @internal */ mapper?: TypeMapper; - /* @internal */ + /** @internal */ instantiations?: ESMap; // Instantiations of generic type alias (undefined if non-generic) } -/* @internal */ +/** @internal */ export const enum VarianceFlags { Invariant = 0, // Neither covariant nor contravariant Covariant = 1 << 0, // Covariant @@ -5925,9 +6000,9 @@ export const enum VarianceFlags { // Generic class and interface types export interface GenericType extends InterfaceType, TypeReference { - /* @internal */ + /** @internal */ instantiations: ESMap; // Generic instantiation cache - /* @internal */ + /** @internal */ variances?: VarianceFlags[]; // Variance of each type parameter } @@ -5961,43 +6036,43 @@ export interface TupleTypeReference extends TypeReference { export interface UnionOrIntersectionType extends Type { types: Type[]; // Constituent types - /* @internal */ + /** @internal */ objectFlags: ObjectFlags; - /* @internal */ + /** @internal */ propertyCache?: SymbolTable; // Cache of resolved properties - /* @internal */ + /** @internal */ propertyCacheWithoutObjectFunctionPropertyAugment?: SymbolTable; // Cache of resolved properties that does not augment function or object type properties - /* @internal */ + /** @internal */ resolvedProperties: Symbol[]; - /* @internal */ + /** @internal */ resolvedIndexType: IndexType; - /* @internal */ + /** @internal */ resolvedStringIndexType: IndexType; - /* @internal */ + /** @internal */ resolvedBaseConstraint: Type; } export interface UnionType extends UnionOrIntersectionType { - /* @internal */ + /** @internal */ resolvedReducedType?: Type; - /* @internal */ + /** @internal */ regularType?: UnionType; - /* @internal */ + /** @internal */ origin?: Type; // Denormalized union, intersection, or index type in which union originates - /* @internal */ + /** @internal */ keyPropertyName?: __String; // Property with unique unit type that exists in every object/intersection in union type - /* @internal */ + /** @internal */ constituentMap?: ESMap; // Constituents keyed by unit type discriminants } export interface IntersectionType extends UnionOrIntersectionType { - /* @internal */ + /** @internal */ resolvedApparentType: Type; } export type StructuredType = ObjectType | UnionType | IntersectionType; -/* @internal */ +/** @internal */ // An instantiated anonymous type has a target and a mapper export interface AnonymousType extends ObjectType { target?: AnonymousType; // Instantiation target @@ -6005,12 +6080,12 @@ export interface AnonymousType extends ObjectType { instantiations?: ESMap; // Instantiations of generic type alias (undefined if non-generic) } -/* @internal */ +/** @internal */ export interface InstantiationExpressionType extends AnonymousType { node: ExpressionWithTypeArguments | TypeQueryNode; } -/* @internal */ +/** @internal */ export interface MappedType extends AnonymousType { declaration: MappedTypeNode; typeParameter?: TypeParameter; @@ -6027,14 +6102,14 @@ export interface EvolvingArrayType extends ObjectType { finalArrayType?: Type; // Final array type of evolving array type } -/* @internal */ +/** @internal */ export interface ReverseMappedType extends ObjectType { source: Type; mappedType: MappedType; constraintType: IndexType; } -/* @internal */ +/** @internal */ // Resolved object, union, or intersection type export interface ResolvedType extends ObjectType, UnionOrIntersectionType { members: SymbolTable; // Properties by name @@ -6044,7 +6119,7 @@ export interface ResolvedType extends ObjectType, UnionOrIntersectionType { indexInfos: readonly IndexInfo[]; // Index signatures } -/* @internal */ +/** @internal */ // Object literals are initially marked fresh. Freshness disappears following an assignment, // before a type assertion, or when an object literal's type is widened. The regular // version of a fresh type is identical except for the TypeFlags.FreshObjectLiteral flag. @@ -6052,7 +6127,7 @@ export interface FreshObjectLiteralType extends ResolvedType { regularType: ResolvedType; // Regular version of fresh type } -/* @internal */ +/** @internal */ export interface IterationTypes { readonly yieldType: Type; readonly returnType: Type; @@ -6060,7 +6135,7 @@ export interface IterationTypes { } // Just a place to cache element types of iterables and iterators -/* @internal */ +/** @internal */ export interface IterableOrIteratorType extends ObjectType, UnionType { iterationTypesOfGeneratorReturnType?: IterationTypes; iterationTypesOfAsyncGeneratorReturnType?: IterationTypes; @@ -6071,46 +6146,49 @@ export interface IterableOrIteratorType extends ObjectType, UnionType { iterationTypesOfIteratorResult?: IterationTypes; } -/* @internal */ +/** @internal */ export interface PromiseOrAwaitableType extends ObjectType, UnionType { promiseTypeOfPromiseConstructor?: Type; promisedTypeOfPromise?: Type; awaitedTypeOfType?: Type; } -/* @internal */ +/** @internal */ export interface SyntheticDefaultModuleType extends Type { syntheticType?: Type; defaultOnlyType?: Type; } export interface InstantiableType extends Type { - /* @internal */ + /** @internal */ resolvedBaseConstraint?: Type; - /* @internal */ + /** @internal */ resolvedIndexType?: IndexType; - /* @internal */ + /** @internal */ resolvedStringIndexType?: IndexType; } // Type parameters (TypeFlags.TypeParameter) export interface TypeParameter extends InstantiableType { - /** Retrieve using getConstraintFromTypeParameter */ - /* @internal */ + /** + * Retrieve using getConstraintFromTypeParameter + * + * @internal + */ constraint?: Type; // Constraint - /* @internal */ + /** @internal */ default?: Type; - /* @internal */ + /** @internal */ target?: TypeParameter; // Instantiation target - /* @internal */ + /** @internal */ mapper?: TypeMapper; // Instantiation mapper - /* @internal */ + /** @internal */ isThisType?: boolean; - /* @internal */ + /** @internal */ resolvedDefaultType?: Type; } -/* @internal */ +/** @internal */ export const enum AccessFlags { None = 0, IncludeUndefined = 1 << 0, @@ -6130,7 +6208,7 @@ export const enum AccessFlags { export interface IndexedAccessType extends InstantiableType { objectType: Type; indexType: Type; - /* @internal */ + /** @internal */ accessFlags: AccessFlags; // Only includes AccessFlags.Persistent constraint?: Type; simplifiedForReading?: Type; @@ -6142,7 +6220,7 @@ export type TypeVariable = TypeParameter | IndexedAccessType; // keyof T types (TypeFlags.Index) export interface IndexType extends InstantiableType { type: InstantiableType | UnionOrIntersectionType; - /* @internal */ + /** @internal */ stringsOnly: boolean; } @@ -6165,13 +6243,13 @@ export interface ConditionalType extends InstantiableType { extendsType: Type; resolvedTrueType?: Type; resolvedFalseType?: Type; - /* @internal */ + /** @internal */ resolvedInferredTrueType?: Type; // The `trueType` instantiated with the `combinedMapper`, if present - /* @internal */ + /** @internal */ resolvedDefaultConstraint?: Type; - /* @internal */ + /** @internal */ mapper?: TypeMapper; - /* @internal */ + /** @internal */ combinedMapper?: TypeMapper; } @@ -6197,7 +6275,7 @@ export interface SubstitutionType extends InstantiableType { constraint: Type; // Constraint that target type is known to satisfy } -/* @internal */ +/** @internal */ export const enum JsxReferenceKind { Component, Function, @@ -6209,7 +6287,7 @@ export const enum SignatureKind { Construct, } -/* @internal */ +/** @internal */ export const enum SignatureFlags { None = 0, @@ -6232,44 +6310,44 @@ export const enum SignatureFlags { } export interface Signature { - /* @internal */ flags: SignatureFlags; - /* @internal */ checker?: TypeChecker; + /** @internal */ flags: SignatureFlags; + /** @internal */ checker?: TypeChecker; declaration?: SignatureDeclaration | JSDocSignature; // Originating declaration typeParameters?: readonly TypeParameter[]; // Type parameters (undefined if non-generic) parameters: readonly Symbol[]; // Parameters - /* @internal */ + /** @internal */ thisParameter?: Symbol; // symbol of this-type parameter - /* @internal */ + /** @internal */ // See comment in `instantiateSignature` for why these are set lazily. resolvedReturnType?: Type; // Lazily set by `getReturnTypeOfSignature`. - /* @internal */ + /** @internal */ // Lazily set by `getTypePredicateOfSignature`. // `undefined` indicates a type predicate that has not yet been computed. // Uses a special `noTypePredicate` sentinel value to indicate that there is no type predicate. This looks like a TypePredicate at runtime to avoid polymorphism. resolvedTypePredicate?: TypePredicate; - /* @internal */ + /** @internal */ minArgumentCount: number; // Number of non-optional parameters - /* @internal */ + /** @internal */ resolvedMinArgumentCount?: number; // Number of non-optional parameters (excluding trailing `void`) - /* @internal */ + /** @internal */ target?: Signature; // Instantiation target - /* @internal */ + /** @internal */ mapper?: TypeMapper; // Instantiation mapper - /* @internal */ + /** @internal */ compositeSignatures?: Signature[]; // Underlying signatures of a union/intersection signature - /* @internal */ + /** @internal */ compositeKind?: TypeFlags; // TypeFlags.Union if the underlying signatures are from union members, otherwise TypeFlags.Intersection - /* @internal */ + /** @internal */ erasedSignatureCache?: Signature; // Erased version of signature (deferred) - /* @internal */ + /** @internal */ canonicalSignatureCache?: Signature; // Canonical version of signature (deferred) - /* @internal */ + /** @internal */ baseSignatureCache?: Signature; // Base version of signature (deferred) - /* @internal */ + /** @internal */ optionalCallSignatureCache?: { inner?: Signature, outer?: Signature }; // Optional chained call version of signature (deferred) - /* @internal */ + /** @internal */ isolatedSignatureType?: ObjectType; // A manufactured type that just contains the signature for purposes of signature comparison - /* @internal */ + /** @internal */ instantiations?: ESMap; // Generic signature instantiation cache } @@ -6285,7 +6363,7 @@ export interface IndexInfo { declaration?: IndexSignatureDeclaration; } -/* @internal */ +/** @internal */ export const enum TypeMapKind { Simple, Array, @@ -6295,7 +6373,7 @@ export const enum TypeMapKind { Merged, } -/* @internal */ +/** @internal */ export type TypeMapper = | { kind: TypeMapKind.Simple, source: Type, target: Type } | { kind: TypeMapKind.Array, sources: readonly Type[], targets: readonly Type[] | undefined } @@ -6321,7 +6399,7 @@ export const enum InferencePriority { Circularity = -1, // Inference circularity (value less than all other priorities) } -/* @internal */ +/** @internal */ export interface InferenceInfo { typeParameter: TypeParameter; // Type parameter for which inferences are being made candidates: Type[] | undefined; // Candidates in covariant positions (or undefined) @@ -6333,7 +6411,7 @@ export interface InferenceInfo { impliedArity?: number; } -/* @internal */ +/** @internal */ export const enum InferenceFlags { None = 0, // No special inference behaviors NoDefault = 1 << 0, // Infer unknownType for no inferences (otherwise anyType or emptyObjectType) @@ -6348,8 +6426,9 @@ export const enum InferenceFlags { * Generally, Ternary.Maybe is used as the result of a relation that depends on itself, and * Ternary.Unknown is used as the result of a variance check that depends on itself. We make * a distinction because we don't want to cache circular variance check results. + * + * @internal */ -/* @internal */ export const enum Ternary { False = 0, Unknown = 1, @@ -6357,10 +6436,10 @@ export const enum Ternary { True = -1 } -/* @internal */ +/** @internal */ export type TypeComparer = (s: Type, t: Type, reportErrors?: boolean) => Ternary; -/* @internal */ +/** @internal */ export interface InferenceContext { inferences: InferenceInfo[]; // Inferences made for each type parameter signature?: Signature; // Generic signature for which inferences are made (if any) @@ -6373,13 +6452,13 @@ export interface InferenceContext { intraExpressionInferenceSites?: IntraExpressionInferenceSite[]; } -/* @internal */ +/** @internal */ export interface IntraExpressionInferenceSite { node: Expression | MethodDeclaration; type: Type; } -/* @internal */ +/** @internal */ export interface WideningContext { parent?: WideningContext; // Parent context propertyName?: __String; // Name of property in parent @@ -6387,7 +6466,7 @@ export interface WideningContext { resolvedProperties?: Symbol[]; // Properties occurring in sibling object literals } -/* @internal */ +/** @internal */ export const enum AssignmentDeclarationKind { None, /// exports.name = expr @@ -6430,7 +6509,7 @@ export interface DiagnosticMessage { message: string; reportsUnnecessary?: {}; reportsDeprecated?: {}; - /* @internal */ + /** @internal */ elidedInCompatabilityPyramid?: boolean; } @@ -6454,7 +6533,7 @@ export interface Diagnostic extends DiagnosticRelatedInformation { reportsDeprecated?: {} source?: string; relatedInformation?: DiagnosticRelatedInformation[]; - /* @internal */ skippedOn?: keyof CompilerOptions; + /** @internal */ skippedOn?: keyof CompilerOptions; } export interface DiagnosticRelatedInformation { @@ -6472,7 +6551,7 @@ export interface DiagnosticWithLocation extends Diagnostic { length: number; } -/* @internal*/ +/** @internal */ export interface DiagnosticWithDetachedLocation extends Diagnostic { file: undefined; fileName: string; @@ -6486,7 +6565,7 @@ export enum DiagnosticCategory { Suggestion, Message } -/* @internal */ +/** @internal */ export function diagnosticCategoryName(d: { category: DiagnosticCategory }, lowerCase = true): string { const name = DiagnosticCategory[d.category]; return lowerCase ? name.toLowerCase() : name; @@ -6560,29 +6639,36 @@ export enum PollingWatchKind { export type CompilerOptionsValue = string | number | boolean | (string | number)[] | string[] | MapLike | PluginImport[] | ProjectReference[] | null | undefined; export interface CompilerOptions { - /*@internal*/ all?: boolean; + /** @internal */ all?: boolean; allowJs?: boolean; - /*@internal*/ allowNonTsExtensions?: boolean; + /** @internal */ allowNonTsExtensions?: boolean; allowSyntheticDefaultImports?: boolean; allowUmdGlobalAccess?: boolean; allowUnreachableCode?: boolean; allowUnusedLabels?: boolean; alwaysStrict?: boolean; // Always combine with strict property baseUrl?: string; - /** An error if set - this should only go through the -b pipeline and not actually be observed */ - /*@internal*/ + /** + * An error if set - this should only go through the -b pipeline and not actually be observed + * + * @internal + */ build?: boolean; charset?: string; checkJs?: boolean; - /* @internal */ configFilePath?: string; - /** configFile is set as non enumerable property so as to avoid checking of json source files */ - /* @internal */ readonly configFile?: TsConfigSourceFile; + /** @internal */ configFilePath?: string; + /** + * configFile is set as non enumerable property so as to avoid checking of json source files + * + * @internal + */ + readonly configFile?: TsConfigSourceFile; declaration?: boolean; declarationMap?: boolean; emitDeclarationOnly?: boolean; declarationDir?: string; - /* @internal */ diagnostics?: boolean; - /* @internal */ extendedDiagnostics?: boolean; + /** @internal */ diagnostics?: boolean; + /** @internal */ extendedDiagnostics?: boolean; disableSizeLimit?: boolean; disableSourceOfProjectReferenceRedirect?: boolean; disableSolutionSearching?: boolean; @@ -6593,22 +6679,22 @@ export interface CompilerOptions { exactOptionalPropertyTypes?: boolean; experimentalDecorators?: boolean; forceConsistentCasingInFileNames?: boolean; - /*@internal*/generateCpuProfile?: string; - /*@internal*/generateTrace?: string; - /*@internal*/help?: boolean; + /** @internal */generateCpuProfile?: string; + /** @internal */generateTrace?: string; + /** @internal */help?: boolean; importHelpers?: boolean; importsNotUsedAsValues?: ImportsNotUsedAsValues; - /*@internal*/init?: boolean; + /** @internal */init?: boolean; inlineSourceMap?: boolean; inlineSources?: boolean; isolatedModules?: boolean; jsx?: JsxEmit; keyofStringsOnly?: boolean; lib?: string[]; - /*@internal*/listEmittedFiles?: boolean; - /*@internal*/listFiles?: boolean; - /*@internal*/explainFiles?: boolean; - /*@internal*/listFilesOnly?: boolean; + /** @internal */listEmittedFiles?: boolean; + /** @internal */listFiles?: boolean; + /** @internal */explainFiles?: boolean; + /** @internal */listFilesOnly?: boolean; locale?: string; mapRoot?: string; maxNodeModuleJsDepth?: number; @@ -6618,7 +6704,7 @@ export interface CompilerOptions { moduleDetection?: ModuleDetectionKind; newLine?: NewLineKind; noEmit?: boolean; - /*@internal*/noEmitForJsFiles?: boolean; + /** @internal */noEmitForJsFiles?: boolean; noEmitHelpers?: boolean; noEmitOnError?: boolean; noErrorTruncation?: boolean; @@ -6634,23 +6720,27 @@ export interface CompilerOptions { assumeChangesOnlyAffectDirectDependencies?: boolean; noLib?: boolean; noResolve?: boolean; - /*@internal*/ + /** @internal */ noDtsResolution?: boolean; noUncheckedIndexedAccess?: boolean; out?: string; outDir?: string; outFile?: string; paths?: MapLike; - /** The directory of the config file that specified 'paths'. Used to resolve relative paths when 'baseUrl' is absent. */ - /*@internal*/ pathsBasePath?: string; - /*@internal*/ plugins?: PluginImport[]; + /** + * The directory of the config file that specified 'paths'. Used to resolve relative paths when 'baseUrl' is absent. + * + * @internal + */ + pathsBasePath?: string; + /** @internal */ plugins?: PluginImport[]; preserveConstEnums?: boolean; noImplicitOverride?: boolean; preserveSymlinks?: boolean; preserveValueImports?: boolean; - /* @internal */ preserveWatchOutput?: boolean; + /** @internal */ preserveWatchOutput?: boolean; project?: string; - /* @internal */ pretty?: boolean; + /** @internal */ pretty?: boolean; reactNamespace?: string; jsxFactory?: string; jsxFragmentFactory?: string; @@ -6673,7 +6763,7 @@ export interface CompilerOptions { stripInternal?: boolean; suppressExcessPropertyErrors?: boolean; suppressImplicitAnyIndexErrors?: boolean; - /* @internal */ suppressOutputPathCheck?: boolean; + /** @internal */ suppressOutputPathCheck?: boolean; target?: ScriptTarget; traceResolution?: boolean; useUnknownInCatchVariables?: boolean; @@ -6681,10 +6771,10 @@ export interface CompilerOptions { types?: string[]; /** Paths used to compute primary types search locations */ typeRoots?: string[]; - /*@internal*/ version?: boolean; - /*@internal*/ watch?: boolean; + /** @internal */ version?: boolean; + /** @internal */ watch?: boolean; esModuleInterop?: boolean; - /* @internal */ showConfig?: boolean; + /** @internal */ showConfig?: boolean; useDefineForClassFields?: boolean; [option: string]: CompilerOptionsValue | TsConfigSourceFile | undefined; @@ -6817,7 +6907,7 @@ export const enum WatchDirectoryFlags { Recursive = 1 << 0, } -/* @internal */ +/** @internal */ export interface ConfigFileSpecs { filesSpecs: readonly string[] | undefined; /** @@ -6835,7 +6925,7 @@ export interface ConfigFileSpecs { isDefaultIncludeSpec: boolean; } -/* @internal */ +/** @internal */ export type RequireResult = | { module: T, modulePath?: string, error: undefined } | { module: undefined, modulePath?: undefined, error: { stack?: string, message?: string } }; @@ -6849,7 +6939,7 @@ export interface CreateProgramOptions { configFileParsingDiagnostics?: readonly Diagnostic[]; } -/* @internal */ +/** @internal */ export interface CommandLineOptionBase { name: string; type: "string" | "number" | "boolean" | "object" | "list" | ESMap; // a value of a primitive type, or an object literal mapping named values to actual values @@ -6875,37 +6965,37 @@ export interface CommandLineOptionBase { extraValidation?: (value: CompilerOptionsValue) => [DiagnosticMessage, ...string[]] | undefined; // Additional validation to be performed for the value to be valid } -/* @internal */ +/** @internal */ export interface CommandLineOptionOfStringType extends CommandLineOptionBase { type: "string"; defaultValueDescription?: string | undefined | DiagnosticMessage; } -/* @internal */ +/** @internal */ export interface CommandLineOptionOfNumberType extends CommandLineOptionBase { type: "number"; defaultValueDescription: number | undefined | DiagnosticMessage; } -/* @internal */ +/** @internal */ export interface CommandLineOptionOfBooleanType extends CommandLineOptionBase { type: "boolean"; defaultValueDescription: boolean | undefined | DiagnosticMessage; } -/* @internal */ +/** @internal */ export interface CommandLineOptionOfCustomType extends CommandLineOptionBase { type: ESMap; // an object literal mapping named values to actual values defaultValueDescription: number | string | undefined | DiagnosticMessage; } -/* @internal */ +/** @internal */ export interface AlternateModeDiagnostics { diagnostic: DiagnosticMessage; getOptionsNameMap: () => OptionsNameMap; } -/* @internal */ +/** @internal */ export interface DidYouMeanOptionsDiagnostics { alternateMode?: AlternateModeDiagnostics; optionDeclarations: CommandLineOption[]; @@ -6913,24 +7003,24 @@ export interface DidYouMeanOptionsDiagnostics { unknownDidYouMeanDiagnostic: DiagnosticMessage, } -/* @internal */ +/** @internal */ export interface TsConfigOnlyOption extends CommandLineOptionBase { type: "object"; elementOptions?: ESMap; extraKeyDiagnostics?: DidYouMeanOptionsDiagnostics; } -/* @internal */ +/** @internal */ export interface CommandLineOptionOfListType extends CommandLineOptionBase { type: "list"; element: CommandLineOptionOfCustomType | CommandLineOptionOfStringType | CommandLineOptionOfNumberType | CommandLineOptionOfBooleanType | TsConfigOnlyOption; listPreserveFalsyValues?: boolean; } -/* @internal */ +/** @internal */ export type CommandLineOption = CommandLineOptionOfCustomType | CommandLineOptionOfStringType | CommandLineOptionOfNumberType | CommandLineOptionOfBooleanType | TsConfigOnlyOption | CommandLineOptionOfListType; -/* @internal */ +/** @internal */ export const enum CharacterCodes { nullCharacter = 0, maxAsciiCharacter = 0x7F, @@ -7165,11 +7255,11 @@ export const enum Extension { export interface ResolvedModuleWithFailedLookupLocations { readonly resolvedModule: ResolvedModuleFull | undefined; - /* @internal */ + /** @internal */ readonly failedLookupLocations: string[]; - /* @internal */ + /** @internal */ readonly affectingLocations: string[]; - /* @internal */ + /** @internal */ readonly resolutionDiagnostics: Diagnostic[] } @@ -7192,13 +7282,13 @@ export interface ResolvedTypeReferenceDirective { export interface ResolvedTypeReferenceDirectiveWithFailedLookupLocations { readonly resolvedTypeReferenceDirective: ResolvedTypeReferenceDirective | undefined; readonly failedLookupLocations: string[]; - /*@internal*/ readonly affectingLocations: string[]; - /* @internal */ resolutionDiagnostics: Diagnostic[]; + /** @internal */ readonly affectingLocations: string[]; + /** @internal */ resolutionDiagnostics: Diagnostic[]; } -/* @internal */ +/** @internal */ export type HasInvalidatedResolutions = (sourceFile: Path) => boolean; -/* @internal */ +/** @internal */ export type HasChangedAutomaticTypeDirectiveNames = () => boolean; export interface ModuleResolutionInfo { @@ -7236,36 +7326,37 @@ export interface CompilerHost extends ModuleResolutionHost { */ resolveTypeReferenceDirectives?(typeReferenceDirectiveNames: string[] | readonly FileReference[], containingFile: string, redirectedReference: ResolvedProjectReference | undefined, options: CompilerOptions, containingFileMode?: SourceFile["impliedNodeFormat"] | undefined): (ResolvedTypeReferenceDirective | undefined)[]; getEnvironmentVariable?(name: string): string | undefined; - /* @internal */ onReleaseOldSourceFile?(oldSourceFile: SourceFile, oldOptions: CompilerOptions, hasSourceFileByPath: boolean): void; - /* @internal */ onReleaseParsedCommandLine?(configFileName: string, oldResolvedRef: ResolvedProjectReference | undefined, optionOptions: CompilerOptions): void; + /** @internal */ onReleaseOldSourceFile?(oldSourceFile: SourceFile, oldOptions: CompilerOptions, hasSourceFileByPath: boolean): void; + /** @internal */ onReleaseParsedCommandLine?(configFileName: string, oldResolvedRef: ResolvedProjectReference | undefined, optionOptions: CompilerOptions): void; /** If provided along with custom resolveModuleNames or resolveTypeReferenceDirectives, used to determine if unchanged file path needs to re-resolve modules/type reference directives */ hasInvalidatedResolutions?(filePath: Path): boolean; - /* @internal */ hasChangedAutomaticTypeDirectiveNames?: HasChangedAutomaticTypeDirectiveNames; + /** @internal */ hasChangedAutomaticTypeDirectiveNames?: HasChangedAutomaticTypeDirectiveNames; createHash?(data: string): string; getParsedCommandLine?(fileName: string): ParsedCommandLine | undefined; - /* @internal */ useSourceOfProjectReferenceRedirect?(): boolean; + /** @internal */ useSourceOfProjectReferenceRedirect?(): boolean; // TODO: later handle this in better way in builder host instead once the api for tsbuild finalizes and doesn't use compilerHost as base - /*@internal*/createDirectory?(directory: string): void; - /*@internal*/getSymlinkCache?(): SymlinkCache; + /** @internal */createDirectory?(directory: string): void; + /** @internal */getSymlinkCache?(): SymlinkCache; // For testing: - /*@internal*/ disableUseFileVersionAsSignature?: boolean; - /*@internal*/ storeFilesChangingSignatureDuringEmit?: boolean; - /*@internal*/ getBuildInfo?(fileName: string, configFilePath: string | undefined): BuildInfo | undefined; + /** @internal */ disableUseFileVersionAsSignature?: boolean; + /** @internal */ storeFilesChangingSignatureDuringEmit?: boolean; + /** @internal */ getBuildInfo?(fileName: string, configFilePath: string | undefined): BuildInfo | undefined; } -/** true if --out otherwise source file name */ -/*@internal*/ +/** true if --out otherwise source file name * + * @internal + */ export type SourceOfProjectReferenceRedirect = string | true; -/*@internal*/ +/** @internal */ export interface ResolvedProjectReferenceCallbacks { getSourceOfProjectReferenceRedirect(fileName: string): SourceOfProjectReferenceRedirect | undefined; forEachResolvedProjectReference(cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined): T | undefined; } -/* @internal */ +/** @internal */ export const enum TransformFlags { None = 0, @@ -7360,11 +7451,11 @@ export interface SourceMapRange extends TextRange { export interface SourceMapSource { fileName: string; text: string; - /* @internal */ lineMap: readonly number[]; + /** @internal */ lineMap: readonly number[]; skipTrivia?: (pos: number) => number; } -/* @internal */ +/** @internal */ export interface EmitNode { annotatedNodes?: Node[]; // Tracks Parse-tree nodes with EmitNodes for eventual cleanup. flags: EmitFlags; // Flags that customize emit @@ -7382,23 +7473,23 @@ export interface EmitNode { typeNode?: TypeNode; // VariableDeclaration type } -/* @internal */ +/** @internal */ export type SnippetElement = TabStop | Placeholder; -/* @internal */ +/** @internal */ export interface TabStop { kind: SnippetKind.TabStop; order: number; } -/* @internal */ +/** @internal */ export interface Placeholder { kind: SnippetKind.Placeholder; order: number; } // Reference: https://code.visualstudio.com/docs/editor/userdefinedsnippets#_snippet-syntax -/* @internal */ +/** @internal */ export const enum SnippetKind { TabStop, // `$1`, `$2` Placeholder, // `${1:foo}` @@ -7436,11 +7527,11 @@ export const enum EmitFlags { HasEndOfDeclarationMarker = 1 << 22, // Declaration has an associated NotEmittedStatement to mark the end of the declaration Iterator = 1 << 23, // The expression to a `yield*` should be treated as an Iterator when down-leveling, not an Iterable. NoAsciiEscaping = 1 << 24, // When synthesizing nodes that lack an original node or textSourceNode, we want to write the text on the node with ASCII escaping substitutions. - /*@internal*/ TypeScriptClassWrapper = 1 << 25, // The node is an IIFE class wrapper created by the ts transform. - /*@internal*/ NeverApplyImportHelper = 1 << 26, // Indicates the node should never be wrapped with an import star helper (because, for example, it imports tslib itself) - /*@internal*/ IgnoreSourceNewlines = 1 << 27, // Overrides `printerOptions.preserveSourceNewlines` to print this node (and all descendants) with default whitespace. - /*@internal*/ Immutable = 1 << 28, // Indicates a node is a singleton intended to be reused in multiple locations. Any attempt to make further changes to the node will result in an error. - /*@internal*/ IndirectCall = 1 << 29, // Emit CallExpression as an indirect call: `(0, f)()` + /** @internal */ TypeScriptClassWrapper = 1 << 25, // The node is an IIFE class wrapper created by the ts transform. + /** @internal */ NeverApplyImportHelper = 1 << 26, // Indicates the node should never be wrapped with an import star helper (because, for example, it imports tslib itself) + /** @internal */ IgnoreSourceNewlines = 1 << 27, // Overrides `printerOptions.preserveSourceNewlines` to print this node (and all descendants) with default whitespace. + /** @internal */ Immutable = 1 << 28, // Indicates a node is a singleton intended to be reused in multiple locations. Any attempt to make further changes to the node will result in an error. + /** @internal */ IndirectCall = 1 << 29, // Emit CallExpression as an indirect call: `(0, f)()` } export interface EmitHelperBase { @@ -7457,14 +7548,14 @@ export interface ScopedEmitHelper extends EmitHelperBase { export interface UnscopedEmitHelper extends EmitHelperBase { readonly scoped: false; // Indicates whether the helper MUST be emitted in the current scope. - /* @internal */ + /** @internal */ readonly importName?: string; // The name of the helper to use when importing via `--importHelpers`. readonly text: string; // ES3-compatible raw script text, or a function yielding such a string } export type EmitHelper = ScopedEmitHelper | UnscopedEmitHelper; -/* @internal */ +/** @internal */ export type UniqueNameHandler = (baseName: string, checkFn?: (name: string) => boolean, optimistic?: boolean) => string; export type EmitHelperUniqueNameCallback = (name: string) => string; @@ -7472,8 +7563,9 @@ export type EmitHelperUniqueNameCallback = (name: string) => string; /** * Used by the checker, this enum keeps track of external emit helpers that should be type * checked. + * + * @internal */ -/* @internal */ export const enum ExternalEmitHelpers { Extends = 1 << 0, // __extends (used by the ES2015 class transformation) Assign = 1 << 1, // __assign (used by Jsx and ESNext object spread transformations) @@ -7527,7 +7619,7 @@ export const enum EmitHint { JsxAttributeValue, // Emitting a JSX attribute value } -/* @internal */ +/** @internal */ export interface SourceFileMayBeEmittedHost { getCompilerOptions(): CompilerOptions; isSourceFileFromExternalLibrary(file: SourceFile): boolean; @@ -7535,7 +7627,7 @@ export interface SourceFileMayBeEmittedHost { isSourceOfProjectReferenceRedirect(fileName: string): boolean; } -/* @internal */ +/** @internal */ export interface EmitHost extends ScriptReferenceHost, ModuleSpecifierResolutionHost, SourceFileMayBeEmittedHost { getSourceFiles(): readonly SourceFile[]; useCaseSensitiveFileNames(): boolean; @@ -7558,7 +7650,7 @@ export interface EmitHost extends ScriptReferenceHost, ModuleSpecifierResolution createHash?(data: string): string; } -/* @internal */ +/** @internal */ export interface PropertyDescriptorAttributes { enumerable?: boolean | Expression; configurable?: boolean | Expression; @@ -7580,7 +7672,7 @@ export const enum OuterExpressionKinds { ExcludeJSDocTypeAssertion = 1 << 4, } -/* @internal */ +/** @internal */ export type OuterExpression = | ParenthesizedExpression | TypeAssertion @@ -7591,13 +7683,13 @@ export type OuterExpression = export type TypeOfTag = "undefined" | "number" | "bigint" | "boolean" | "string" | "symbol" | "object" | "function"; -/* @internal */ +/** @internal */ export interface CallBinding { target: LeftHandSideExpression; thisArg: Expression; } -/* @internal */ +/** @internal */ export interface ParenthesizerRules { getParenthesizeLeftSideOfBinaryForOperator(binaryOperator: SyntaxKind): (leftSide: Expression) => Expression; getParenthesizeRightSideOfBinaryForOperator(binaryOperator: SyntaxKind): (rightSide: Expression) => Expression; @@ -7632,7 +7724,7 @@ export interface ParenthesizerRules { parenthesizeTypeArguments(typeParameters: readonly TypeNode[] | undefined): NodeArray | undefined; } -/* @internal */ +/** @internal */ export interface NodeConverters { convertToFunctionBlock(node: ConciseBody, multiLine?: boolean): Block; convertToFunctionExpression(node: FunctionDeclaration): FunctionExpression; @@ -7644,7 +7736,7 @@ export interface NodeConverters { convertToAssignmentElementTarget(node: BindingOrAssignmentElementTarget): Expression; } -/* @internal */ +/** @internal */ export interface GeneratedNamePart { /** an additional prefix to insert before the text sourced from `node` */ prefix?: string; @@ -7654,10 +7746,10 @@ export interface GeneratedNamePart { } export interface NodeFactory { - /* @internal */ readonly parenthesizer: ParenthesizerRules; - /* @internal */ readonly converters: NodeConverters; - /* @internal */ readonly baseFactory: BaseNodeFactory; - /* @internal */ readonly flags: NodeFactoryFlags; + /** @internal */ readonly parenthesizer: ParenthesizerRules; + /** @internal */ readonly converters: NodeConverters; + /** @internal */ readonly baseFactory: BaseNodeFactory; + /** @internal */ readonly flags: NodeFactoryFlags; createNodeArray(elements?: readonly T[], hasTrailingComma?: boolean): NodeArray; // @@ -7667,7 +7759,7 @@ export interface NodeFactory { createNumericLiteral(value: string | number, numericLiteralFlags?: TokenFlags): NumericLiteral; createBigIntLiteral(value: string | PseudoBigInt): BigIntLiteral; createStringLiteral(text: string, isSingleQuote?: boolean): StringLiteral; - /* @internal*/ createStringLiteral(text: string, isSingleQuote?: boolean, hasExtendedUnicodeEscape?: boolean): StringLiteral; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ createStringLiteral(text: string, isSingleQuote?: boolean, hasExtendedUnicodeEscape?: boolean): StringLiteral; // eslint-disable-line @typescript-eslint/unified-signatures createStringLiteralFromNode(sourceNode: PropertyNameLiteral | PrivateIdentifier, isSingleQuote?: boolean): StringLiteral; createRegularExpressionLiteral(text: string): RegularExpressionLiteral; @@ -7676,8 +7768,8 @@ export interface NodeFactory { // createIdentifier(text: string): Identifier; - /* @internal */ createIdentifier(text: string, typeArguments?: readonly (TypeNode | TypeParameterDeclaration)[], originalKeywordKind?: SyntaxKind, hasExtendedUnicodeEscape?: boolean): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures - /* @internal */ updateIdentifier(node: Identifier, typeArguments: NodeArray | undefined): Identifier; + /** @internal */ createIdentifier(text: string, typeArguments?: readonly (TypeNode | TypeParameterDeclaration)[], originalKeywordKind?: SyntaxKind, hasExtendedUnicodeEscape?: boolean): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ updateIdentifier(node: Identifier, typeArguments: NodeArray | undefined): Identifier; /** * Create a unique temporary variable. @@ -7689,7 +7781,7 @@ export interface NodeFactory { * setting `EmitFlags.ReuseTempVariableScope` on the nested function itself. */ createTempVariable(recordTempVariable: ((node: Identifier) => void) | undefined, reservedInNestedScopes?: boolean): Identifier; - /*@internal*/ createTempVariable(recordTempVariable: ((node: Identifier) => void) | undefined, reservedInNestedScopes?: boolean, prefix?: string | GeneratedNamePart, suffix?: string): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ createTempVariable(recordTempVariable: ((node: Identifier) => void) | undefined, reservedInNestedScopes?: boolean, prefix?: string | GeneratedNamePart, suffix?: string): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures /** * Create a unique temporary variable for use in a loop. @@ -7701,17 +7793,17 @@ export interface NodeFactory { /** Create a unique name based on the supplied text. */ createUniqueName(text: string, flags?: GeneratedIdentifierFlags): Identifier; - /*@internal*/ createUniqueName(text: string, flags?: GeneratedIdentifierFlags, prefix?: string | GeneratedNamePart, suffix?: string): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ createUniqueName(text: string, flags?: GeneratedIdentifierFlags, prefix?: string | GeneratedNamePart, suffix?: string): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures /** Create a unique name generated for a node. */ getGeneratedNameForNode(node: Node | undefined, flags?: GeneratedIdentifierFlags): Identifier; - /*@internal*/ getGeneratedNameForNode(node: Node | undefined, flags?: GeneratedIdentifierFlags, prefix?: string | GeneratedNamePart, suffix?: string): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ getGeneratedNameForNode(node: Node | undefined, flags?: GeneratedIdentifierFlags, prefix?: string | GeneratedNamePart, suffix?: string): Identifier; // eslint-disable-line @typescript-eslint/unified-signatures createPrivateIdentifier(text: string): PrivateIdentifier createUniquePrivateName(text?: string): PrivateIdentifier; - /*@internal*/ createUniquePrivateName(text?: string, prefix?: string | GeneratedNamePart, suffix?: string): PrivateIdentifier; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ createUniquePrivateName(text?: string, prefix?: string | GeneratedNamePart, suffix?: string): PrivateIdentifier; // eslint-disable-line @typescript-eslint/unified-signatures getGeneratedPrivateNameForNode(node: Node): PrivateIdentifier; - /*@internal*/ getGeneratedPrivateNameForNode(node: Node, prefix?: string | GeneratedNamePart, suffix?: string): PrivateIdentifier; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ getGeneratedPrivateNameForNode(node: Node, prefix?: string | GeneratedNamePart, suffix?: string): PrivateIdentifier; // eslint-disable-line @typescript-eslint/unified-signatures // // Punctuation @@ -7727,7 +7819,7 @@ export interface NodeFactory { createToken(token: TKind): ModifierToken; createToken(token: TKind): KeywordToken; createToken(token: TKind): Token; - /*@internal*/ createToken(token: TKind): Token; + /** @internal */ createToken(token: TKind): Token; // // Reserved words @@ -7789,7 +7881,7 @@ export interface NodeFactory { createConstructSignature(typeParameters: readonly TypeParameterDeclaration[] | undefined, parameters: readonly ParameterDeclaration[], type: TypeNode | undefined): ConstructSignatureDeclaration; updateConstructSignature(node: ConstructSignatureDeclaration, typeParameters: NodeArray | undefined, parameters: NodeArray, type: TypeNode | undefined): ConstructSignatureDeclaration; createIndexSignature(modifiers: readonly Modifier[] | undefined, parameters: readonly ParameterDeclaration[], type: TypeNode): IndexSignatureDeclaration; - /* @internal */ createIndexSignature(modifiers: readonly Modifier[] | undefined, parameters: readonly ParameterDeclaration[], type: TypeNode | undefined): IndexSignatureDeclaration; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ createIndexSignature(modifiers: readonly Modifier[] | undefined, parameters: readonly ParameterDeclaration[], type: TypeNode | undefined): IndexSignatureDeclaration; // eslint-disable-line @typescript-eslint/unified-signatures updateIndexSignature(node: IndexSignatureDeclaration, modifiers: readonly Modifier[] | undefined, parameters: readonly ParameterDeclaration[], type: TypeNode): IndexSignatureDeclaration; createTemplateLiteralTypeSpan(type: TypeNode, literal: TemplateMiddle | TemplateTail): TemplateLiteralTypeSpan; updateTemplateLiteralTypeSpan(node: TemplateLiteralTypeSpan, type: TypeNode, literal: TemplateMiddle | TemplateTail): TemplateLiteralTypeSpan; @@ -7916,11 +8008,11 @@ export interface NodeFactory { createTemplateTail(text: string | undefined, rawText: string, templateFlags?: TokenFlags): TemplateTail; createNoSubstitutionTemplateLiteral(text: string, rawText?: string): NoSubstitutionTemplateLiteral; createNoSubstitutionTemplateLiteral(text: string | undefined, rawText: string): NoSubstitutionTemplateLiteral; - /* @internal */ createLiteralLikeNode(kind: LiteralToken["kind"] | SyntaxKind.JsxTextAllWhiteSpaces, text: string): LiteralToken; - /* @internal */ createTemplateLiteralLikeNode(kind: TemplateLiteralToken["kind"], text: string, rawText: string, templateFlags: TokenFlags | undefined): TemplateLiteralLikeNode; + /** @internal */ createLiteralLikeNode(kind: LiteralToken["kind"] | SyntaxKind.JsxTextAllWhiteSpaces, text: string): LiteralToken; + /** @internal */ createTemplateLiteralLikeNode(kind: TemplateLiteralToken["kind"], text: string, rawText: string, templateFlags: TokenFlags | undefined): TemplateLiteralLikeNode; createYieldExpression(asteriskToken: AsteriskToken, expression: Expression): YieldExpression; createYieldExpression(asteriskToken: undefined, expression: Expression | undefined): YieldExpression; - /* @internal */ createYieldExpression(asteriskToken: AsteriskToken | undefined, expression: Expression | undefined): YieldExpression; // eslint-disable-line @typescript-eslint/unified-signatures + /** @internal */ createYieldExpression(asteriskToken: AsteriskToken | undefined, expression: Expression | undefined): YieldExpression; // eslint-disable-line @typescript-eslint/unified-signatures updateYieldExpression(node: YieldExpression, asteriskToken: AsteriskToken | undefined, expression: Expression | undefined): YieldExpression; createSpreadElement(expression: Expression): SpreadElement; updateSpreadElement(node: SpreadElement, expression: Expression): SpreadElement; @@ -8038,7 +8130,7 @@ export interface NodeFactory { updateNamedExports(node: NamedExports, elements: readonly ExportSpecifier[]): NamedExports; createExportSpecifier(isTypeOnly: boolean, propertyName: string | Identifier | undefined, name: string | Identifier): ExportSpecifier; updateExportSpecifier(node: ExportSpecifier, isTypeOnly: boolean, propertyName: Identifier | undefined, name: Identifier): ExportSpecifier; - /* @internal*/ createMissingDeclaration(): MissingDeclaration; + /** @internal */ createMissingDeclaration(): MissingDeclaration; // // Module references @@ -8193,30 +8285,30 @@ export interface NodeFactory { createSourceFile(statements: readonly Statement[], endOfFileToken: EndOfFileToken, flags: NodeFlags): SourceFile; updateSourceFile(node: SourceFile, statements: readonly Statement[], isDeclarationFile?: boolean, referencedFiles?: readonly FileReference[], typeReferences?: readonly FileReference[], hasNoDefaultLib?: boolean, libReferences?: readonly FileReference[]): SourceFile; - /* @internal */ createUnparsedSource(prologues: readonly UnparsedPrologue[], syntheticReferences: readonly UnparsedSyntheticReference[] | undefined, texts: readonly UnparsedSourceText[]): UnparsedSource; - /* @internal */ createUnparsedPrologue(data?: string): UnparsedPrologue; - /* @internal */ createUnparsedPrepend(data: string | undefined, texts: readonly UnparsedSourceText[]): UnparsedPrepend; - /* @internal */ createUnparsedTextLike(data: string | undefined, internal: boolean): UnparsedTextLike; - /* @internal */ createUnparsedSyntheticReference(section: BundleFileHasNoDefaultLib | BundleFileReference): UnparsedSyntheticReference; - /* @internal */ createInputFiles(): InputFiles; + /** @internal */ createUnparsedSource(prologues: readonly UnparsedPrologue[], syntheticReferences: readonly UnparsedSyntheticReference[] | undefined, texts: readonly UnparsedSourceText[]): UnparsedSource; + /** @internal */ createUnparsedPrologue(data?: string): UnparsedPrologue; + /** @internal */ createUnparsedPrepend(data: string | undefined, texts: readonly UnparsedSourceText[]): UnparsedPrepend; + /** @internal */ createUnparsedTextLike(data: string | undefined, internal: boolean): UnparsedTextLike; + /** @internal */ createUnparsedSyntheticReference(section: BundleFileHasNoDefaultLib | BundleFileReference): UnparsedSyntheticReference; + /** @internal */ createInputFiles(): InputFiles; // // Synthetic Nodes // - /* @internal */ createSyntheticExpression(type: Type, isSpread?: boolean, tupleNameSource?: ParameterDeclaration | NamedTupleMember): SyntheticExpression; - /* @internal */ createSyntaxList(children: Node[]): SyntaxList; + /** @internal */ createSyntheticExpression(type: Type, isSpread?: boolean, tupleNameSource?: ParameterDeclaration | NamedTupleMember): SyntheticExpression; + /** @internal */ createSyntaxList(children: Node[]): SyntaxList; // // Transformation nodes // createNotEmittedStatement(original: Node): NotEmittedStatement; - /* @internal */ createEndOfDeclarationMarker(original: Node): EndOfDeclarationMarker; - /* @internal */ createMergeDeclarationMarker(original: Node): MergeDeclarationMarker; + /** @internal */ createEndOfDeclarationMarker(original: Node): EndOfDeclarationMarker; + /** @internal */ createMergeDeclarationMarker(original: Node): MergeDeclarationMarker; createPartiallyEmittedExpression(expression: Expression, original?: Node): PartiallyEmittedExpression; updatePartiallyEmittedExpression(node: PartiallyEmittedExpression, expression: Expression): PartiallyEmittedExpression; - /* @internal */ createSyntheticReferenceExpression(expression: Expression, thisArg: Expression): SyntheticReferenceExpression; - /* @internal */ updateSyntheticReferenceExpression(node: SyntheticReferenceExpression, expression: Expression, thisArg: Expression): SyntheticReferenceExpression; + /** @internal */ createSyntheticReferenceExpression(expression: Expression, thisArg: Expression): SyntheticReferenceExpression; + /** @internal */ updateSyntheticReferenceExpression(node: SyntheticReferenceExpression, expression: Expression, thisArg: Expression): SyntheticReferenceExpression; createCommaListExpression(elements: readonly Expression[]): CommaListExpression; updateCommaListExpression(node: CommaListExpression, elements: readonly Expression[]): CommaListExpression; createBundle(sourceFiles: readonly SourceFile[], prepends?: readonly (UnparsedSource | InputFiles)[]): Bundle; @@ -8274,19 +8366,19 @@ export interface NodeFactory { createExportDefault(expression: Expression): ExportAssignment; createExternalModuleExport(exportName: Identifier): ExportDeclaration; - /* @internal */ createTypeCheck(value: Expression, tag: TypeOfTag): Expression; - /* @internal */ createMethodCall(object: Expression, methodName: string | Identifier, argumentsList: readonly Expression[]): CallExpression; - /* @internal */ createGlobalMethodCall(globalObjectName: string, globalMethodName: string, argumentsList: readonly Expression[]): CallExpression; - /* @internal */ createFunctionBindCall(target: Expression, thisArg: Expression, argumentsList: readonly Expression[]): CallExpression; - /* @internal */ createFunctionCallCall(target: Expression, thisArg: Expression, argumentsList: readonly Expression[]): CallExpression; - /* @internal */ createFunctionApplyCall(target: Expression, thisArg: Expression, argumentsExpression: Expression): CallExpression; - /* @internal */ createObjectDefinePropertyCall(target: Expression, propertyName: string | Expression, attributes: Expression): CallExpression; - /* @internal */ createReflectGetCall(target: Expression, propertyKey: Expression, receiver?: Expression): CallExpression; - /* @internal */ createReflectSetCall(target: Expression, propertyKey: Expression, value: Expression, receiver?: Expression): CallExpression; - /* @internal */ createPropertyDescriptor(attributes: PropertyDescriptorAttributes, singleLine?: boolean): ObjectLiteralExpression; - /* @internal */ createArraySliceCall(array: Expression, start?: number | Expression): CallExpression; - /* @internal */ createArrayConcatCall(array: Expression, values: readonly Expression[]): CallExpression; - /* @internal */ createCallBinding(expression: Expression, recordTempVariable: (temp: Identifier) => void, languageVersion?: ScriptTarget, cacheIdentifiers?: boolean): CallBinding; + /** @internal */ createTypeCheck(value: Expression, tag: TypeOfTag): Expression; + /** @internal */ createMethodCall(object: Expression, methodName: string | Identifier, argumentsList: readonly Expression[]): CallExpression; + /** @internal */ createGlobalMethodCall(globalObjectName: string, globalMethodName: string, argumentsList: readonly Expression[]): CallExpression; + /** @internal */ createFunctionBindCall(target: Expression, thisArg: Expression, argumentsList: readonly Expression[]): CallExpression; + /** @internal */ createFunctionCallCall(target: Expression, thisArg: Expression, argumentsList: readonly Expression[]): CallExpression; + /** @internal */ createFunctionApplyCall(target: Expression, thisArg: Expression, argumentsExpression: Expression): CallExpression; + /** @internal */ createObjectDefinePropertyCall(target: Expression, propertyName: string | Expression, attributes: Expression): CallExpression; + /** @internal */ createReflectGetCall(target: Expression, propertyKey: Expression, receiver?: Expression): CallExpression; + /** @internal */ createReflectSetCall(target: Expression, propertyKey: Expression, value: Expression, receiver?: Expression): CallExpression; + /** @internal */ createPropertyDescriptor(attributes: PropertyDescriptorAttributes, singleLine?: boolean): ObjectLiteralExpression; + /** @internal */ createArraySliceCall(array: Expression, start?: number | Expression): CallExpression; + /** @internal */ createArrayConcatCall(array: Expression, values: readonly Expression[]): CallExpression; + /** @internal */ createCallBinding(expression: Expression, recordTempVariable: (temp: Identifier) => void, languageVersion?: ScriptTarget, cacheIdentifiers?: boolean): CallBinding; /** * Wraps an expression that cannot be an assignment target in an expression that can be. * @@ -8301,9 +8393,11 @@ export interface NodeFactory { * * @param paramName * @param expression + * + * @internal */ - /* @internal */ createAssignmentTargetWrapper(paramName: Identifier, expression: Expression): LeftHandSideExpression; - /* @internal */ inlineExpressions(expressions: readonly Expression[]): Expression; + createAssignmentTargetWrapper(paramName: Identifier, expression: Expression): LeftHandSideExpression; + /** @internal */ inlineExpressions(expressions: readonly Expression[]): Expression; /** * Gets the internal name of a declaration. This is primarily used for declarations that can be * referred to by name in the body of an ES5 class function body. An internal name will *never* @@ -8314,8 +8408,10 @@ export interface NodeFactory { * @param node The declaration. * @param allowComments A value indicating whether comments may be emitted for the name. * @param allowSourceMaps A value indicating whether source maps may be emitted for the name. + * + * @internal */ - /* @internal */ getInternalName(node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; + getInternalName(node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; /** * Gets the local name of a declaration. This is primarily used for declarations that can be * referred to by name in the declaration's immediate scope (classes, enums, namespaces). A @@ -8325,8 +8421,10 @@ export interface NodeFactory { * @param node The declaration. * @param allowComments A value indicating whether comments may be emitted for the name. * @param allowSourceMaps A value indicating whether source maps may be emitted for the name. + * + * @internal */ - /* @internal */ getLocalName(node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; + getLocalName(node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; /** * Gets the export name of a declaration. This is primarily used for declarations that can be * referred to by name in the declaration's immediate scope (classes, enums, namespaces). An @@ -8336,16 +8434,20 @@ export interface NodeFactory { * @param node The declaration. * @param allowComments A value indicating whether comments may be emitted for the name. * @param allowSourceMaps A value indicating whether source maps may be emitted for the name. + * + * @internal */ - /* @internal */ getExportName(node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; + getExportName(node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; /** * Gets the name of a declaration for use in declarations. * * @param node The declaration. * @param allowComments A value indicating whether comments may be emitted for the name. * @param allowSourceMaps A value indicating whether source maps may be emitted for the name. + * + * @internal */ - /* @internal */ getDeclarationName(node: Declaration | undefined, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; + getDeclarationName(node: Declaration | undefined, allowComments?: boolean, allowSourceMaps?: boolean): Identifier; /** * Gets a namespace-qualified name for use in expressions. * @@ -8353,8 +8455,10 @@ export interface NodeFactory { * @param name The name. * @param allowComments A value indicating whether comments may be emitted for the name. * @param allowSourceMaps A value indicating whether source maps may be emitted for the name. + * + * @internal */ - /* @internal */ getNamespaceMemberName(ns: Identifier, name: Identifier, allowComments?: boolean, allowSourceMaps?: boolean): PropertyAccessExpression; + getNamespaceMemberName(ns: Identifier, name: Identifier, allowComments?: boolean, allowSourceMaps?: boolean): PropertyAccessExpression; /** * Gets the exported name of a declaration for use in expressions. * @@ -8365,62 +8469,76 @@ export interface NodeFactory { * @param node The declaration. * @param allowComments A value indicating whether comments may be emitted for the name. * @param allowSourceMaps A value indicating whether source maps may be emitted for the name. + * + * @internal */ - /* @internal */ getExternalModuleOrNamespaceExportName(ns: Identifier | undefined, node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier | PropertyAccessExpression; + getExternalModuleOrNamespaceExportName(ns: Identifier | undefined, node: Declaration, allowComments?: boolean, allowSourceMaps?: boolean): Identifier | PropertyAccessExpression; // // Utilities // restoreOuterExpressions(outerExpression: Expression | undefined, innerExpression: Expression, kinds?: OuterExpressionKinds): Expression; - /* @internal */ restoreEnclosingLabel(node: Statement, outermostLabeledStatement: LabeledStatement | undefined, afterRestoreLabelCallback?: (node: LabeledStatement) => void): Statement; - /* @internal */ createUseStrictPrologue(): PrologueDirective; + /** @internal */ restoreEnclosingLabel(node: Statement, outermostLabeledStatement: LabeledStatement | undefined, afterRestoreLabelCallback?: (node: LabeledStatement) => void): Statement; + /** @internal */ createUseStrictPrologue(): PrologueDirective; /** * Copies any necessary standard and custom prologue-directives into target array. * @param source origin statements array * @param target result statements array * @param ensureUseStrict boolean determining whether the function need to add prologue-directives * @param visitor Optional callback used to visit any custom prologue directives. + * + * @internal */ - /* @internal */ copyPrologue(source: readonly Statement[], target: Push, ensureUseStrict?: boolean, visitor?: (node: Node) => VisitResult): number; + copyPrologue(source: readonly Statement[], target: Push, ensureUseStrict?: boolean, visitor?: (node: Node) => VisitResult): number; /** * Copies only the standard (string-expression) prologue-directives into the target statement-array. * @param source origin statements array * @param target result statements array * @param statementOffset The offset at which to begin the copy. * @param ensureUseStrict boolean determining whether the function need to add prologue-directives + * + * @internal */ - /* @internal */ copyStandardPrologue(source: readonly Statement[], target: Push, statementOffset: number | undefined, ensureUseStrict?: boolean): number; + copyStandardPrologue(source: readonly Statement[], target: Push, statementOffset: number | undefined, ensureUseStrict?: boolean): number; /** * Copies only the custom prologue-directives into target statement-array. * @param source origin statements array * @param target result statements array * @param statementOffset The offset at which to begin the copy. * @param visitor Optional callback used to visit any custom prologue directives. + * + * @internal */ - /* @internal */ copyCustomPrologue(source: readonly Statement[], target: Push, statementOffset: number, visitor?: (node: Node) => VisitResult, filter?: (node: Node) => boolean): number; - /* @internal */ copyCustomPrologue(source: readonly Statement[], target: Push, statementOffset: number | undefined, visitor?: (node: Node) => VisitResult, filter?: (node: Node) => boolean): number | undefined; - /* @internal */ ensureUseStrict(statements: NodeArray): NodeArray; - /* @internal */ liftToBlock(nodes: readonly Node[]): Statement; + copyCustomPrologue(source: readonly Statement[], target: Push, statementOffset: number, visitor?: (node: Node) => VisitResult, filter?: (node: Node) => boolean): number; + /** @internal */ copyCustomPrologue(source: readonly Statement[], target: Push, statementOffset: number | undefined, visitor?: (node: Node) => VisitResult, filter?: (node: Node) => boolean): number | undefined; + /** @internal */ ensureUseStrict(statements: NodeArray): NodeArray; + /** @internal */ liftToBlock(nodes: readonly Node[]): Statement; /** * Merges generated lexical declarations into a new statement list. + * + * @internal */ - /* @internal */ mergeLexicalEnvironment(statements: NodeArray, declarations: readonly Statement[] | undefined): NodeArray; + mergeLexicalEnvironment(statements: NodeArray, declarations: readonly Statement[] | undefined): NodeArray; /** * Appends generated lexical declarations to an array of statements. + * + * @internal */ - /* @internal */ mergeLexicalEnvironment(statements: Statement[], declarations: readonly Statement[] | undefined): Statement[]; + mergeLexicalEnvironment(statements: Statement[], declarations: readonly Statement[] | undefined): Statement[]; /** * Creates a shallow, memberwise clone of a node. * - The result will have its `original` pointer set to `node`. * - The result will have its `pos` and `end` set to `-1`. * - *DO NOT USE THIS* if a more appropriate function is available. + * + * @internal */ - /* @internal */ cloneNode(node: T): T; - /* @internal */ updateModifiers(node: T, modifiers: readonly Modifier[] | ModifierFlags | undefined): T; + cloneNode(node: T): T; + /** @internal */ updateModifiers(node: T, modifiers: readonly Modifier[] | ModifierFlags | undefined): T; } -/* @internal */ +/** @internal */ export const enum LexicalEnvironmentFlags { None = 0, InParameters = 1 << 0, // currently visiting a parameter list @@ -8436,8 +8554,8 @@ export interface CoreTransformationContext { /** Starts a new lexical environment. */ startLexicalEnvironment(): void; - /* @internal */ setLexicalEnvironmentFlags(flags: LexicalEnvironmentFlags, value: boolean): void; - /* @internal */ getLexicalEnvironmentFlags(): LexicalEnvironmentFlags; + /** @internal */ setLexicalEnvironmentFlags(flags: LexicalEnvironmentFlags, value: boolean): void; + /** @internal */ getLexicalEnvironmentFlags(): LexicalEnvironmentFlags; /** Suspends the current lexical environment, usually after visiting a parameter list. */ suspendLexicalEnvironment(): void; @@ -8454,21 +8572,24 @@ export interface CoreTransformationContext { /** Hoists a variable declaration to the containing scope. */ hoistVariableDeclaration(node: Identifier): void; - /*@internal*/ startBlockScope(): void; + /** @internal */ startBlockScope(): void; - /*@internal*/ endBlockScope(): Statement[] | undefined; + /** @internal */ endBlockScope(): Statement[] | undefined; - /*@internal*/ addBlockScopedVariable(node: Identifier): void; + /** @internal */ addBlockScopedVariable(node: Identifier): void; - /** Adds an initialization statement to the top of the lexical environment. */ - /* @internal */ + /** + * Adds an initialization statement to the top of the lexical environment. + * + * @internal + */ addInitializationStatement(node: Statement): void; } export interface TransformationContext extends CoreTransformationContext { - /*@internal*/ getEmitResolver(): EmitResolver; - /*@internal*/ getEmitHost(): EmitHost; - /*@internal*/ getEmitHelperFactory(): EmitHelperFactory; + /** @internal */ getEmitResolver(): EmitResolver; + /** @internal */ getEmitHost(): EmitHost; + /** @internal */ getEmitHelperFactory(): EmitHelperFactory; /** Records a request for a non-scoped emit helper in the current context. */ requestEmitHelper(helper: EmitHelper): void; @@ -8512,7 +8633,7 @@ export interface TransformationContext extends CoreTransformationContext { */ onEmitNode: (hint: EmitHint, node: Node, emitCallback: (hint: EmitHint, node: Node) => void) => void; - /* @internal */ addDiagnostic(diag: DiagnosticWithLocation): void; + /** @internal */ addDiagnostic(diag: DiagnosticWithLocation): void; } export interface TransformationResult { @@ -8607,14 +8728,14 @@ export interface Printer { * Prints a bundle of source files as-is, without any emit transformations. */ printBundle(bundle: Bundle): string; - /*@internal*/ writeNode(hint: EmitHint, node: Node, sourceFile: SourceFile | undefined, writer: EmitTextWriter): void; - /*@internal*/ writeList(format: ListFormat, list: NodeArray | undefined, sourceFile: SourceFile | undefined, writer: EmitTextWriter): void; - /*@internal*/ writeFile(sourceFile: SourceFile, writer: EmitTextWriter, sourceMapGenerator: SourceMapGenerator | undefined): void; - /*@internal*/ writeBundle(bundle: Bundle, writer: EmitTextWriter, sourceMapGenerator: SourceMapGenerator | undefined): void; - /*@internal*/ bundleFileInfo?: BundleFileInfo; + /** @internal */ writeNode(hint: EmitHint, node: Node, sourceFile: SourceFile | undefined, writer: EmitTextWriter): void; + /** @internal */ writeList(format: ListFormat, list: NodeArray | undefined, sourceFile: SourceFile | undefined, writer: EmitTextWriter): void; + /** @internal */ writeFile(sourceFile: SourceFile, writer: EmitTextWriter, sourceMapGenerator: SourceMapGenerator | undefined): void; + /** @internal */ writeBundle(bundle: Bundle, writer: EmitTextWriter, sourceMapGenerator: SourceMapGenerator | undefined): void; + /** @internal */ bundleFileInfo?: BundleFileInfo; } -/*@internal*/ +/** @internal */ export const enum BundleFileSectionKind { Prologue = "prologue", EmitHelpers = "emitHelpers", @@ -8630,51 +8751,51 @@ export const enum BundleFileSectionKind { // comments? } -/*@internal*/ +/** @internal */ export interface BundleFileSectionBase extends TextRange { kind: BundleFileSectionKind; data?: string; } -/*@internal*/ +/** @internal */ export interface BundleFilePrologue extends BundleFileSectionBase { kind: BundleFileSectionKind.Prologue; data: string; } -/*@internal*/ +/** @internal */ export interface BundleFileEmitHelpers extends BundleFileSectionBase { kind: BundleFileSectionKind.EmitHelpers; data: string; } -/*@internal*/ +/** @internal */ export interface BundleFileHasNoDefaultLib extends BundleFileSectionBase { kind: BundleFileSectionKind.NoDefaultLib; } -/*@internal*/ +/** @internal */ export interface BundleFileReference extends BundleFileSectionBase { kind: BundleFileSectionKind.Reference | BundleFileSectionKind.Type | BundleFileSectionKind.Lib | BundleFileSectionKind.TypeResolutionModeImport | BundleFileSectionKind.TypeResolutionModeRequire; data: string; } -/*@internal*/ +/** @internal */ export interface BundleFilePrepend extends BundleFileSectionBase { kind: BundleFileSectionKind.Prepend; data: string; texts: BundleFileTextLike[]; } -/*@internal*/ +/** @internal */ export type BundleFileTextLikeKind = BundleFileSectionKind.Text | BundleFileSectionKind.Internal; -/*@internal*/ +/** @internal */ export interface BundleFileTextLike extends BundleFileSectionBase { kind: BundleFileTextLikeKind; } -/*@internal*/ +/** @internal */ export type BundleFileSection = BundleFilePrologue | BundleFileEmitHelpers @@ -8683,31 +8804,31 @@ export type BundleFileSection = | BundleFilePrepend | BundleFileTextLike; -/*@internal*/ +/** @internal */ export interface SourceFilePrologueDirectiveExpression extends TextRange { text: string; } -/*@internal*/ +/** @internal */ export interface SourceFilePrologueDirective extends TextRange { expression: SourceFilePrologueDirectiveExpression; } -/*@internal*/ +/** @internal */ export interface SourceFilePrologueInfo { file: number; text: string; directives: SourceFilePrologueDirective[]; } -/*@internal*/ +/** @internal */ export interface SourceFileInfo { // List of helpers in own source files emitted if no prepend is present helpers?: string[]; prologues?: SourceFilePrologueInfo[]; } -/*@internal*/ +/** @internal */ export interface BundleFileInfo { sections: BundleFileSection[]; hash?: string; @@ -8715,7 +8836,7 @@ export interface BundleFileInfo { sources?: SourceFileInfo; } -/*@internal*/ +/** @internal */ export interface BundleBuildInfo { js?: BundleFileInfo; dts?: BundleFileInfo; @@ -8723,7 +8844,7 @@ export interface BundleBuildInfo { sourceFiles: readonly string[]; } -/* @internal */ +/** @internal */ export interface BuildInfo { bundle?: BundleBuildInfo; program?: ProgramBuildInfo; @@ -8778,16 +8899,16 @@ export interface PrintHandlers { * ``` */ substituteNode?(hint: EmitHint, node: Node): Node; - /*@internal*/ onEmitSourceMapOfNode?: (hint: EmitHint, node: Node, emitCallback: (hint: EmitHint, node: Node) => void) => void; - /*@internal*/ onEmitSourceMapOfToken?: (node: Node | undefined, token: SyntaxKind, writer: (s: string) => void, pos: number, emitCallback: (token: SyntaxKind, writer: (s: string) => void, pos: number) => number) => number; - /*@internal*/ onEmitSourceMapOfPosition?: (pos: number) => void; - /*@internal*/ onSetSourceFile?: (node: SourceFile) => void; - /*@internal*/ onBeforeEmitNode?: (node: Node | undefined) => void; - /*@internal*/ onAfterEmitNode?: (node: Node | undefined) => void; - /*@internal*/ onBeforeEmitNodeArray?: (nodes: NodeArray | undefined) => void; - /*@internal*/ onAfterEmitNodeArray?: (nodes: NodeArray | undefined) => void; - /*@internal*/ onBeforeEmitToken?: (node: Node) => void; - /*@internal*/ onAfterEmitToken?: (node: Node) => void; + /** @internal */ onEmitSourceMapOfNode?: (hint: EmitHint, node: Node, emitCallback: (hint: EmitHint, node: Node) => void) => void; + /** @internal */ onEmitSourceMapOfToken?: (node: Node | undefined, token: SyntaxKind, writer: (s: string) => void, pos: number, emitCallback: (token: SyntaxKind, writer: (s: string) => void, pos: number) => number) => number; + /** @internal */ onEmitSourceMapOfPosition?: (pos: number) => void; + /** @internal */ onSetSourceFile?: (node: SourceFile) => void; + /** @internal */ onBeforeEmitNode?: (node: Node | undefined) => void; + /** @internal */ onAfterEmitNode?: (node: Node | undefined) => void; + /** @internal */ onBeforeEmitNodeArray?: (nodes: NodeArray | undefined) => void; + /** @internal */ onAfterEmitNodeArray?: (nodes: NodeArray | undefined) => void; + /** @internal */ onBeforeEmitToken?: (node: Node) => void; + /** @internal */ onAfterEmitToken?: (node: Node) => void; } export interface PrinterOptions { @@ -8795,23 +8916,23 @@ export interface PrinterOptions { newLine?: NewLineKind; omitTrailingSemicolon?: boolean; noEmitHelpers?: boolean; - /*@internal*/ module?: CompilerOptions["module"]; - /*@internal*/ target?: CompilerOptions["target"]; - /*@internal*/ sourceMap?: boolean; - /*@internal*/ inlineSourceMap?: boolean; - /*@internal*/ inlineSources?: boolean; - /*@internal*/ extendedDiagnostics?: boolean; - /*@internal*/ onlyPrintJsDocStyle?: boolean; - /*@internal*/ neverAsciiEscape?: boolean; - /*@internal*/ writeBundleFileInfo?: boolean; - /*@internal*/ recordInternalSection?: boolean; - /*@internal*/ stripInternal?: boolean; - /*@internal*/ preserveSourceNewlines?: boolean; - /*@internal*/ terminateUnterminatedLiterals?: boolean; - /*@internal*/ relativeToBuildInfo?: (path: string) => string; -} - -/* @internal */ + /** @internal */ module?: CompilerOptions["module"]; + /** @internal */ target?: CompilerOptions["target"]; + /** @internal */ sourceMap?: boolean; + /** @internal */ inlineSourceMap?: boolean; + /** @internal */ inlineSources?: boolean; + /** @internal */ extendedDiagnostics?: boolean; + /** @internal */ onlyPrintJsDocStyle?: boolean; + /** @internal */ neverAsciiEscape?: boolean; + /** @internal */ writeBundleFileInfo?: boolean; + /** @internal */ recordInternalSection?: boolean; + /** @internal */ stripInternal?: boolean; + /** @internal */ preserveSourceNewlines?: boolean; + /** @internal */ terminateUnterminatedLiterals?: boolean; + /** @internal */ relativeToBuildInfo?: (path: string) => string; +} + +/** @internal */ export interface RawSourceMap { version: 3; file: string; @@ -8824,8 +8945,9 @@ export interface RawSourceMap { /** * Generates a source map. + * + * @internal */ -/* @internal */ export interface SourceMapGenerator { getSources(): readonly string[]; /** @@ -8862,7 +8984,7 @@ export interface SourceMapGenerator { toString(): string; } -/* @internal */ +/** @internal */ export interface DocumentPositionMapperHost { getSourceFileLike(fileName: string): SourceFileLike | undefined; getCanonicalFileName(path: string): string; @@ -8871,20 +8993,21 @@ export interface DocumentPositionMapperHost { /** * Maps positions between source and generated files. + * + * @internal */ -/* @internal */ export interface DocumentPositionMapper { getSourcePosition(input: DocumentPosition): DocumentPosition; getGeneratedPosition(input: DocumentPosition): DocumentPosition; } -/* @internal */ +/** @internal */ export interface DocumentPosition { fileName: string; pos: number; } -/* @internal */ +/** @internal */ export interface EmitTextWriter extends SymbolWriter { write(s: string): void; writeTrailingSemicolon(text: string): void; @@ -8908,12 +9031,12 @@ export interface GetEffectiveTypeRootsHost { getCurrentDirectory?(): string; } -/* @internal */ +/** @internal */ export interface HasCurrentDirectory { getCurrentDirectory(): string; } -/*@internal*/ +/** @internal */ export interface ModuleSpecifierResolutionHost { useCaseSensitiveFileNames?(): boolean; fileExists(path: string): boolean; @@ -8933,26 +9056,26 @@ export interface ModuleSpecifierResolutionHost { getFileIncludeReasons(): MultiMap; } -/* @internal */ +/** @internal */ export interface ModulePath { path: string; isInNodeModules: boolean; isRedirect: boolean; } -/*@internal*/ +/** @internal */ export interface ResolvedModuleSpecifierInfo { modulePaths: readonly ModulePath[] | undefined; moduleSpecifiers: readonly string[] | undefined; isBlockedByPackageJsonDependencies: boolean | undefined; } -/* @internal */ +/** @internal */ export interface ModuleSpecifierOptions { overrideImportMode?: SourceFile["impliedNodeFormat"]; } -/* @internal */ +/** @internal */ export interface ModuleSpecifierCache { get(fromFileName: Path, toFileName: Path, preferences: UserPreferences, options: ModuleSpecifierOptions): Readonly | undefined; set(fromFileName: Path, toFileName: Path, preferences: UserPreferences, options: ModuleSpecifierOptions, modulePaths: readonly ModulePath[], moduleSpecifiers: readonly string[]): void; @@ -8963,7 +9086,7 @@ export interface ModuleSpecifierCache { } // Note: this used to be deprecated in our public API, but is still used internally -/* @internal */ +/** @internal */ export interface SymbolTracker { // Called when the symbol writer encounters a symbol to write. Currently only used by the // declaration emitter to help determine if it should patch up the final declaration file @@ -8993,7 +9116,7 @@ export interface TextChangeRange { newLength: number; } -/* @internal */ +/** @internal */ export interface DiagnosticCollection { // Adds a diagnostic to this diagnostic collection. add(diagnostic: Diagnostic): void; @@ -9102,7 +9225,7 @@ export const enum ListFormat { JSDocComment = MultiLine | AsteriskDelimited, } -/* @internal */ +/** @internal */ export const enum PragmaKindFlags { None = 0, /** @@ -9126,14 +9249,14 @@ export const enum PragmaKindFlags { Default = All, } -/* @internal */ +/** @internal */ interface PragmaArgumentSpecification { name: TName; // Determines the name of the key in the resulting parsed type, type parameter to cause literal type inference optional?: boolean; captureSpan?: boolean; } -/* @internal */ +/** @internal */ export interface PragmaDefinition { args?: | readonly [PragmaArgumentSpecification] @@ -9146,7 +9269,7 @@ export interface PragmaDefinition = TDesc extends {captureSpan: true} ? {value: string, pos: number, end: number} : string; -/* @internal */ +/** @internal */ type PragmaArgTypeOptional = TDesc extends {optional: true} ? {[K in TName]?: PragmaArgTypeMaybeCapture} : {[K in TName]: PragmaArgTypeMaybeCapture}; -/* @internal */ +/** @internal */ type UnionToIntersection = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never; -/* @internal */ +/** @internal */ type ArgumentDefinitionToFieldUnion[]> = { [K in keyof T]: PragmaArgTypeOptional }[Extract]; // The mapped type maps over only the tuple members, but this reindex gets _all_ members - by extracting only `number` keys, we get only the tuple members /** * Maps a pragma definition into the desired shape for its arguments object + * + * @internal */ -/* @internal */ type PragmaArgumentType = ConcretePragmaSpecs[KPrag] extends { args: readonly PragmaArgumentSpecification[] } ? UnionToIntersection> : never; -/* @internal */ +/** @internal */ type ConcretePragmaSpecs = typeof commentPragmas; -/* @internal */ +/** @internal */ export type PragmaPseudoMap = {[K in keyof ConcretePragmaSpecs]: {arguments: PragmaArgumentType, range: CommentRange}}; -/* @internal */ +/** @internal */ export type PragmaPseudoMapEntry = {[K in keyof PragmaPseudoMap]: {name: K, args: PragmaPseudoMap[K]}}[keyof PragmaPseudoMap]; -/* @internal */ +/** @internal */ export interface ReadonlyPragmaMap extends ReadonlyESMap { get(key: TKey): PragmaPseudoMap[TKey] | PragmaPseudoMap[TKey][]; forEach(action: (value: PragmaPseudoMap[TKey] | PragmaPseudoMap[TKey][], key: TKey) => void): void; @@ -9236,15 +9360,16 @@ export interface ReadonlyPragmaMap extends ReadonlyESMap, ReadonlyPragmaMap { set(key: TKey, value: PragmaPseudoMap[TKey] | PragmaPseudoMap[TKey][]): this; get(key: TKey): PragmaPseudoMap[TKey] | PragmaPseudoMap[TKey][]; forEach(action: (value: PragmaPseudoMap[TKey] | PragmaPseudoMap[TKey][], key: TKey) => void): void; } -/* @internal */ +/** @internal */ export interface CommentDirectivesMap { getUnusedExpectations(): CommentDirective[]; markUsed(matchedLine: number): boolean; @@ -9288,7 +9413,7 @@ export interface PseudoBigInt { base10Value: string; } -/* @internal */ +/** @internal */ export interface Queue { enqueue(...items: T[]): void; dequeue(): T; diff --git a/src/compiler/utilities.ts b/src/compiler/utilities.ts index d62911e174b66..a81212f6d22b5 100644 --- a/src/compiler/utilities.ts +++ b/src/compiler/utilities.ts @@ -213,10 +213,11 @@ export function forEachAncestor(node: Node, callback: (n: Node) => T | undefi } } -/** @internal */ /** * Calls `callback` for each entry in the map, returning the first truthy result. * Use `map.forEach` instead for normal iteration. + * + * @internal */ export function forEachEntry(map: ReadonlyESMap, callback: (value: V, key: K) => U | undefined): U | undefined { const iterator = map.entries(); @@ -230,8 +231,11 @@ export function forEachEntry(map: ReadonlyESMap, callback: (value return undefined; } -/** @internal */ -/** `forEachEntry` for just keys. */ +/** + * `forEachEntry` for just keys. + * + * @internal + */ export function forEachKey(map: ReadonlyCollection, callback: (key: K) => T | undefined): T | undefined { const iterator = map.keys(); for (let iterResult = iterator.next(); !iterResult.done; iterResult = iterator.next()) { @@ -243,8 +247,11 @@ export function forEachKey(map: ReadonlyCollection, callback: (key: K) return undefined; } -/** @internal */ -/** Copy entries from `source` to `target`. */ +/** + * Copy entries from `source` to `target`. + * + * @internal + */ export function copyEntries(source: ReadonlyESMap, target: ESMap): void { source.forEach((value, key) => { target.set(key, value); @@ -459,10 +466,11 @@ export function getEndLinePosition(line: number, sourceFile: SourceFileLike): nu } } -/** @internal */ /** * Returns a value indicating whether a name is unique globally or within the current file. * Note: This does not consider whether a name appears as a free identifier or not, so at the expression `x.y` this includes both `x` and `y`. + * + * @internal */ export function isFileLevelUniqueName(sourceFile: SourceFile, name: string, hasGlobalName?: PrintHandlers["hasGlobalName"]): boolean { return !(hasGlobalName && hasGlobalName(name)) && !sourceFile.identifiers.has(name); @@ -525,9 +533,10 @@ function isAnyPrologueDirective(node: Node) { return isPrologueDirective(node) || !!(getEmitFlags(node) & EmitFlags.CustomPrologue); } -/** @internal */ /** * Prepends statements to an array while taking care of prologue directives. + * + * @internal */ export function insertStatementsAfterStandardPrologue(to: T[], from: readonly T[] | undefined): T[] { return insertStatementsAfterPrologue(to, from, isPrologueDirective); @@ -538,9 +547,10 @@ export function insertStatementsAfterCustomPrologue(to: T[] return insertStatementsAfterPrologue(to, from, isAnyPrologueDirective); } -/** @internal */ /** * Prepends statements to an array while taking care of prologue directives. + * + * @internal */ export function insertStatementAfterStandardPrologue(to: T[], statement: T | undefined): T[] { return insertStatementAfterPrologue(to, statement, isPrologueDirective); @@ -551,11 +561,12 @@ export function insertStatementAfterCustomPrologue(to: T[], return insertStatementAfterPrologue(to, statement, isAnyPrologueDirective); } -/** @internal */ /** * Determine if the given comment is a triple-slash * * @return true if the comment is a triple-slash comment else false + * + * @internal */ export function isRecognizedTripleSlashComment(text: string, commentPos: number, commentEnd: number) { // Verify this is /// comment, but do the regexp match only when we first can find /// in the comment text @@ -690,18 +701,20 @@ function getPos(range: Node) { return range.pos; } -/** @internal */ /** * Note: it is expected that the `nodeArray` and the `node` are within the same file. * For example, searching for a `SourceFile` in a `SourceFile[]` wouldn't work. + * + * @internal */ export function indexOfNode(nodeArray: readonly Node[], node: Node) { return binarySearch(nodeArray, node, getPos, compareValues); } -/** @internal */ /** * Gets flags that control emit behavior of a node. + * + * @internal */ export function getEmitFlags(node: Node): EmitFlags { const emitNode = node.emitNode; @@ -914,19 +927,23 @@ export function isNonGlobalAmbientModule(node: Node): node is ModuleDeclaration return isModuleDeclaration(node) && isStringLiteral(node.name); } -/** @internal */ /** * An effective module (namespace) declaration is either * 1. An actual declaration: namespace X { ... } * 2. A Javascript declaration, which is: * An identifier in a nested property access expression: Y in `X.Y.Z = { ... }` + * + * @internal */ export function isEffectiveModuleDeclaration(node: Node) { return isModuleDeclaration(node) || isIdentifier(node); } -/** @internal */ -/** Given a symbol for a module, checks that it is a shorthand ambient module. */ +/** + * Given a symbol for a module, checks that it is a shorthand ambient module. + * + * @internal + */ export function isShorthandAmbientModuleSymbol(moduleSymbol: Symbol): boolean { return isShorthandAmbientModule(moduleSymbol.valueDeclaration); } @@ -981,9 +998,10 @@ export function isEffectiveExternalModule(node: SourceFile, compilerOptions: Com return isExternalModule(node) || compilerOptions.isolatedModules || (isCommonJSContainingModuleKind(getEmitModuleKind(compilerOptions)) && !!node.commonJsModuleIndicator); } -/** @internal */ /** * Returns whether the source file will be treated as if it were in strict mode at runtime. + * + * @internal */ export function isEffectiveStrictModeSourceFile(node: SourceFile, compilerOptions: CompilerOptions) { // We can only verify strict mode for JS/TS files @@ -1690,12 +1708,13 @@ export function forEachYieldExpression(body: Block, visitor: (expr: YieldExpress } } -/** @internal */ /** * Gets the most likely element type for a TypeNode. This is not an exhaustive test * as it assumes a rest argument can only be an array type (either T[], or Array). * * @param node The type node. + * + * @internal */ export function getRestParameterElementType(node: TypeNode | undefined) { if (node && node.kind === SyntaxKind.ArrayType) { @@ -1961,9 +1980,10 @@ export function getThisContainer(node: Node, includeArrowFunctions: boolean): No } } -/** @internal */ /** * @returns Whether the node creates a new 'this' scope for its children. + * + * @internal */ export function isThisContainerOrFunctionBlock(node: Node): boolean { switch (node.kind) { @@ -2015,7 +2035,6 @@ export function getNewTargetContainer(node: Node) { return undefined; } -/** @internal */ /** * Given an super call/property node, returns the closest node where * - a super call/property access is legal in the node and not legal in the parent node the node. @@ -2023,6 +2042,8 @@ export function getNewTargetContainer(node: Node) { * - the container is an arrow function (so caller might need to call getSuperContainer again in case it needs to climb higher) * - a super call/property is definitely illegal in the container (but might be legal in some subnode) * i.e. super property access is illegal in function declaration but can be legal in the statement list + * + * @internal */ export function getSuperContainer(node: Node, stopOnFunctions: boolean): Node { while (true) { @@ -2089,9 +2110,10 @@ export function isSuperOrSuperProperty(node: Node): node is SuperExpression | Su || isSuperProperty(node); } -/** @internal */ /** * Determines whether a node is a property or element access expression for `super`. + * + * @internal */ export function isSuperProperty(node: Node): node is SuperProperty { const kind = node.kind; @@ -2099,9 +2121,10 @@ export function isSuperProperty(node: Node): node is SuperProperty { && (node as PropertyAccessExpression | ElementAccessExpression).expression.kind === SyntaxKind.SuperKeyword; } -/** @internal */ /** * Determines whether a node is a property or element access expression for `this`. + * + * @internal */ export function isThisProperty(node: Node): boolean { const kind = node.kind; @@ -2454,11 +2477,12 @@ export function isJSDocIndexSignature(node: TypeReferenceNode | ExpressionWithTy (node.typeArguments[0].kind === SyntaxKind.StringKeyword || node.typeArguments[0].kind === SyntaxKind.NumberKeyword); } -/** @internal */ /** * Returns true if the node is a CallExpression to the identifier 'require' with * exactly one argument (of the form 'require("name")'). * This function does not test if the node is in a JavaScript file or not. + * + * @internal */ export function isRequireCall(callExpression: Node, requireStringLiteralLikeArgument: true): callExpression is RequireOrImportCall & { expression: Identifier, arguments: [StringLiteralLike] }; /** @internal */ @@ -2481,18 +2505,20 @@ export function isRequireCall(callExpression: Node, requireStringLiteralLikeArgu return !requireStringLiteralLikeArgument || isStringLiteralLike(arg); } -/** @internal */ /** * Returns true if the node is a VariableDeclaration initialized to a require call (see `isRequireCall`). * This function does not test if the node is in a JavaScript file or not. + * + * @internal */ export function isVariableDeclarationInitializedToRequire(node: Node): node is VariableDeclarationInitializedTo { return isVariableDeclarationInitializedWithRequireHelper(node, /*allowAccessedRequire*/ false); } -/** @internal */ /** * Like {@link isVariableDeclarationInitializedToRequire} but allows things like `require("...").foo.bar` or `require("...")["baz"]`. + * + * @internal */ export function isVariableDeclarationInitializedToBareOrAccessedRequire(node: Node): node is VariableDeclarationInitializedTo { return isVariableDeclarationInitializedWithRequireHelper(node, /*allowAccessedRequire*/ true); @@ -2526,8 +2552,11 @@ export function isAssignmentDeclaration(decl: Declaration) { return isBinaryExpression(decl) || isAccessExpression(decl) || isIdentifier(decl) || isCallExpression(decl); } -/** @internal */ -/** Get the initializer, taking into account defaulted Javascript initializers */ +/** + * Get the initializer, taking into account defaulted Javascript initializers + * + * @internal + */ export function getEffectiveInitializer(node: HasExpressionInitializer) { if (isInJSFile(node) && node.initializer && isBinaryExpression(node.initializer) && @@ -2538,8 +2567,11 @@ export function getEffectiveInitializer(node: HasExpressionInitializer) { return node.initializer; } -/** @internal */ -/** Get the declaration initializer when it is container-like (See getExpandoInitializer). */ +/** + * Get the declaration initializer when it is container-like (See getExpandoInitializer). + * + * @internal + */ export function getDeclaredExpandoInitializer(node: HasExpressionInitializer) { const init = getEffectiveInitializer(node); return init && getExpandoInitializer(init, isPrototypeAccess(node.name)); @@ -2554,10 +2586,11 @@ function hasExpandoValueProperty(node: ObjectLiteralExpression, isPrototypeAssig getExpandoInitializer(p.initializer, isPrototypeAssignment)); } -/** @internal */ /** * Get the assignment 'initializer' -- the righthand side-- when the initializer is container-like (See getExpandoInitializer). * We treat the right hand side of assignments with container-like initializers as declarations. + * + * @internal */ export function getAssignedExpandoInitializer(node: Node | undefined): Expression | undefined { if (node && node.parent && isBinaryExpression(node.parent) && node.parent.operatorToken.kind === SyntaxKind.EqualsToken) { @@ -2573,7 +2606,6 @@ export function getAssignedExpandoInitializer(node: Node | undefined): Expressio } } -/** @internal */ /** * Recognized expando initializers are: * 1. (function() {})() -- IIFEs @@ -2583,6 +2615,8 @@ export function getAssignedExpandoInitializer(node: Node | undefined): Expressio * 5. { ... } -- Non-empty object literals, when used to initialize a prototype, like `C.prototype = { m() { } }` * * This function returns the provided initializer, or undefined if it is not valid. + * + * @internal */ export function getExpandoInitializer(initializer: Node, isPrototypeAssignment: boolean): Expression | undefined { if (isCallExpression(initializer)) { @@ -2624,8 +2658,11 @@ export function isDefaultedExpandoInitializer(node: BinaryExpression) { return name && getExpandoInitializer(node.right, isPrototypeAccess(name)) && isEntityNameExpression(name) && isSameEntityName(name, node.left); } -/** @internal */ -/** Given an expando initializer, return its declaration name, or the left-hand side of the assignment if it's part of an assignment declaration. */ +/** + * Given an expando initializer, return its declaration name, or the left-hand side of the assignment if it's part of an assignment declaration. + * + * @internal + */ export function getNameOfExpando(node: Declaration): DeclarationName | undefined { if (isBinaryExpression(node.parent)) { const parent = ((node.parent.operatorToken.kind === SyntaxKind.BarBarToken || node.parent.operatorToken.kind === SyntaxKind.QuestionQuestionToken) && isBinaryExpression(node.parent.parent)) ? node.parent.parent : node.parent; @@ -2638,7 +2675,6 @@ export function getNameOfExpando(node: Declaration): DeclarationName | undefined } } -/** @internal */ /** * Is the 'declared' name the same as the one in the initializer? * @return true for identical entity names, as well as ones where the initializer is prefixed with @@ -2647,6 +2683,8 @@ export function getNameOfExpando(node: Declaration): DeclarationName | undefined * var my = my || {} * var min = window.min || {} * my.app = self.my.app || class { } + * + * @internal */ export function isSameEntityName(name: Expression, initializer: Expression): boolean { if (isPropertyNameLiteral(name) && isPropertyNameLiteral(initializer)) { @@ -2711,27 +2749,39 @@ export function isBindableObjectDefinePropertyCall(expr: CallExpression): expr i isBindableStaticNameExpression(expr.arguments[0], /*excludeThisKeyword*/ true); } -/** @internal */ -/** x.y OR x[0] */ +/** + * x.y OR x[0] + * + * @internal + */ export function isLiteralLikeAccess(node: Node): node is LiteralLikeElementAccessExpression | PropertyAccessExpression { return isPropertyAccessExpression(node) || isLiteralLikeElementAccess(node); } -/** @internal */ -/** x[0] OR x['a'] OR x[Symbol.y] */ +/** + * x[0] OR x['a'] OR x[Symbol.y] + * + * @internal + */ export function isLiteralLikeElementAccess(node: Node): node is LiteralLikeElementAccessExpression { return isElementAccessExpression(node) && isStringOrNumericLiteralLike(node.argumentExpression); } -/** @internal */ -/** Any series of property and element accesses. */ +/** + * Any series of property and element accesses. + * + * @internal + */ export function isBindableStaticAccessExpression(node: Node, excludeThisKeyword?: boolean): node is BindableStaticAccessExpression { return isPropertyAccessExpression(node) && (!excludeThisKeyword && node.expression.kind === SyntaxKind.ThisKeyword || isIdentifier(node.name) && isBindableStaticNameExpression(node.expression, /*excludeThisKeyword*/ true)) || isBindableStaticElementAccessExpression(node, excludeThisKeyword); } -/** @internal */ -/** Any series of property and element accesses, ending in a literal element access */ +/** + * Any series of property and element accesses, ending in a literal element access + * + * @internal + */ export function isBindableStaticElementAccessExpression(node: Node, excludeThisKeyword?: boolean): node is BindableStaticElementAccessExpression { return isLiteralLikeElementAccess(node) && ((!excludeThisKeyword && node.expression.kind === SyntaxKind.ThisKeyword) || @@ -2783,8 +2833,9 @@ function isVoidZero(node: Node) { /** * Does not handle signed numeric names like `a[+0]` - handling those would require handling prefix unary expressions * throughout late binding handling as well, which is awkward (but ultimately probably doable if there is demand) + * + * @internal */ -/* @internal */ export function getElementOrPropertyAccessArgumentExpressionOrName(node: AccessExpression): Identifier | PrivateIdentifier | StringLiteralLike | NumericLiteral | ElementAccessExpression | undefined { if (isPropertyAccessExpression(node)) { return node.name; @@ -2796,7 +2847,7 @@ export function getElementOrPropertyAccessArgumentExpressionOrName(node: AccessE return node; } -/* @internal */ +/** @internal */ export function getElementOrPropertyAccessName(node: LiteralLikeElementAccessExpression | PropertyAccessExpression): __String; /** @internal */ export function getElementOrPropertyAccessName(node: AccessExpression): __String | undefined; @@ -3138,8 +3189,11 @@ export function getNextJSDocCommentLocation(node: Node) { } } -/** @internal */ -/** Does the opposite of `getJSDocParameterTags`: given a JSDoc parameter, finds the parameter corresponding to it. */ +/** + * Does the opposite of `getJSDocParameterTags`: given a JSDoc parameter, finds the parameter corresponding to it. + * + * @internal + */ export function getParameterSymbolFromJSDoc(node: JSDocParameterTag): Symbol | undefined { if (node.symbol) { return node.symbol; @@ -3192,8 +3246,11 @@ export function getEffectiveJSDocHost(node: Node): Node | undefined { } } -/** @internal */ -/** Use getEffectiveJSDocHost if you additionally need to look for jsdoc on parent nodes, like assignments. */ +/** + * Use getEffectiveJSDocHost if you additionally need to look for jsdoc on parent nodes, like assignments. + * + * @internal + */ export function getJSDocHost(node: Node): HasJSDoc | undefined { const jsDoc = getJSDocRoot(node); if (!jsDoc) { @@ -3301,10 +3358,11 @@ export type NodeWithPossibleHoistedDeclaration = | TryStatement | CatchClause; -/** @internal */ /** * Indicates whether a node could contain a `var` VariableDeclarationList that contributes to * the same `var` declaration scope as the node's parent. + * + * @internal */ export function isNodeWithPossibleHoistedDeclaration(node: Node): node is NodeWithPossibleHoistedDeclaration { switch (node.kind) { @@ -3360,11 +3418,12 @@ export function walkUpParenthesizedExpressions(node: Node) { return walkUp(node, SyntaxKind.ParenthesizedExpression); } -/** @internal */ /** * Walks up parenthesized types. * It returns both the outermost parenthesized type and its parent. * If given node is not a parenthesiezd type, undefined is return as the former. + * + * @internal */ export function walkUpParenthesizedTypesAndGetParentAndChild(node: Node): [ParenthesizedTypeNode | undefined, Node] { let child: ParenthesizedTypeNode | undefined; @@ -3602,8 +3661,11 @@ export function getEffectiveImplementsTypeNodes(node: ClassLikeDeclaration): und } } -/** @internal */ -/** Returns the node in an `extends` or `implements` clause of a class or interface. */ +/** + * Returns the node in an `extends` or `implements` clause of a class or interface. + * + * @internal + */ export function getAllSuperTypeNodes(node: Node): readonly TypeNode[] { return isInterfaceDeclaration(node) ? getInterfaceBaseTypeNodes(node) || emptyArray : isClassLike(node) ? concatenate(singleElementArray(getEffectiveBaseTypeNode(node)), getEffectiveImplementsTypeNodes(node)) || emptyArray : @@ -3745,7 +3807,6 @@ export function isSignedNumericLiteral(node: Node): node is PrefixUnaryExpressio return isPrefixUnaryExpression(node) && (node.operator === SyntaxKind.PlusToken || node.operator === SyntaxKind.MinusToken) && isNumericLiteral(node.operand); } -/** @internal */ /** * A declaration has a dynamic name if all of the following are true: * 1. The declaration has a computed property name. @@ -3753,6 +3814,8 @@ export function isSignedNumericLiteral(node: Node): node is PrefixUnaryExpressio * 3. The computed name is *not* expressed as a NumericLiteral. * 4. The computed name is *not* expressed as a PlusToken or MinusToken * immediately followed by a NumericLiteral. + * + * @internal */ export function hasDynamicName(declaration: Declaration): declaration is DynamicNamedDeclaration | DynamicNamedBinaryExpression { const name = getNameOfDeclaration(declaration); @@ -3837,9 +3900,10 @@ export function isPrivateIdentifierSymbol(symbol: Symbol): boolean { return startsWith(symbol.escapedName as string, "__#"); } -/** @internal */ /** * Includes the word "Symbol" with unicode escapes + * + * @internal */ export function isESSymbolIdentifier(node: Node): boolean { return node.kind === SyntaxKind.Identifier && (node as Identifier).escapedText === "Symbol"; @@ -4453,11 +4517,12 @@ function getReplacement(c: string, offset: number, input: string) { return escapedCharsMap.get(c) || encodeUtf16EscapeSequence(c.charCodeAt(0)); } -/** @internal */ /** * Based heavily on the abstract 'Quote'/'QuoteJSONString' operation from ECMA-262 (24.3.2.2), * but augmented for a few select characters (e.g. lineSeparator, paragraphSeparator, nextLine) * Note that this doesn't actually wrap the input in double quotes. + * + * @internal */ export function escapeString(s: string, quoteChar?: CharacterCodes.doubleQuote | CharacterCodes.singleQuote | CharacterCodes.backtick): string { const escapedCharsRegExp = @@ -4509,11 +4574,12 @@ export function escapeJsxAttributeString(s: string, quoteChar?: CharacterCodes.d return s.replace(escapedCharsRegExp, getJsxAttributeStringReplacement); } -/** @internal */ /** * Strip off existed surrounding single quotes, double quotes, or backticks from a given string * * @return non-quoted string + * + * @internal */ export function stripQuotes(name: string) { const length = name.length; @@ -4783,9 +4849,10 @@ export function getExternalModuleNameFromDeclaration(host: ResolveModuleNameReso return getResolvedExternalModuleName(host, file); } -/** @internal */ /** * Resolves a local path to a path which is absolute to the base of the emit + * + * @internal */ export function getExternalModuleNameFromPath(host: ResolveModuleNameResolutionHost, fileName: string, referencePath?: string): string { const getCanonicalFileName = (f: string) => host.getCanonicalFileName(f); @@ -4834,9 +4901,10 @@ export function getDeclarationEmitExtensionForPath(path: string) { Extension.Dts; } -/** @internal */ /** * This function is an inverse of `getDeclarationEmitExtensionForPath`. + * + * @internal */ export function getPossibleOriginalInputExtensionForExtension(path: string) { return fileExtensionIsOneOf(path, [Extension.Dmts, Extension.Mjs, Extension.Mts]) ? [Extension.Mts, Extension.Mjs] : @@ -4850,8 +4918,11 @@ export function outFile(options: CompilerOptions) { return options.outFile || options.out; } -/** @internal */ -/** Returns 'undefined' if and only if 'options.paths' is undefined. */ +/** + * Returns 'undefined' if and only if 'options.paths' is undefined. + * + * @internal + */ export function getPathsBasePath(options: CompilerOptions, host: { getCurrentDirectory?(): string }) { if (!options.paths) return undefined; return options.baseUrl ?? Debug.checkDefined(options.pathsBasePath || host.getCurrentDirectory?.(), "Encountered 'paths' without a 'baseUrl', config file, or host 'getCurrentDirectory'."); @@ -4866,7 +4937,6 @@ export interface EmitFileNames { buildInfoPath?: string | undefined; } -/** @internal */ /** * Gets the source files that are expected to have an emit output. * @@ -4875,6 +4945,8 @@ export interface EmitFileNames { * * @param host An EmitHost. * @param targetSourceFile An optional target source file to emit. + * + * @internal */ export function getSourceFilesToEmit(host: EmitHost, targetSourceFile?: SourceFile, forceDtsEmit?: boolean): readonly SourceFile[] { const options = host.getCompilerOptions(); @@ -4898,8 +4970,11 @@ export function getSourceFilesToEmit(host: EmitHost, targetSourceFile?: SourceFi } } -/** @internal */ -/** Don't call this for `--outFile`, just for `--outDir` or plain emit. `--outFile` needs additional checks. */ +/** + * Don't call this for `--outFile`, just for `--outDir` or plain emit. `--outFile` needs additional checks. + * + * @internal + */ export function sourceFileMayBeEmitted(sourceFile: SourceFile, host: SourceFileMayBeEmittedHost, forceDtsEmit?: boolean) { const options = host.getCompilerOptions(); return !(options.noEmitForJsFiles && isSourceFileJS(sourceFile)) && @@ -4986,8 +5061,11 @@ export function getSetAccessorValueParameter(accessor: SetAccessorDeclaration): } } -/** @internal */ -/** Get the type annotation for the value parameter. */ +/** + * Get the type annotation for the value parameter. + * + * @internal + */ export function getSetAccessorTypeAnnotationNode(accessor: SetAccessorDeclaration): TypeNode | undefined { const parameter = getSetAccessorValueParameter(accessor); return parameter && parameter.type; @@ -5084,11 +5162,12 @@ export function getAllAccessorDeclarations(declarations: readonly Declaration[], }; } -/** @internal */ /** * Gets the effective type annotation of a variable, parameter, or property. If the node was * parsed in a JavaScript file, gets the type annotation from JSDoc. Also gets the type of * functions only the JSDoc case. + * + * @internal */ export function getEffectiveTypeAnnotationNode(node: Node): TypeNode | undefined { if (!isInJSFile(node) && isFunctionDeclaration(node)) return undefined; @@ -5102,10 +5181,11 @@ export function getTypeAnnotationNode(node: Node): TypeNode | undefined { return (node as HasType).type; } -/** @internal */ /** * Gets the effective return type annotation of a signature. If the node was parsed in a * JavaScript file, gets the return type annotation from JSDoc. + * + * @internal */ export function getEffectiveReturnTypeNode(node: SignatureDeclaration | JSDocSignature): TypeNode | undefined { return isJSDocSignature(node) ? @@ -5123,10 +5203,11 @@ function isNonTypeAliasTemplate(tag: JSDocTag): tag is JSDocTemplateTag { return isJSDocTemplateTag(tag) && !(tag.parent.kind === SyntaxKind.JSDoc && tag.parent.tags!.some(isJSDocTypeAlias)); } -/** @internal */ /** * Gets the effective type annotation of the value parameter of a set accessor. If the node * was parsed in a JavaScript file, gets the type annotation from JSDoc. + * + * @internal */ export function getEffectiveSetAccessorTypeAnnotationNode(node: SetAccessorDeclaration): TypeNode | undefined { const parameter = getSetAccessorValueParameter(node); @@ -5193,10 +5274,11 @@ export function emitComments( } } -/** @internal */ /** * Detached comment is a comment at the top of file or function body that is separated from * the next statement by space. + * + * @internal */ export function emitDetachedComments(text: string, lineMap: readonly number[], writer: EmitTextWriter, writeComment: (text: string, lineMap: readonly number[], writer: EmitTextWriter, commentPos: number, commentEnd: number, newLine: string) => void, @@ -5447,11 +5529,12 @@ function getModifierFlagsWorker(node: Node, includeJSDoc: boolean, alwaysInclude return node.modifierFlagsCache & ~(ModifierFlags.HasComputedFlags | ModifierFlags.HasComputedJSDocModifiers); } -/** @internal */ /** * Gets the effective ModifierFlags for the provided node, including JSDoc modifiers. The modifiers will be cached on the node to improve performance. * * NOTE: This function may use `parent` pointers. + * + * @internal */ export function getEffectiveModifierFlags(node: Node): ModifierFlags { return getModifierFlagsWorker(node, /*includeJSDoc*/ true); @@ -5462,11 +5545,12 @@ export function getEffectiveModifierFlagsAlwaysIncludeJSDoc(node: Node): Modifie return getModifierFlagsWorker(node, /*includeJSDOc*/ true, /*alwaysIncludeJSDOc*/ true); } -/** @internal */ /** * Gets the ModifierFlags for syntactic modifiers on the provided node. The modifiers will be cached on the node to improve performance. * * NOTE: This function does not use `parent` pointers and will not include modifiers from JSDoc. + * + * @internal */ export function getSyntacticModifierFlags(node: Node): ModifierFlags { return getModifierFlagsWorker(node, /*includeJSDoc*/ false); @@ -5488,21 +5572,23 @@ function getJSDocModifierFlagsNoCache(node: Node): ModifierFlags { return flags; } -/** @internal */ /** * Gets the effective ModifierFlags for the provided node, including JSDoc modifiers. The modifier flags cache on the node is ignored. * * NOTE: This function may use `parent` pointers. + * + * @internal */ export function getEffectiveModifierFlagsNoCache(node: Node): ModifierFlags { return getSyntacticModifierFlagsNoCache(node) | getJSDocModifierFlagsNoCache(node); } -/** @internal */ /** * Gets the ModifierFlags for syntactic modifiers on the provided node. The modifier flags cache on the node is ignored. * * NOTE: This function does not use `parent` pointers and will not include modifiers from JSDoc. + * + * @internal */ export function getSyntacticModifierFlagsNoCache(node: Node): ModifierFlags { let flags = canHaveModifiers(node) ? modifiersToFlags(node.modifiers) : ModifierFlags.None; @@ -5570,8 +5656,11 @@ export function isAssignmentOperator(token: SyntaxKind): boolean { return token >= SyntaxKind.FirstAssignment && token <= SyntaxKind.LastAssignment; } -/** @internal */ -/** Get `C` given `N` if `N` is in the position `class C extends N` where `N` is an ExpressionWithTypeArguments. */ +/** + * Get `C` given `N` if `N` is in the position `class C extends N` where `N` is an ExpressionWithTypeArguments. + * + * @internal + */ export function tryGetClassExtendingExpressionWithTypeArguments(node: Node): ClassLikeDeclaration | undefined { const cls = tryGetClassImplementingOrExtendingExpressionWithTypeArguments(node); return cls && !cls.isImplements ? cls.class : undefined; @@ -5731,8 +5820,11 @@ function isExportDefaultSymbol(symbol: Symbol): boolean { return symbol && length(symbol.declarations) > 0 && hasSyntacticModifier(symbol.declarations![0], ModifierFlags.Default); } -/** @internal */ -/** Return ".ts", ".d.ts", or ".tsx", if that is the extension. */ +/** + * Return ".ts", ".d.ts", or ".tsx", if that is the extension. + * + * @internal + */ export function tryExtractTSExtension(fileName: string): string | undefined { return find(supportedTSExtensionsForExtractExtension, extension => fileExtensionIs(fileName, extension)); } @@ -5776,9 +5868,10 @@ function getExpandedCharCodes(input: string): number[] { const base64Digits = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/="; -/** @internal */ /** * Converts a string to a base-64 encoded ASCII string. + * + * @internal */ export function convertToBase64(input: string): string { let result = ""; @@ -5924,43 +6017,47 @@ export function getNewLineCharacter(options: CompilerOptions | PrinterOptions, g return getNewLine ? getNewLine() : sys ? sys.newLine : carriageReturnLineFeed; } -/** @internal */ /** * Creates a new TextRange from the provided pos and end. * * @param pos The start position. * @param end The end position. + * + * @internal */ export function createRange(pos: number, end: number = pos): TextRange { Debug.assert(end >= pos || end === -1); return { pos, end }; } -/** @internal */ /** * Creates a new TextRange from a provided range with a new end position. * * @param range A TextRange. * @param end The new end position. + * + * @internal */ export function moveRangeEnd(range: TextRange, end: number): TextRange { return createRange(range.pos, end); } -/** @internal */ /** * Creates a new TextRange from a provided range with a new start position. * * @param range A TextRange. * @param pos The new Start position. + * + * @internal */ export function moveRangePos(range: TextRange, pos: number): TextRange { return createRange(pos, range.end); } -/** @internal */ /** * Moves the start position of a range past any decorators. + * + * @internal */ export function moveRangePastDecorators(node: Node): TextRange { const lastDecorator = canHaveModifiers(node) ? findLast(node.modifiers, isDecorator) : undefined; @@ -5969,9 +6066,10 @@ export function moveRangePastDecorators(node: Node): TextRange { : node; } -/** @internal */ /** * Moves the start position of a range past any decorators or modifiers. + * + * @internal */ export function moveRangePastModifiers(node: Node): TextRange { const lastModifier = canHaveModifiers(node) ? lastOrUndefined(node.modifiers) : undefined; @@ -5980,22 +6078,24 @@ export function moveRangePastModifiers(node: Node): TextRange { : moveRangePastDecorators(node); } -/** @internal */ /** * Determines whether a TextRange has the same start and end positions. * * @param range A TextRange. + * + * @internal */ export function isCollapsedRange(range: TextRange) { return range.pos === range.end; } -/** @internal */ /** * Creates a new TextRange for a token at the provides start position. * * @param pos The start position. * @param token The token. + * + * @internal */ export function createTokenRange(pos: number, token: SyntaxKind): TextRange { return createRange(pos, pos + tokenToString(token)!.length); @@ -6076,10 +6176,11 @@ function getPreviousNonWhitespacePosition(pos: number, stopPos = 0, sourceFile: } } -/** @internal */ /** * Determines whether a name was originally the declaration name of an enum or namespace * declaration. + * + * @internal */ export function isDeclarationNameOfEnumOrNamespace(node: Identifier) { const parseNode = getParseTreeNode(node); @@ -6145,8 +6246,11 @@ export function skipAlias(symbol: Symbol, checker: TypeChecker) { return symbol.flags & SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol; } -/** @internal */ -/** See comment on `declareModuleMember` in `binder.ts`. */ +/** + * See comment on `declareModuleMember` in `binder.ts`. + * + * @internal + */ export function getCombinedLocalAndExportSymbolFlags(symbol: Symbol): SymbolFlags { return symbol.exportSymbol ? symbol.exportSymbol.flags | symbol.flags : symbol.flags; } @@ -6240,9 +6344,10 @@ export function compareDataObjects(dst: any, src: any): boolean { return true; } -/** @internal */ /** * clears already present map by calling onDeleteExistingValue callback before deleting that key/value + * + * @internal */ export function clearMap(map: { forEach: ESMap["forEach"]; clear: ESMap["clear"]; }, onDeleteValue: (valueInMap: T, key: K) => void) { // Remove all @@ -6263,9 +6368,10 @@ export interface MutateMapSkippingNewValuesOptions { onExistingValue?(existingValue: T, valueInNewMap: U, key: K): void; } -/** @internal */ /** * Mutates the map with newMap such that keys in map will be same as newMap. + * + * @internal */ export function mutateMapSkippingNewValues( map: ESMap, @@ -6293,9 +6399,10 @@ export interface MutateMapOptions extends MutateMapSkippingNewValuesOpt createNewValue(key: K, valueInNewMap: U): T; } -/** @internal */ /** * Mutates the map with newMap such that keys in map will be same as newMap. + * + * @internal */ export function mutateMap(map: ESMap, newMap: ReadonlyESMap, options: MutateMapOptions) { // Needs update @@ -6369,8 +6476,11 @@ export function getLastChild(node: Node): Node | undefined { return lastChild; } -/** @internal */ -/** Add a value to a set, and return true if it wasn't already present. */ +/** + * Add a value to a set, and return true if it wasn't already present. + * + * @internal + */ export function addToSeen(seen: ESMap, key: K): boolean; /** @internal */ export function addToSeen(seen: ESMap, key: K, value: T): boolean; @@ -6632,12 +6742,12 @@ export function formatStringFromArgs(text: string, args: ArrayLike | undefined; -/* @internal */ +/** @internal */ export function setLocalizedDiagnosticMessages(messages: typeof localizedDiagnosticMessages) { localizedDiagnosticMessages = messages; } -/* @internal */ +/** @internal */ // If the localized messages json is unset, and if given function use it to set the json export function maybeSetLocalizedDiagnosticMessages(getMessages: undefined | (() => typeof localizedDiagnosticMessages)) { @@ -7360,10 +7470,11 @@ export function getRegularExpressionsForWildcards(specs: readonly string[] | und spec && getSubPatternFromSpec(spec, basePath, usage, wildcardMatchers[usage])); } -/** @internal */ /** * An "includes" path "foo" is implicitly a glob "foo/** /*" (without the space) if its last component has no extension, * and does not contain any glob characters itself. + * + * @internal */ export function isImplicitGlob(lastPathComponent: string): boolean { return !/[.*?]/.test(lastPathComponent); @@ -7472,8 +7583,11 @@ export interface FileMatcherPatterns { basePaths: readonly string[]; } -/** @internal */ -/** @param path directory of the tsconfig.json */ +/** + * @param path directory of the tsconfig.json + * + * @internal + */ export function getFileMatcherPatterns(path: string, excludes: readonly string[] | undefined, includes: readonly string[] | undefined, useCaseSensitiveFileNames: boolean, currentDirectory: string): FileMatcherPatterns { path = normalizePath(path); currentDirectory = normalizePath(currentDirectory); @@ -7493,8 +7607,11 @@ export function getRegexFromPattern(pattern: string, useCaseSensitiveFileNames: return new RegExp(pattern, useCaseSensitiveFileNames ? "" : "i"); } -/** @internal */ -/** @param path directory of the tsconfig.json */ +/** + * @param path directory of the tsconfig.json + * + * @internal + */ export function matchFiles(path: string, extensions: readonly string[] | undefined, excludes: readonly string[] | undefined, includes: readonly string[] | undefined, useCaseSensitiveFileNames: boolean, currentDirectory: string, depth: number | undefined, getFileSystemEntries: (path: string) => FileSystemEntries, realpath: (path: string) => string): string[] { path = normalizePath(path); currentDirectory = normalizePath(currentDirectory); @@ -7634,9 +7751,10 @@ export function getScriptKindFromFileName(fileName: string): ScriptKind { } } -/** @internal */ /** * Groups of supported extensions in order of file resolution precedence. (eg, TS > TSX > DTS and seperately, CTS > DCTS) + * + * @internal */ export const supportedTSExtensions: readonly Extension[][] = [[Extension.Ts, Extension.Tsx, Extension.Dts], [Extension.Cts, Extension.Dcts], [Extension.Mts, Extension.Dmts]]; /** @internal */ @@ -7754,10 +7872,11 @@ export function changeExtension(path: T, newExtension: return changeAnyExtension(path, newExtension, extensionsToRemove, /*ignoreCase*/ false) as T; } -/** @internal */ /** * Returns the input if there are no stars, a pattern if there is exactly one, * and undefined if there are more. + * + * @internal */ export function tryParsePattern(pattern: string): string | Pattern | undefined { const indexOfStar = pattern.indexOf("*"); @@ -7784,8 +7903,11 @@ export function positionIsSynthesized(pos: number): boolean { return !(pos >= 0); } -/** @internal */ -/** True if an extension is one of the supported TypeScript extensions. */ +/** + * True if an extension is one of the supported TypeScript extensions. + * + * @internal + */ export function extensionIsTS(ext: Extension): boolean { return ext === Extension.Ts || ext === Extension.Tsx || ext === Extension.Dts || ext === Extension.Cts || ext === Extension.Mts || ext === Extension.Dmts || ext === Extension.Dcts; } @@ -7795,10 +7917,11 @@ export function resolutionExtensionIsTSOrJson(ext: Extension) { return extensionIsTS(ext) || ext === Extension.Json; } -/** @internal */ /** * Gets the extension from a path. * Path must have a valid extension. + * + * @internal */ export function extensionFromPath(path: string): Extension { const ext = tryGetExtensionFromPath(path); @@ -7827,11 +7950,12 @@ export const emptyFileSystemEntries: FileSystemEntries = { }; -/** @internal */ /** * patternOrStrings contains both patterns (containing "*") and regular strings. * Return an exact match if possible, or a pattern match, or undefined. * (These are verified by verifyCompilerOptions to have 0 or 1 "*" characters.) + * + * @internal */ export function matchPatternOrExact(patternOrStrings: readonly (string | Pattern)[], candidate: string): string | Pattern | undefined { const patterns: Pattern[] = []; @@ -7921,10 +8045,11 @@ export function isJsonEqual(a: unknown, b: unknown): boolean { return a === b || typeof a === "object" && a !== null && typeof b === "object" && b !== null && equalOwnProperties(a as MapLike, b as MapLike, isJsonEqual); } -/** @internal */ /** * Converts a bigint literal string, e.g. `0x1234n`, * to its decimal string representation, e.g. `4660`. + * + * @internal */ export function parsePseudoBigInt(stringValue: string): string { let log2Base: number; @@ -8060,8 +8185,9 @@ export function arrayIsHomogeneous(array: readonly T[], comparer: EqualityCom /** * Bypasses immutability and directly sets the `pos` property of a `TextRange` or `Node`. + * + * @internal */ -/* @internal */ export function setTextRangePos(range: T, pos: number) { (range as TextRange).pos = pos; return range; @@ -8069,8 +8195,9 @@ export function setTextRangePos(range: T, pos: numb /** * Bypasses immutability and directly sets the `end` property of a `TextRange` or `Node`. + * + * @internal */ -/* @internal */ export function setTextRangeEnd(range: T, end: number) { (range as TextRange).end = end; return range; @@ -8078,8 +8205,9 @@ export function setTextRangeEnd(range: T, end: numb /** * Bypasses immutability and directly sets the `pos` and `end` properties of a `TextRange` or `Node`. + * + * @internal */ -/* @internal */ export function setTextRangePosEnd(range: T, pos: number, end: number) { return setTextRangeEnd(setTextRangePos(range, pos), end); } @@ -8087,18 +8215,20 @@ export function setTextRangePosEnd(range: T, pos: n /** * Bypasses immutability and directly sets the `pos` and `end` properties of a `TextRange` or `Node` from the * provided position and width. + * + * @internal */ -/* @internal */ export function setTextRangePosWidth(range: T, pos: number, width: number) { return setTextRangePosEnd(range, pos, pos + width); } /** * Bypasses immutability and directly sets the `flags` property of a `Node`. + * + * @internal */ -/* @internal */ export function setNodeFlags(node: T, newFlags: NodeFlags): T; -/* @internal */ +/** @internal */ export function setNodeFlags(node: T | undefined, newFlags: NodeFlags): T | undefined; /** @internal */ export function setNodeFlags(node: T | undefined, newFlags: NodeFlags): T | undefined { @@ -8110,10 +8240,11 @@ export function setNodeFlags(node: T | undefined, newFlags: Node /** * Bypasses immutability and directly sets the `parent` property of a `Node`. + * + * @internal */ -/* @internal */ export function setParent(child: T, parent: T["parent"] | undefined): T; -/* @internal */ +/** @internal */ export function setParent(child: T | undefined, parent: T["parent"] | undefined): T | undefined; /** @internal */ export function setParent(child: T | undefined, parent: T["parent"] | undefined): T | undefined { @@ -8125,10 +8256,11 @@ export function setParent(child: T | undefined, parent: T["paren /** * Bypasses immutability and directly sets the `parent` property of each `Node` in an array of nodes, if is not already set. + * + * @internal */ -/* @internal */ export function setEachParent(children: T, parent: T[number]["parent"]): T; -/* @internal */ +/** @internal */ export function setEachParent(children: T | undefined, parent: T[number]["parent"]): T | undefined; /** @internal */ export function setEachParent(children: T | undefined, parent: T[number]["parent"]): T | undefined { @@ -8145,10 +8277,11 @@ export function setEachParent(children: T | undefined * @param rootNode The root node from which to start the recursion. * @param incremental When `true`, only recursively descends through nodes whose `parent` pointers are incorrect. * This allows us to quickly bail out of setting `parent` for subtrees during incremental parsing. + * + * @internal */ -/* @internal */ export function setParentRecursive(rootNode: T, incremental: boolean): T; -/* @internal */ +/** @internal */ export function setParentRecursive(rootNode: T | undefined, incremental: boolean): T | undefined; /** @internal */ export function setParentRecursive(rootNode: T | undefined, incremental: boolean): T | undefined { @@ -8181,19 +8314,21 @@ function isPackedElement(node: Expression) { return !isOmittedExpression(node); } -/** @internal */ /** * Determines whether the provided node is an ArrayLiteralExpression that contains no missing elements. + * + * @internal */ export function isPackedArrayLiteral(node: Expression) { return isArrayLiteralExpression(node) && every(node.elements, isPackedElement); } -/** @internal */ /** * Indicates whether the result of an `Expression` will be unused. * * NOTE: This requires a node with a valid `parent` pointer. + * + * @internal */ export function expressionResultIsUnused(node: Expression): boolean { Debug.assertIsDefined(node.parent); @@ -8325,7 +8460,7 @@ export function hasContextSensitiveParameters(node: FunctionLikeDeclaration) { return false; } -/* @internal */ +/** @internal */ export function isInfinityOrNaNString(name: string | __String): boolean { return name === "Infinity" || name === "-Infinity" || name === "NaN"; } diff --git a/src/compiler/utilitiesPublic.ts b/src/compiler/utilitiesPublic.ts index 2cc80ba8d2a82..03b172fa3e7f2 100644 --- a/src/compiler/utilitiesPublic.ts +++ b/src/compiler/utilitiesPublic.ts @@ -96,7 +96,7 @@ export function textSpanContainsPosition(span: TextSpan, position: number) { return position >= span.start && position < textSpanEnd(span); } -/* @internal */ +/** @internal */ export function textRangeContainsPositionInclusive(span: TextRange, position: number): boolean { return position >= span.pos && position <= span.end; } @@ -355,7 +355,7 @@ export function getCombinedModifierFlags(node: Declaration): ModifierFlags { return getCombinedFlags(node, getEffectiveModifierFlags); } -/* @internal */ +/** @internal */ export function getCombinedNodeFlagsAlwaysIncludeJSDoc(node: Declaration): ModifierFlags { return getCombinedFlags(node, getEffectiveModifierFlagsAlwaysIncludeJSDoc); } @@ -371,7 +371,7 @@ export function getCombinedNodeFlags(node: Node): NodeFlags { return getCombinedFlags(node, n => n.flags); } -/* @internal */ +/** @internal */ export const supportedLocaleDirectories = ["cs", "de", "es", "fr", "it", "ja", "ko", "pl", "pt-br", "ru", "tr", "zh-cn", "zh-tw"]; /** @@ -673,7 +673,7 @@ export function getNameOfDeclaration(declaration: Declaration | Expression | und (isFunctionExpression(declaration) || isArrowFunction(declaration) || isClassExpression(declaration) ? getAssignedName(declaration) : undefined); } -/*@internal*/ +/** @internal */ export function getAssignedName(node: Node): DeclarationName | undefined { if (!node.parent) { return undefined; @@ -741,7 +741,7 @@ export function getJSDocParameterTags(param: ParameterDeclaration): readonly JSD return getJSDocParameterTagsWorker(param, /*noCache*/ false); } -/* @internal */ +/** @internal */ export function getJSDocParameterTagsNoCache(param: ParameterDeclaration): readonly JSDocParameterTag[] { return getJSDocParameterTagsWorker(param, /*noCache*/ true); } @@ -766,7 +766,7 @@ export function getJSDocTypeParameterTags(param: TypeParameterDeclaration): read return getJSDocTypeParameterTagsWorker(param, /*noCache*/ false); } -/* @internal */ +/** @internal */ export function getJSDocTypeParameterTagsNoCache(param: TypeParameterDeclaration): readonly JSDocTemplateTag[] { return getJSDocTypeParameterTagsWorker(param, /*noCache*/ true); } @@ -801,7 +801,7 @@ export function getJSDocPublicTag(node: Node): JSDocPublicTag | undefined { return getFirstJSDocTag(node, isJSDocPublicTag); } -/*@internal*/ +/** @internal */ export function getJSDocPublicTagNoCache(node: Node): JSDocPublicTag | undefined { return getFirstJSDocTag(node, isJSDocPublicTag, /*noCache*/ true); } @@ -811,7 +811,7 @@ export function getJSDocPrivateTag(node: Node): JSDocPrivateTag | undefined { return getFirstJSDocTag(node, isJSDocPrivateTag); } -/*@internal*/ +/** @internal */ export function getJSDocPrivateTagNoCache(node: Node): JSDocPrivateTag | undefined { return getFirstJSDocTag(node, isJSDocPrivateTag, /*noCache*/ true); } @@ -821,7 +821,7 @@ export function getJSDocProtectedTag(node: Node): JSDocProtectedTag | undefined return getFirstJSDocTag(node, isJSDocProtectedTag); } -/*@internal*/ +/** @internal */ export function getJSDocProtectedTagNoCache(node: Node): JSDocProtectedTag | undefined { return getFirstJSDocTag(node, isJSDocProtectedTag, /*noCache*/ true); } @@ -831,7 +831,7 @@ export function getJSDocReadonlyTag(node: Node): JSDocReadonlyTag | undefined { return getFirstJSDocTag(node, isJSDocReadonlyTag); } -/*@internal*/ +/** @internal */ export function getJSDocReadonlyTagNoCache(node: Node): JSDocReadonlyTag | undefined { return getFirstJSDocTag(node, isJSDocReadonlyTag, /*noCache*/ true); } @@ -845,7 +845,7 @@ export function getJSDocDeprecatedTag(node: Node): JSDocDeprecatedTag | undefine return getFirstJSDocTag(node, isJSDocDeprecatedTag); } -/*@internal */ +/** @internal */ export function getJSDocDeprecatedTagNoCache(node: Node): JSDocDeprecatedTag | undefined { return getFirstJSDocTag(node, isJSDocDeprecatedTag, /*noCache*/ true); } @@ -943,7 +943,7 @@ export function getJSDocTags(node: Node): readonly JSDocTag[] { return getJSDocTagsWorker(node, /*noCache*/ false); } -/* @internal */ +/** @internal */ export function getJSDocTagsNoCache(node: Node): readonly JSDocTag[] { return getJSDocTagsWorker(node, /*noCache*/ true); } @@ -1027,7 +1027,7 @@ export function isMemberName(node: Node): node is MemberName { return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier; } -/* @internal */ +/** @internal */ export function isGetOrSetAccessorDeclaration(node: Node): node is AccessorDeclaration { return node.kind === SyntaxKind.SetAccessor || node.kind === SyntaxKind.GetAccessor; } @@ -1053,15 +1053,16 @@ export function isOptionalChain(node: Node): node is PropertyAccessChain | Eleme || kind === SyntaxKind.NonNullExpression); } -/* @internal */ +/** @internal */ export function isOptionalChainRoot(node: Node): node is OptionalChainRoot { return isOptionalChain(node) && !isNonNullExpression(node) && !!node.questionDotToken; } /** * Determines whether a node is the expression preceding an optional chain (i.e. `a` in `a?.b`). + * + * @internal */ -/* @internal */ export function isExpressionOfOptionalChainRoot(node: Node): node is Expression & { parent: OptionalChainRoot } { return isOptionalChainRoot(node.parent) && node.parent.expression === node; } @@ -1076,8 +1077,9 @@ export function isExpressionOfOptionalChainRoot(node: Node): node is Expression * the end of the chain starting at `c?.`) * 5. For `a?.(b?.c).d`, both `b?.c` and `a?.(b?.c)d` are outermost (`c` is the end of the chain starting at `b`, and `d` is * the end of the chain starting at `a?.`) + * + * @internal */ -/* @internal */ export function isOutermostOptionalChain(node: OptionalChain) { return !isOptionalChain(node.parent) // cases 1, 2, and 3 || isOptionalChainRoot(node.parent) // case 4 @@ -1138,12 +1140,12 @@ export function isJSDocPropertyLikeTag(node: Node): node is JSDocPropertyLikeTag // // All node tests in the following list should *not* reference parent pointers so that // they may be used with transformations. -/* @internal */ +/** @internal */ export function isNode(node: Node) { return isNodeKind(node.kind); } -/* @internal */ +/** @internal */ export function isNodeKind(kind: SyntaxKind) { return kind >= SyntaxKind.FirstNode; } @@ -1168,14 +1170,14 @@ export function isToken(n: Node): boolean { // Node Arrays -/* @internal */ +/** @internal */ export function isNodeArray(array: readonly T[]): array is NodeArray { return hasProperty(array, "pos") && hasProperty(array, "end"); } // Literals -/* @internal */ +/** @internal */ export function isLiteralKind(kind: SyntaxKind): kind is LiteralToken["kind"] { return SyntaxKind.FirstLiteralToken <= kind && kind <= SyntaxKind.LastLiteralToken; } @@ -1199,7 +1201,7 @@ export function isLiteralExpressionOfObject(node: Node) { // Pseudo-literals -/* @internal */ +/** @internal */ export function isTemplateLiteralKind(kind: SyntaxKind): kind is TemplateLiteralToken["kind"] { return SyntaxKind.FirstTemplateToken <= kind && kind <= SyntaxKind.LastTemplateToken; } @@ -1243,30 +1245,30 @@ export function isStringTextContainingNode(node: Node): node is StringLiteral | // Identifiers -/* @internal */ +/** @internal */ export function isGeneratedIdentifier(node: Node): node is GeneratedIdentifier { return isIdentifier(node) && (node.autoGenerateFlags! & GeneratedIdentifierFlags.KindMask) > GeneratedIdentifierFlags.None; } -/* @internal */ +/** @internal */ export function isGeneratedPrivateIdentifier(node: Node): node is GeneratedPrivateIdentifier { return isPrivateIdentifier(node) && (node.autoGenerateFlags! & GeneratedIdentifierFlags.KindMask) > GeneratedIdentifierFlags.None; } // Private Identifiers -/*@internal*/ +/** @internal */ export function isPrivateIdentifierClassElementDeclaration(node: Node): node is PrivateClassElementDeclaration { return (isPropertyDeclaration(node) || isMethodOrAccessor(node)) && isPrivateIdentifier(node.name); } -/*@internal*/ +/** @internal */ export function isPrivateIdentifierPropertyAccessExpression(node: Node): node is PrivateIdentifierPropertyAccessExpression { return isPropertyAccessExpression(node) && isPrivateIdentifier(node.name); } // Keywords -/* @internal */ +/** @internal */ export function isModifierKind(token: SyntaxKind): token is Modifier["kind"] { switch (token) { case SyntaxKind.AbstractKeyword: @@ -1289,12 +1291,12 @@ export function isModifierKind(token: SyntaxKind): token is Modifier["kind"] { return false; } -/* @internal */ +/** @internal */ export function isParameterPropertyModifier(kind: SyntaxKind): boolean { return !!(modifierToFlag(kind) & ModifierFlags.ParameterPropertyModifier); } -/* @internal */ +/** @internal */ export function isClassMemberModifier(idToken: SyntaxKind): boolean { return isParameterPropertyModifier(idToken) || idToken === SyntaxKind.StaticKeyword || @@ -1334,17 +1336,17 @@ export function isFunctionLike(node: Node | undefined): node is SignatureDeclara return !!node && isFunctionLikeKind(node.kind); } -/* @internal */ +/** @internal */ export function isFunctionLikeOrClassStaticBlockDeclaration(node: Node | undefined): node is SignatureDeclaration | ClassStaticBlockDeclaration { return !!node && (isFunctionLikeKind(node.kind) || isClassStaticBlockDeclaration(node)); } -/* @internal */ +/** @internal */ export function isFunctionLikeDeclaration(node: Node): node is FunctionLikeDeclaration { return node && isFunctionLikeDeclarationKind(node.kind); } -/* @internal */ +/** @internal */ export function isBooleanLiteral(node: Node): node is BooleanLiteral { return node.kind === SyntaxKind.TrueKeyword || node.kind === SyntaxKind.FalseKeyword; } @@ -1364,7 +1366,7 @@ function isFunctionLikeDeclarationKind(kind: SyntaxKind): boolean { } } -/* @internal */ +/** @internal */ export function isFunctionLikeKind(kind: SyntaxKind): boolean { switch (kind) { case SyntaxKind.MethodSignature: @@ -1381,7 +1383,7 @@ export function isFunctionLikeKind(kind: SyntaxKind): boolean { } } -/* @internal */ +/** @internal */ export function isFunctionOrModuleBlock(node: Node): boolean { return isSourceFile(node) || isModuleBlock(node) || isBlock(node) && isFunctionLike(node.parent); } @@ -1411,7 +1413,7 @@ export function isAutoAccessorPropertyDeclaration(node: Node): node is AutoAcces return isPropertyDeclaration(node) && hasAccessorModifier(node); } -/* @internal */ +/** @internal */ export function isMethodOrAccessor(node: Node): node is MethodDeclaration | AccessorDeclaration { switch (node.kind) { case SyntaxKind.MethodDeclaration: @@ -1423,7 +1425,7 @@ export function isMethodOrAccessor(node: Node): node is MethodDeclaration | Acce } } -/* @internal */ +/** @internal */ export function isNamedClassElement(node: Node): node is MethodDeclaration | AccessorDeclaration | PropertyDeclaration { switch (node.kind) { case SyntaxKind.MethodDeclaration: @@ -1490,7 +1492,7 @@ export function isFunctionOrConstructorTypeNode(node: Node): node is FunctionTyp // Binding patterns -/* @internal */ +/** @internal */ export function isBindingPattern(node: Node | undefined): node is BindingPattern { if (node) { const kind = node.kind; @@ -1501,7 +1503,7 @@ export function isBindingPattern(node: Node | undefined): node is BindingPattern return false; } -/* @internal */ +/** @internal */ export function isAssignmentPattern(node: Node): node is AssignmentPattern { const kind = node.kind; return kind === SyntaxKind.ArrayLiteralExpression @@ -1509,7 +1511,7 @@ export function isAssignmentPattern(node: Node): node is AssignmentPattern { } -/* @internal */ +/** @internal */ export function isArrayBindingElement(node: Node): node is ArrayBindingElement { const kind = node.kind; return kind === SyntaxKind.BindingElement @@ -1519,8 +1521,9 @@ export function isArrayBindingElement(node: Node): node is ArrayBindingElement { /** * Determines whether the BindingOrAssignmentElement is a BindingElement-like declaration + * + * @internal */ -/* @internal */ export function isDeclarationBindingElement(bindingElement: BindingOrAssignmentElement): bindingElement is VariableDeclaration | ParameterDeclaration | BindingElement { switch (bindingElement.kind) { case SyntaxKind.VariableDeclaration: @@ -1534,8 +1537,9 @@ export function isDeclarationBindingElement(bindingElement: BindingOrAssignmentE /** * Determines whether a node is a BindingOrAssignmentPattern + * + * @internal */ -/* @internal */ export function isBindingOrAssignmentPattern(node: BindingOrAssignmentElementTarget): node is BindingOrAssignmentPattern { return isObjectBindingOrAssignmentPattern(node) || isArrayBindingOrAssignmentPattern(node); @@ -1543,8 +1547,9 @@ export function isBindingOrAssignmentPattern(node: BindingOrAssignmentElementTar /** * Determines whether a node is an ObjectBindingOrAssignmentPattern + * + * @internal */ -/* @internal */ export function isObjectBindingOrAssignmentPattern(node: BindingOrAssignmentElementTarget): node is ObjectBindingOrAssignmentPattern { switch (node.kind) { case SyntaxKind.ObjectBindingPattern: @@ -1555,7 +1560,7 @@ export function isObjectBindingOrAssignmentPattern(node: BindingOrAssignmentElem return false; } -/* @internal */ +/** @internal */ export function isObjectBindingOrAssignmentElement(node: Node): node is ObjectBindingOrAssignmentElement { switch (node.kind) { case SyntaxKind.BindingElement: @@ -1569,8 +1574,9 @@ export function isObjectBindingOrAssignmentElement(node: Node): node is ObjectBi /** * Determines whether a node is an ArrayBindingOrAssignmentPattern + * + * @internal */ -/* @internal */ export function isArrayBindingOrAssignmentPattern(node: BindingOrAssignmentElementTarget): node is ArrayBindingOrAssignmentPattern { switch (node.kind) { case SyntaxKind.ArrayBindingPattern: @@ -1581,7 +1587,7 @@ export function isArrayBindingOrAssignmentPattern(node: BindingOrAssignmentEleme return false; } -/* @internal */ +/** @internal */ export function isPropertyAccessOrQualifiedNameOrImportTypeNode(node: Node): node is PropertyAccessExpression | QualifiedName | ImportTypeNode { const kind = node.kind; return kind === SyntaxKind.PropertyAccessExpression @@ -1621,7 +1627,7 @@ export function isTemplateLiteral(node: Node): node is TemplateLiteral { || kind === SyntaxKind.NoSubstitutionTemplateLiteral; } -/* @internal */ +/** @internal */ export function isLeftHandSideExpression(node: Node): node is LeftHandSideExpression { return isLeftHandSideExpressionKind(skipPartiallyEmittedExpressions(node).kind); } @@ -1664,7 +1670,7 @@ function isLeftHandSideExpressionKind(kind: SyntaxKind): boolean { } } -/* @internal */ +/** @internal */ export function isUnaryExpression(node: Node): node is UnaryExpression { return isUnaryExpressionKind(skipPartiallyEmittedExpressions(node).kind); } @@ -1684,7 +1690,7 @@ function isUnaryExpressionKind(kind: SyntaxKind): boolean { } } -/* @internal */ +/** @internal */ export function isUnaryExpressionWithWrite(expr: Node): expr is PrefixUnaryExpression | PostfixUnaryExpression { switch (expr.kind) { case SyntaxKind.PostfixUnaryExpression: @@ -1697,10 +1703,11 @@ export function isUnaryExpressionWithWrite(expr: Node): expr is PrefixUnaryExpre } } -/* @internal */ /** * Determines whether a node is an expression based only on its kind. * Use `isExpressionNode` if not in transforms. + * + * @internal */ export function isExpression(node: Node): node is Expression { return isExpressionKind(skipPartiallyEmittedExpressions(node).kind); @@ -1730,7 +1737,7 @@ export function isAssertionExpression(node: Node): node is AssertionExpression { || kind === SyntaxKind.AsExpression; } -/* @internal */ +/** @internal */ export function isNotEmittedOrPartiallyEmittedNode(node: Node): node is NotEmittedStatement | PartiallyEmittedExpression { return isNotEmittedStatement(node) || isPartiallyEmittedExpression(node); @@ -1755,52 +1762,52 @@ export function isIterationStatement(node: Node, lookInLabeledStatements: boolea return false; } -/* @internal */ +/** @internal */ export function isScopeMarker(node: Node) { return isExportAssignment(node) || isExportDeclaration(node); } -/* @internal */ +/** @internal */ export function hasScopeMarker(statements: readonly Statement[]) { return some(statements, isScopeMarker); } -/* @internal */ +/** @internal */ export function needsScopeMarker(result: Statement) { return !isAnyImportOrReExport(result) && !isExportAssignment(result) && !hasSyntacticModifier(result, ModifierFlags.Export) && !isAmbientModule(result); } -/* @internal */ +/** @internal */ export function isExternalModuleIndicator(result: Statement) { // Exported top-level member indicates moduleness return isAnyImportOrReExport(result) || isExportAssignment(result) || hasSyntacticModifier(result, ModifierFlags.Export); } -/* @internal */ +/** @internal */ export function isForInOrOfStatement(node: Node): node is ForInOrOfStatement { return node.kind === SyntaxKind.ForInStatement || node.kind === SyntaxKind.ForOfStatement; } // Element -/* @internal */ +/** @internal */ export function isConciseBody(node: Node): node is ConciseBody { return isBlock(node) || isExpression(node); } -/* @internal */ +/** @internal */ export function isFunctionBody(node: Node): node is FunctionBody { return isBlock(node); } -/* @internal */ +/** @internal */ export function isForInitializer(node: Node): node is ForInitializer { return isVariableDeclarationList(node) || isExpression(node); } -/* @internal */ +/** @internal */ export function isModuleBody(node: Node): node is ModuleBody { const kind = node.kind; return kind === SyntaxKind.ModuleBlock @@ -1808,28 +1815,28 @@ export function isModuleBody(node: Node): node is ModuleBody { || kind === SyntaxKind.Identifier; } -/* @internal */ +/** @internal */ export function isNamespaceBody(node: Node): node is NamespaceBody { const kind = node.kind; return kind === SyntaxKind.ModuleBlock || kind === SyntaxKind.ModuleDeclaration; } -/* @internal */ +/** @internal */ export function isJSDocNamespaceBody(node: Node): node is JSDocNamespaceBody { const kind = node.kind; return kind === SyntaxKind.Identifier || kind === SyntaxKind.ModuleDeclaration; } -/* @internal */ +/** @internal */ export function isNamedImportBindings(node: Node): node is NamedImportBindings { const kind = node.kind; return kind === SyntaxKind.NamedImports || kind === SyntaxKind.NamespaceImport; } -/* @internal */ +/** @internal */ export function isModuleOrEnumDeclaration(node: Node): node is ModuleDeclaration | EnumDeclaration { return node.kind === SyntaxKind.ModuleDeclaration || node.kind === SyntaxKind.EnumDeclaration; } @@ -1911,7 +1918,7 @@ function isStatementKindButNotDeclarationKind(kind: SyntaxKind) { || kind === SyntaxKind.MergeDeclarationMarker; } -/* @internal */ +/** @internal */ export function isDeclaration(node: Node): node is NamedDeclaration { if (node.kind === SyntaxKind.TypeParameter) { return (node.parent && node.parent.kind !== SyntaxKind.JSDocTemplateTag) || isInJSFile(node); @@ -1920,20 +1927,21 @@ export function isDeclaration(node: Node): node is NamedDeclaration { return isDeclarationKind(node.kind); } -/* @internal */ +/** @internal */ export function isDeclarationStatement(node: Node): node is DeclarationStatement { return isDeclarationStatementKind(node.kind); } /** * Determines whether the node is a statement that is not also a declaration + * + * @internal */ -/* @internal */ export function isStatementButNotDeclaration(node: Node): node is Statement { return isStatementKindButNotDeclarationKind(node.kind); } -/* @internal */ +/** @internal */ export function isStatement(node: Node): node is Statement { const kind = node.kind; return isStatementKindButNotDeclarationKind(kind) @@ -1953,8 +1961,9 @@ function isBlockStatement(node: Node): node is Block { /** * NOTE: This is similar to `isStatement` but does not access parent pointers. + * + * @internal */ -/* @internal */ export function isStatementOrBlock(node: Node): node is Statement | Block { const kind = node.kind; return isStatementKindButNotDeclarationKind(kind) @@ -1964,7 +1973,7 @@ export function isStatementOrBlock(node: Node): node is Statement | Block { // Module references -/* @internal */ +/** @internal */ export function isModuleReference(node: Node): node is ModuleReference { const kind = node.kind; return kind === SyntaxKind.ExternalModuleReference @@ -1974,7 +1983,7 @@ export function isModuleReference(node: Node): node is ModuleReference { // JSX -/* @internal */ +/** @internal */ export function isJsxTagNameExpression(node: Node): node is JsxTagNameExpression { const kind = node.kind; return kind === SyntaxKind.ThisKeyword @@ -1982,7 +1991,7 @@ export function isJsxTagNameExpression(node: Node): node is JsxTagNameExpression || kind === SyntaxKind.PropertyAccessExpression; } -/* @internal */ +/** @internal */ export function isJsxChild(node: Node): node is JsxChild { const kind = node.kind; return kind === SyntaxKind.JsxElement @@ -1992,14 +2001,14 @@ export function isJsxChild(node: Node): node is JsxChild { || kind === SyntaxKind.JsxFragment; } -/* @internal */ +/** @internal */ export function isJsxAttributeLike(node: Node): node is JsxAttributeLike { const kind = node.kind; return kind === SyntaxKind.JsxAttribute || kind === SyntaxKind.JsxSpreadAttribute; } -/* @internal */ +/** @internal */ export function isStringLiteralOrJsxExpression(node: Node): node is StringLiteral | JsxExpression { const kind = node.kind; return kind === SyntaxKind.StringLiteral @@ -2022,8 +2031,11 @@ export function isCaseOrDefaultClause(node: Node): node is CaseOrDefaultClause { // JSDoc -/** True if node is of some JSDoc syntax kind. */ -/* @internal */ +/** + * True if node is of some JSDoc syntax kind. + * + * @internal + */ export function isJSDocNode(node: Node): boolean { return node.kind >= SyntaxKind.FirstJSDocNode && node.kind <= SyntaxKind.LastJSDocNode; } @@ -2040,7 +2052,7 @@ export function isJSDocCommentContainingNode(node: Node): boolean { } // TODO: determine what this does before making it public. -/* @internal */ +/** @internal */ export function isJSDocTag(node: Node): node is JSDocTag { return node.kind >= SyntaxKind.FirstJSDocTagNode && node.kind <= SyntaxKind.LastJSDocTagNode; } @@ -2053,22 +2065,31 @@ export function isGetAccessor(node: Node): node is GetAccessorDeclaration { return node.kind === SyntaxKind.GetAccessor; } -/** True if has jsdoc nodes attached to it. */ -/* @internal */ +/** + * True if has jsdoc nodes attached to it. + * + * @internal + */ // TODO: GH#19856 Would like to return `node is Node & { jsDoc: JSDoc[] }` but it causes long compile times export function hasJSDocNodes(node: Node): node is HasJSDoc { const { jsDoc } = node as JSDocContainer; return !!jsDoc && jsDoc.length > 0; } -/** True if has type node attached to it. */ -/* @internal */ +/** + * True if has type node attached to it. + * + * @internal + */ export function hasType(node: Node): node is HasType { return !!(node as HasType).type; } -/** True if has initializer node attached to it. */ -/* @internal */ +/** + * True if has initializer node attached to it. + * + * @internal + */ export function hasInitializer(node: Node): node is HasInitializer { return !!(node as HasInitializer).initializer; } @@ -2092,13 +2113,13 @@ export function isObjectLiteralElement(node: Node): node is ObjectLiteralElement return node.kind === SyntaxKind.JsxAttribute || node.kind === SyntaxKind.JsxSpreadAttribute || isObjectLiteralElementLike(node); } -/* @internal */ +/** @internal */ export function isTypeReferenceType(node: Node): node is TypeReferenceType { return node.kind === SyntaxKind.TypeReference || node.kind === SyntaxKind.ExpressionWithTypeArguments; } const MAX_SMI_X86 = 0x3fff_ffff; -/* @internal */ +/** @internal */ export function guessIndentation(lines: string[]) { let indentation = MAX_SMI_X86; for (const line of lines) { diff --git a/src/compiler/visitorPublic.ts b/src/compiler/visitorPublic.ts index 3dcb96b072d58..2f22a76e0e2d1 100644 --- a/src/compiler/visitorPublic.ts +++ b/src/compiler/visitorPublic.ts @@ -64,7 +64,7 @@ export function visitNode(node: T | undefined, visitor: Visitor return visitedNode as T; } -/* @internal */ +/** @internal */ export function visitNodes(nodes: NodeArray, visitor: Visitor, test: (node: Node) => node is U, start?: number, count?: number): NodeArray; /** @@ -78,7 +78,7 @@ export function visitNodes(nodes: NodeArray, vis */ export function visitNodes(nodes: NodeArray, visitor: Visitor | undefined, test?: (node: Node) => boolean, start?: number, count?: number): NodeArray; -/* @internal */ +/** @internal */ export function visitNodes(nodes: NodeArray | undefined, visitor: Visitor, test: (node: Node) => node is U, start?: number, count?: number): NodeArray | undefined; /** @@ -141,13 +141,13 @@ export function visitNodes(nodes: NodeArray | undefined, visi return nodes; } -/* @internal */ +/** @internal */ export function visitArray(nodes: T[] | undefined, visitor: Visitor, test: (node: Node) => node is U, start?: number, count?: number): U[] | undefined; -/* @internal */ +/** @internal */ export function visitArray(nodes: readonly T[] | undefined, visitor: Visitor, test: (node: Node) => node is U, start?: number, count?: number): readonly U[] | undefined; -/* @internal */ +/** @internal */ export function visitArray(nodes: T[] | undefined, visitor: Visitor, test: (node: Node) => node is T, start?: number, count?: number): T[] | undefined; -/* @internal */ +/** @internal */ export function visitArray(nodes: readonly T[] | undefined, visitor: Visitor, test: (node: Node) => node is T, start?: number, count?: number): readonly T[] | undefined; export function visitArray(nodes: readonly T[] | undefined, visitor: Visitor, test: (node: Node) => node is U, start?: number, count?: number) { if (nodes === undefined) { @@ -167,7 +167,7 @@ export function visitArray(nodes: readonly T[] | un return visitArrayWorker(nodes, visitor, test, start, count) as readonly U[]; } -/* @internal */ +/** @internal */ function visitArrayWorker(nodes: readonly T[], visitor: Visitor, test: ((node: Node) => boolean) | undefined, start: number, count: number): readonly T[] | undefined { let updated: T[] | undefined; @@ -355,9 +355,9 @@ export function visitFunctionBody(node: FunctionBody | undefined, visitor: Visit * environment and merging hoisted declarations upon completion. */ export function visitFunctionBody(node: ConciseBody, visitor: Visitor, context: TransformationContext): ConciseBody; -/* @internal*/ export function visitFunctionBody(node: FunctionBody, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): FunctionBody; // eslint-disable-line @typescript-eslint/unified-signatures -/* @internal*/ export function visitFunctionBody(node: FunctionBody | undefined, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): FunctionBody | undefined; // eslint-disable-line @typescript-eslint/unified-signatures -/* @internal*/ export function visitFunctionBody(node: ConciseBody, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): ConciseBody; // eslint-disable-line @typescript-eslint/unified-signatures +/** @internal */ export function visitFunctionBody(node: FunctionBody, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): FunctionBody; // eslint-disable-line @typescript-eslint/unified-signatures +/** @internal */ export function visitFunctionBody(node: FunctionBody | undefined, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): FunctionBody | undefined; // eslint-disable-line @typescript-eslint/unified-signatures +/** @internal */ export function visitFunctionBody(node: ConciseBody, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): ConciseBody; // eslint-disable-line @typescript-eslint/unified-signatures export function visitFunctionBody(node: ConciseBody | undefined, visitor: Visitor, context: TransformationContext, nodeVisitor: NodeVisitor = visitNode): ConciseBody | undefined { context.resumeLexicalEnvironment(); const updated = nodeVisitor(node, visitor, isConciseBody); @@ -377,7 +377,7 @@ export function visitFunctionBody(node: ConciseBody | undefined, visitor: Visito * Visits an iteration body, adding any block-scoped variables required by the transformation. */ export function visitIterationBody(body: Statement, visitor: Visitor, context: TransformationContext): Statement; -/* @internal */ +/** @internal */ export function visitIterationBody(body: Statement, visitor: Visitor, context: TransformationContext, nodeVisitor?: NodeVisitor): Statement; // eslint-disable-line @typescript-eslint/unified-signatures export function visitIterationBody(body: Statement, visitor: Visitor, context: TransformationContext, nodeVisitor: NodeVisitor = visitNode): Statement { context.startBlockScope(); @@ -402,7 +402,7 @@ export function visitIterationBody(body: Statement, visitor: Visitor, context: T * @param context A lexical environment context for the visitor. */ export function visitEachChild(node: T, visitor: Visitor, context: TransformationContext): T; -/* @internal */ +/** @internal */ export function visitEachChild(node: T, visitor: Visitor, context: TransformationContext, nodesVisitor?: NodesVisitor, tokenVisitor?: Visitor, nodeVisitor?: NodeVisitor): T; // eslint-disable-line @typescript-eslint/unified-signatures /** * Visits each child of a Node using the supplied visitor, possibly returning a new Node of the same kind in its place. @@ -412,7 +412,7 @@ export function visitEachChild(node: T, visitor: Visitor, contex * @param context A lexical environment context for the visitor. */ export function visitEachChild(node: T | undefined, visitor: Visitor, context: TransformationContext, nodesVisitor?: typeof visitNodes, tokenVisitor?: Visitor): T | undefined; -/* @internal */ +/** @internal */ export function visitEachChild(node: T | undefined, visitor: Visitor, context: TransformationContext, nodesVisitor?: NodesVisitor, tokenVisitor?: Visitor, nodeVisitor?: NodeVisitor): T | undefined; // eslint-disable-line @typescript-eslint/unified-signatures export function visitEachChild(node: T | undefined, visitor: Visitor, context: TransformationContext, nodesVisitor = visitNodes, tokenVisitor?: Visitor, nodeVisitor: NodeVisitor = visitNode): T | undefined { if (node === undefined) { diff --git a/src/compiler/watch.ts b/src/compiler/watch.ts index f85cbae8c6cb1..7fe6d38208f15 100644 --- a/src/compiler/watch.ts +++ b/src/compiler/watch.ts @@ -27,9 +27,10 @@ const sysFormatDiagnosticsHost: FormatDiagnosticsHost | undefined = sys ? { getCanonicalFileName: createGetCanonicalFileName(sys.useCaseSensitiveFileNames) } : undefined; -/** @internal */ /** * Create a function that reports error by writing to the system and handles the formatting of the diagnostic + * + * @internal */ export function createDiagnosticReporter(system: System, pretty?: boolean): DiagnosticReporter { const host: FormatDiagnosticsHost = system === sys && sysFormatDiagnosticsHost ? sysFormatDiagnosticsHost : { @@ -77,9 +78,10 @@ function getPlainDiagnosticFollowingNewLines(diagnostic: Diagnostic, newLine: st : newLine; } -/** @internal */ /** * Get locale specific time based on whether we are in test mode + * + * @internal */ export function getLocaleTimeString(system: System) { return !system.now ? @@ -87,9 +89,10 @@ export function getLocaleTimeString(system: System) { system.now().toLocaleTimeString("en-US", { timeZone: "UTC" }); } -/** @internal */ /** * Create a function that reports watch status by writing to the system and handles the formatting of the diagnostic + * + * @internal */ export function createWatchStatusReporter(system: System, pretty?: boolean): WatchStatusReporter { return pretty ? @@ -113,8 +116,11 @@ export function createWatchStatusReporter(system: System, pretty?: boolean): Wat }; } -/** @internal */ -/** Parses config file using System interface */ +/** + * Parses config file using System interface + * + * @internal + */ export function parseConfigFileWithSystem(configFileName: string, optionsToExtend: CompilerOptions, extendedConfigCache: Map | undefined, watchOptionsToExtend: WatchOptions | undefined, system: System, reportDiagnostic: DiagnosticReporter) { const host: ParseConfigFileHost = system as any; host.onUnRecoverableConfigFileDiagnostic = diagnostic => reportUnrecoverableDiagnostic(system, reportDiagnostic, diagnostic); @@ -461,9 +467,10 @@ function toFileName(file: SourceFile | string, fileNameConvertor?: (fileName: st return fileNameConvertor ? fileNameConvertor(fileName) : fileName; } -/** @internal */ /** * Helper that emit files, report diagnostics and lists emitted and/or source files depending on compiler options + * + * @internal */ export function emitFilesAndReportErrors( program: Program | T, @@ -724,9 +731,10 @@ export function setGetSourceFileAsHashVersioned(compilerHost: CompilerHost, host }; } -/** @internal */ /** * Creates the watch compiler host that can be extended with config file or root file names and options host + * + * @internal */ export function createProgramHost(system: System, createProgram: CreateProgram | undefined): ProgramHost { const getDefaultLibLocation = memoize(() => getDirectoryPath(normalizePath(system.getExecutingFilePath()))); @@ -803,9 +811,10 @@ export interface CreateWatchCompilerHostOfConfigFileInput({ configFileName, optionsToExtend, watchOptionsToExtend, extraFileExtensions, @@ -828,9 +837,10 @@ export interface CreateWatchCompilerHostOfFilesAndCompilerOptionsInput({ rootFiles, options, watchOptions, projectReferences, diff --git a/src/compiler/watchPublic.ts b/src/compiler/watchPublic.ts index ee6f018f37135..6762477e51c16 100644 --- a/src/compiler/watchPublic.ts +++ b/src/compiler/watchPublic.ts @@ -26,7 +26,7 @@ export interface ReadBuildProgramHost { useCaseSensitiveFileNames(): boolean; getCurrentDirectory(): string; readFile(fileName: string): string | undefined; - /*@internal*/ + /** @internal */ getBuildInfo?(fileName: string, configFilePath: string | undefined): BuildInfo | undefined; } export function readBuilderProgram(compilerOptions: CompilerOptions, host: ReadBuildProgramHost) { @@ -142,9 +142,11 @@ export interface ProgramHost { */ getModuleResolutionCache?(): ModuleResolutionCache | undefined; } -/** Internal interface used to wire emit through same host */ - -/*@internal*/ +/** + * Internal interface used to wire emit through same host + * + * @internal + */ export interface ProgramHost { // TODO: GH#18217 Optional methods are frequently asserted createDirectory?(path: string): void; @@ -205,8 +207,9 @@ export interface WatchCompilerHostOfConfigFile extends /** * Host to create watch with config file that is already parsed (from tsc) + * + * @internal */ -/*@internal*/ export interface WatchCompilerHostOfConfigFile extends WatchCompilerHost { configFileParsingResult?: ParsedCommandLine; extendedConfigCache?: Map; @@ -215,8 +218,11 @@ export interface WatchCompilerHostOfConfigFile extends export interface Watch { /** Synchronize with host and get updated program */ getProgram(): T; - /** Gets the existing program without synchronizing with changes on host */ - /*@internal*/ + /** + * Gets the existing program without synchronizing with changes on host + * + * @internal + */ getCurrentProgram(): T; /** Closes the watch */ close(): void; diff --git a/src/compiler/watchUtilities.ts b/src/compiler/watchUtilities.ts index b5dc7f19dee7e..5dce173af6377 100644 --- a/src/compiler/watchUtilities.ts +++ b/src/compiler/watchUtilities.ts @@ -11,9 +11,10 @@ import { timestamp, WatchDirectoryFlags, WatchFileKind, WatchOptions, } from "./_namespaces/ts"; -/** @internal */ /** * Partial interface of the System thats needed to support the caching of directory structure + * + * @internal */ export interface DirectoryStructureHost { fileExists(path: string): boolean; @@ -332,9 +333,10 @@ export interface SharedExtendedConfigFileWatcher extends FileWatcher { projects: Set; } -/** @internal */ /** * Updates the map of shared extended config file watches with a new set of extended config files from a base config file of the project + * + * @internal */ export function updateSharedExtendedConfigFileWatcher( projectPath: T, @@ -373,9 +375,10 @@ export function updateSharedExtendedConfigFileWatcher( }); } -/** @internal */ /** * Remove the project from the extended config file watchers and close not needed watches + * + * @internal */ export function clearSharedExtendedConfigFileWatcher( projectPath: T, @@ -386,9 +389,10 @@ export function clearSharedExtendedConfigFileWatcher( }); } -/** @internal */ /** * Clean the extendsConfigCache when extended config file has changed + * + * @internal */ export function cleanExtendedConfigCache( extendedConfigCache: ESMap, @@ -403,9 +407,10 @@ export function cleanExtendedConfigCache( }); } -/** @internal */ /** * Updates watchers based on the package json files used in module resolution + * + * @internal */ export function updatePackageJsonWatch( lookups: readonly (readonly [Path, object | boolean])[], @@ -423,9 +428,10 @@ export function updatePackageJsonWatch( ); } -/** @internal */ /** * Updates the existing missing file watches with the new set of missing files after new program is created + * + * @internal */ export function updateMissingFilePathsWatch( program: Program, @@ -455,12 +461,13 @@ export interface WildcardDirectoryWatcher { flags: WatchDirectoryFlags; } -/** @internal */ /** * Updates the existing wild card directory watches with the new set of wild card directories from the config file * after new program is created because the config file was reloaded or program was created first time from the config file * Note that there is no need to call this function when the program is updated with additional files without reloading config files, * as wildcard directories wont change unless reloading config file + * + * @internal */ export function updateWatchingWildcardDirectories( existingWatchedForWildcards: ESMap, @@ -513,7 +520,7 @@ export interface IsIgnoredFileFromWildCardWatchingInput { writeLog: (s: string) => void; toPath: (fileName: string) => Path; } -/* @internal */ +/** @internal */ export function isIgnoredFileFromWildCardWatching({ watchedDirPath, fileOrDirectory, fileOrDirectoryPath, configFileName, options, program, extraFileExtensions, diff --git a/src/debug/dbg.ts b/src/debug/dbg.ts index c165c3e8725d8..202681c34a308 100644 --- a/src/debug/dbg.ts +++ b/src/debug/dbg.ts @@ -515,4 +515,4 @@ export function formatControlFlowGraph(flowNode: FlowNode) { declare const module: { exports: {} }; if (typeof module !== "undefined" && module.exports) { module.exports = Debug; -} \ No newline at end of file +} diff --git a/src/deprecatedCompat/deprecations.ts b/src/deprecatedCompat/deprecations.ts index 8c80005d2f982..d85748d14d292 100644 --- a/src/deprecatedCompat/deprecations.ts +++ b/src/deprecatedCompat/deprecations.ts @@ -106,4 +106,4 @@ export function buildOverload(name: string): OverloadBuilder { }) }) }; -} \ No newline at end of file +} diff --git a/src/harness/client.ts b/src/harness/client.ts index 2ff546d622244..7808709963f86 100644 --- a/src/harness/client.ts +++ b/src/harness/client.ts @@ -29,7 +29,7 @@ interface RenameEntry { readonly locations: RenameLocation[]; } -/* @internal */ +/** @internal */ export function extractMessage(message: string): string { // Read the content length const contentLengthPrefix = "Content-Length: "; @@ -138,7 +138,7 @@ export class SessionClient implements LanguageService { return response; } - /*@internal*/ + /** @internal */ configure(preferences: UserPreferences) { this.preferences = preferences; const args: protocol.ConfigureRequestArguments = { preferences }; @@ -146,14 +146,14 @@ export class SessionClient implements LanguageService { this.processResponse(request, /*expectEmptyBody*/ true); } - /*@internal*/ + /** @internal */ setFormattingOptions(formatOptions: FormatCodeSettings) { const args: protocol.ConfigureRequestArguments = { formatOptions }; const request = this.processRequest(CommandNames.Configure, args); this.processResponse(request, /*expectEmptyBody*/ true); } - /*@internal*/ + /** @internal */ setCompilerOptionsForInferredProjects(options: protocol.CompilerOptions) { const args: protocol.SetCompilerOptionsForInferredProjectsArgs = { options }; const request = this.processRequest(CommandNames.CompilerOptionsForInferredProjects, args); diff --git a/src/jsTyping/jsTyping.ts b/src/jsTyping/jsTyping.ts index bafe1ee954057..0ba0351a503d1 100644 --- a/src/jsTyping/jsTyping.ts +++ b/src/jsTyping/jsTyping.ts @@ -100,9 +100,10 @@ export function nonRelativeModuleNameForTypingCache(moduleName: string) { return nodeCoreModules.has(moduleName) ? "node" : moduleName; } -/** @internal */ /** * A map of loose file names to library names that we are confident require typings + * + * @internal */ export type SafeList = ReadonlyESMap; @@ -121,7 +122,6 @@ export function loadTypesMap(host: TypingResolutionHost, typesMapPath: Path): Sa return undefined; } -/** @internal */ /** * @param host is the object providing I/O related operations. * @param fileNames are the file names that belong to the same project @@ -130,6 +130,8 @@ export function loadTypesMap(host: TypingResolutionHost, typesMapPath: Path): Sa * @param packageNameToTypingLocation is the map of package names to their cached typing locations and installed versions * @param typeAcquisition is used to customize the typing acquisition process * @param compilerOptions are used as a source for typing inference + * + * @internal */ export function discoverTypings( host: TypingResolutionHost, @@ -371,9 +373,10 @@ export interface ScopedPackageNameValidationResult { /** @internal */ export type PackageNameValidationResult = NameValidationResult | ScopedPackageNameValidationResult; -/** @internal */ /** * Validates package name using rules defined at https://docs.npmjs.com/files/package.json + * + * @internal */ export function validatePackageName(packageName: string): PackageNameValidationResult { return validatePackageNameWorker(packageName, /*supportScopedPackage*/ true); diff --git a/src/jsTyping/shared.ts b/src/jsTyping/shared.ts index 2b6282d25f066..f004b0257ad03 100644 --- a/src/jsTyping/shared.ts +++ b/src/jsTyping/shared.ts @@ -7,22 +7,22 @@ export type EventTypesRegistry = "event::typesRegistry"; export type EventBeginInstallTypes = "event::beginInstallTypes"; export type EventEndInstallTypes = "event::endInstallTypes"; export type EventInitializationFailed = "event::initializationFailed"; -/* @internal */ +/** @internal */ export const ActionSet: ActionSet = "action::set"; -/* @internal */ +/** @internal */ export const ActionInvalidate: ActionInvalidate = "action::invalidate"; -/* @internal */ +/** @internal */ export const ActionPackageInstalled: ActionPackageInstalled = "action::packageInstalled"; -/* @internal */ +/** @internal */ export const EventTypesRegistry: EventTypesRegistry = "event::typesRegistry"; -/* @internal */ +/** @internal */ export const EventBeginInstallTypes: EventBeginInstallTypes = "event::beginInstallTypes"; -/* @internal */ +/** @internal */ export const EventEndInstallTypes: EventEndInstallTypes = "event::endInstallTypes"; -/* @internal */ +/** @internal */ export const EventInitializationFailed: EventInitializationFailed = "event::initializationFailed"; -/* @internal */ +/** @internal */ export namespace Arguments { export const GlobalCacheLocation = "--globalTypingsCacheLocation"; export const LogFile = "--logFile"; @@ -41,12 +41,12 @@ export namespace Arguments { export const ValidateDefaultNpmLocation = "--validateDefaultNpmLocation"; } -/* @internal */ +/** @internal */ export function hasArgument(argumentName: string) { return sys.args.indexOf(argumentName) >= 0; } -/* @internal */ +/** @internal */ export function findArgument(argumentName: string): string | undefined { const index = sys.args.indexOf(argumentName); return index >= 0 && index < sys.args.length - 1 @@ -54,7 +54,7 @@ export function findArgument(argumentName: string): string | undefined { : undefined; } -/* @internal */ +/** @internal */ export function nowString() { // E.g. "12:34:56.789" const d = new Date(); diff --git a/src/jsTyping/types.ts b/src/jsTyping/types.ts index 4d948b5b757be..013e32553c6e1 100644 --- a/src/jsTyping/types.ts +++ b/src/jsTyping/types.ts @@ -15,7 +15,7 @@ export interface TypingInstallerRequestWithProjectName { readonly projectName: string; } -/* @internal */ +/** @internal */ export type TypingInstallerRequestUnion = DiscoverTypings | CloseProject | TypesRegistryRequest | InstallPackageRequest; export interface DiscoverTypings extends TypingInstallerRequestWithProjectName { @@ -44,7 +44,7 @@ export interface InstallPackageRequest extends TypingInstallerRequestWithProject readonly projectRootPath: Path; } -/* @internal */ +/** @internal */ export interface TypesRegistryResponse extends TypingInstallerResponse { readonly kind: EventTypesRegistry; readonly typesRegistry: MapLike>; @@ -86,7 +86,7 @@ export interface EndInstallTypes extends InstallTypes { readonly installSuccess: boolean; } -/* @internal */ +/** @internal */ export interface InstallTypingHost extends JsTyping.TypingResolutionHost { useCaseSensitiveFileNames: boolean; writeFile(path: string, content: string): void; @@ -104,5 +104,5 @@ export interface SetTypings extends ProjectResponse { readonly kind: ActionSet; } -/* @internal */ +/** @internal */ export type TypingInstallerResponseUnion = SetTypings | InvalidateCachedTypings | TypesRegistryResponse | PackageInstalledResponse | InstallTypes | InitializationFailedResponse; diff --git a/src/server/editorServices.ts b/src/server/editorServices.ts index b59a533db1aec..1ae9921a3c5f6 100644 --- a/src/server/editorServices.ts +++ b/src/server/editorServices.ts @@ -36,7 +36,7 @@ import { } from "./_namespaces/ts"; export const maxProgramSizeForNonTsFiles = 20 * 1024 * 1024; -/*@internal*/ +/** @internal */ export const maxFileSize = 4 * 1024 * 1024; export const ProjectsUpdatedInBackgroundEvent = "projectsUpdatedInBackground"; @@ -186,7 +186,7 @@ export type ProjectServiceEvent = export type ProjectServiceEventHandler = (event: ProjectServiceEvent) => void; -/*@internal*/ +/** @internal */ export type PerformanceEventHandler = (event: PerformanceEvent) => void; export interface SafeList { @@ -330,7 +330,7 @@ export function convertScriptKindName(scriptKindName: protocol.ScriptKindName) { } } -/*@internal*/ +/** @internal */ export function convertUserPreferences(preferences: protocol.UserPreferences): UserPreferences { const { lazyConfiguredProjectsFromExternalProject, ...userPreferences } = preferences; return userPreferences; @@ -396,7 +396,7 @@ function findProjectByName(projectName: string, projects: T[] const noopConfigFileWatcher: FileWatcher = { close: noop }; -/*@internal*/ +/** @internal */ interface ConfigFileExistenceInfo { /** * Cached value of existence of config file @@ -468,8 +468,11 @@ function isAncestorConfigFileInfo(infoOrFileNameOrConfig: OpenScriptInfoOrClosed return !!(infoOrFileNameOrConfig as AncestorConfigFileInfo).configFileInfo; } -/*@internal*/ -/** Kind of operation to perform to get project reference project */ +/** + * Kind of operation to perform to get project reference project + * + * @internal + */ export enum ProjectReferenceProjectLoadKind { /** Find existing project for project reference */ Find, @@ -479,14 +482,14 @@ export enum ProjectReferenceProjectLoadKind { FindCreateLoad } -/*@internal*/ +/** @internal */ export function forEachResolvedProjectReferenceProject( project: ConfiguredProject, fileName: string | undefined, cb: (child: ConfiguredProject) => T | undefined, projectReferenceProjectLoadKind: ProjectReferenceProjectLoadKind.Find | ProjectReferenceProjectLoadKind.FindCreate, ): T | undefined; -/*@internal*/ +/** @internal */ export function forEachResolvedProjectReferenceProject( project: ConfiguredProject, fileName: string | undefined, @@ -640,14 +643,17 @@ function isScriptInfoWatchedFromNodeModules(info: ScriptInfo) { return !info.isScriptOpen() && info.mTime !== undefined; } -/*@internal*/ -/** true if script info is part of project and is not in project because it is referenced from project reference source */ +/** + * true if script info is part of project and is not in project because it is referenced from project reference source + * + * @internal + */ export function projectContainsInfoDirectly(project: Project, info: ScriptInfo) { return project.containsScriptInfo(info) && !project.isSourceOfProjectReferenceRedirect(info.path); } -/*@internal*/ +/** @internal */ export function updateProjectIfDirty(project: Project) { project.invalidateResolutionsOfFailedLookupLocations(); return project.dirty && project.updateGraph(); @@ -659,7 +665,7 @@ function setProjectOptionsUsed(project: ConfiguredProject | ExternalProject) { } } -/*@internal*/ +/** @internal */ export interface OpenFileArguments { fileName: string; content?: string; @@ -668,7 +674,7 @@ export interface OpenFileArguments { projectRootPath?: string; } -/*@internal*/ +/** @internal */ export interface ChangeFileArguments { fileName: string; changes: Iterator; @@ -679,7 +685,7 @@ export interface WatchOptionsAndErrors { errors: Diagnostic[] | undefined; } -/*@internal*/ +/** @internal */ export interface ParsedConfig{ cachedDirectoryStructureHost: CachedDirectoryStructureHost; /** @@ -704,16 +710,16 @@ function createProjectNameFactoryWithCounter(nameFactory: (counter: number) => s export class ProjectService { - /*@internal*/ + /** @internal */ readonly typingsCache: TypingsCache; - /*@internal*/ + /** @internal */ readonly documentRegistry: DocumentRegistry; /** * Container of all known scripts */ - /*@internal*/ + /** @internal */ readonly filenameToScriptInfo = new Map(); private readonly nodeModulesWatchers = new Map(); /** @@ -728,7 +734,7 @@ export class ProjectService { /** * Map to the real path of the infos */ - /* @internal */ + /** @internal */ readonly realpathToScriptInfos: MultiMap | undefined; /** * maps external project file name to list of config files that were the part of this project @@ -747,17 +753,17 @@ export class ProjectService { * projects specified by a tsconfig.json file */ readonly configuredProjects: Map = new Map(); - /*@internal*/ + /** @internal */ readonly newInferredProjectName = createProjectNameFactoryWithCounter(makeInferredProjectName); - /*@internal*/ + /** @internal */ readonly newAutoImportProviderProjectName = createProjectNameFactoryWithCounter(makeAutoImportProviderProjectName); - /*@internal*/ + /** @internal */ readonly newAuxiliaryProjectName = createProjectNameFactoryWithCounter(makeAuxiliaryProjectName); /** * Open files: with value being project root path, and key being Path of the file that is open */ readonly openFiles: Map = new Map(); - /* @internal */ + /** @internal */ readonly configFileForOpenFiles: ESMap = new Map(); /** * Map of open files that are opened without complete path but have projectRoot as current directory @@ -781,15 +787,15 @@ export class ProjectService { * - Or it is present if we have configured project open with config file at that location * In this case the exists property is always true */ - /*@internal*/ readonly configFileExistenceInfoCache = new Map(); - /*@internal*/ readonly throttledOperations: ThrottledOperations; + /** @internal */ readonly configFileExistenceInfoCache = new Map(); + /** @internal */ readonly throttledOperations: ThrottledOperations; private readonly hostConfiguration: HostConfiguration; private safelist: SafeList = defaultTypeSafeList; private readonly legacySafelist = new Map(); private pendingProjectUpdates = new Map(); - /* @internal */ + /** @internal */ pendingEnsureProjectForOpenFiles = false; readonly currentDirectory: NormalizedPath; @@ -820,21 +826,21 @@ export class ProjectService { /** Tracks projects that we have already sent telemetry for. */ private readonly seenProjects = new Map(); - /*@internal*/ + /** @internal */ readonly watchFactory: WatchFactory; - /*@internal*/ + /** @internal */ private readonly sharedExtendedConfigFileWatchers = new Map>(); - /*@internal*/ + /** @internal */ private readonly extendedConfigCache = new Map(); - /*@internal*/ + /** @internal */ readonly packageJsonCache: PackageJsonCache; - /*@internal*/ + /** @internal */ private packageJsonFilesMap: ESMap | undefined; - /*@internal*/ + /** @internal */ private incompleteCompletionsCache: IncompleteCompletionsCache | undefined; - /*@internal*/ + /** @internal */ readonly session: Session | undefined; @@ -917,39 +923,39 @@ export class ProjectService { return toPath(fileName, this.currentDirectory, this.toCanonicalFileName); } - /*@internal*/ + /** @internal */ getExecutingFilePath() { return this.getNormalizedAbsolutePath(this.host.getExecutingFilePath()); } - /*@internal*/ + /** @internal */ getNormalizedAbsolutePath(fileName: string) { return getNormalizedAbsolutePath(fileName, this.host.getCurrentDirectory()); } - /*@internal*/ + /** @internal */ setDocument(key: DocumentRegistryBucketKeyWithMode, path: Path, sourceFile: SourceFile) { const info = Debug.checkDefined(this.getScriptInfoForPath(path)); info.cacheSourceFile = { key, sourceFile }; } - /*@internal*/ + /** @internal */ getDocument(key: DocumentRegistryBucketKeyWithMode, path: Path): SourceFile | undefined { const info = this.getScriptInfoForPath(path); return info && info.cacheSourceFile && info.cacheSourceFile.key === key ? info.cacheSourceFile.sourceFile : undefined; } - /* @internal */ + /** @internal */ ensureInferredProjectsUpToDate_TestOnly() { this.ensureProjectStructuresUptoDate(); } - /* @internal */ + /** @internal */ getCompilerOptionsForInferredProjects() { return this.compilerOptionsForInferredProjects; } - /* @internal */ + /** @internal */ onUpdateLanguageServiceStateForProject(project: Project, languageServiceEnabled: boolean) { if (!this.eventHandler) { return; @@ -1008,7 +1014,7 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ delayEnsureProjectForOpenFiles() { if (!this.openFiles.size) return; this.pendingEnsureProjectForOpenFiles = true; @@ -1041,12 +1047,12 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ hasPendingProjectUpdate(project: Project) { return this.pendingProjectUpdates.has(project.getProjectName()); } - /* @internal */ + /** @internal */ sendProjectsUpdatedInBackgroundEvent() { if (!this.eventHandler) { return; @@ -1061,7 +1067,7 @@ export class ProjectService { this.eventHandler(event); } - /* @internal */ + /** @internal */ sendLargeFileReferencedEvent(file: string, fileSize: number) { if (!this.eventHandler) { return; @@ -1074,7 +1080,7 @@ export class ProjectService { this.eventHandler(event); } - /* @internal */ + /** @internal */ sendProjectLoadingStartEvent(project: ConfiguredProject, reason: string) { if (!this.eventHandler) { return; @@ -1087,7 +1093,7 @@ export class ProjectService { this.eventHandler(event); } - /* @internal */ + /** @internal */ sendProjectLoadingFinishEvent(project: ConfiguredProject) { if (!this.eventHandler || !project.sendLoadingProjectFinish) { return; @@ -1101,14 +1107,14 @@ export class ProjectService { this.eventHandler(event); } - /* @internal */ + /** @internal */ sendPerformanceEvent(kind: PerformanceEvent["kind"], durationMs: number) { if (this.performanceEventHandler) { this.performanceEventHandler({ kind, durationMs }); } } - /* @internal */ + /** @internal */ delayUpdateProjectGraphAndEnsureProjectStructureForOpenFiles(project: Project) { this.delayUpdateProjectGraph(project); this.delayEnsureProjectForOpenFiles(); @@ -1182,14 +1188,14 @@ export class ProjectService { return this.findExternalProjectByProjectName(projectName) || this.findConfiguredProjectByProjectName(toNormalizedPath(projectName)); } - /* @internal */ + /** @internal */ private forEachProject(cb: (project: Project) => void) { this.externalProjects.forEach(cb); this.configuredProjects.forEach(cb); this.inferredProjects.forEach(cb); } - /* @internal */ + /** @internal */ forEachEnabledProject(cb: (project: Project) => void) { this.forEachProject(project => { if (!project.isOrphan() && project.languageServiceEnabled) { @@ -1202,13 +1208,13 @@ export class ProjectService { return ensureProject ? this.ensureDefaultProjectForFile(fileName) : this.tryGetDefaultProjectForFile(fileName); } - /* @internal */ + /** @internal */ tryGetDefaultProjectForFile(fileNameOrScriptInfo: NormalizedPath | ScriptInfo): Project | undefined { const scriptInfo = isString(fileNameOrScriptInfo) ? this.getScriptInfoForNormalizedPath(fileNameOrScriptInfo) : fileNameOrScriptInfo; return scriptInfo && !scriptInfo.isOrphan() ? scriptInfo.getDefaultProject() : undefined; } - /* @internal */ + /** @internal */ ensureDefaultProjectForFile(fileNameOrScriptInfo: NormalizedPath | ScriptInfo): Project { return this.tryGetDefaultProjectForFile(fileNameOrScriptInfo) || this.doEnsureDefaultProjectForFile(fileNameOrScriptInfo); } @@ -1339,7 +1345,7 @@ export class ProjectService { /** * This is to watch whenever files are added or removed to the wildcard directories */ - /*@internal*/ + /** @internal */ private watchWildcardDirectory(directory: Path, flags: WatchDirectoryFlags, configFileName: NormalizedPath, config: ParsedConfig) { return this.watchFactory.watchDirectory( directory, @@ -1405,7 +1411,7 @@ export class ProjectService { ); } - /*@internal*/ + /** @internal */ private delayUpdateProjectsFromParsedConfigOnConfigFileChange(canonicalConfigFilePath: NormalizedPath, reloadReason: string) { const configFileExistenceInfo = this.configFileExistenceInfoCache.get(canonicalConfigFilePath); if (!configFileExistenceInfo?.config) return false; @@ -1434,7 +1440,7 @@ export class ProjectService { return scheduledAnyProjectUpdate; } - /*@internal*/ + /** @internal */ private onConfigFileChanged(canonicalConfigFilePath: NormalizedPath, eventKind: FileWatcherEventKind) { const configFileExistenceInfo = this.configFileExistenceInfoCache.get(canonicalConfigFilePath)!; if (eventKind === FileWatcherEventKind.Deleted) { @@ -1518,7 +1524,7 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ assignOrphanScriptInfoToInferredProject(info: ScriptInfo, projectRootPath: NormalizedPath | undefined) { Debug.assert(info.isOrphan()); @@ -1704,7 +1710,7 @@ export class ProjectService { return exists; } - /*@internal*/ + /** @internal */ private createConfigFileWatcherForParsedConfig(configFileName: NormalizedPath, canonicalConfigFilePath: NormalizedPath, forProject: ConfiguredProject) { const configFileExistenceInfo = this.configFileExistenceInfoCache.get(canonicalConfigFilePath)!; // When watching config file for parsed config, remove the noopFileWatcher that can be created for open files impacted by config file and watch for real @@ -1731,7 +1737,7 @@ export class ProjectService { forEachEntry(configFileExistenceInfo.openFilesImpactedByConfigFile, identity); } - /* @internal */ + /** @internal */ releaseParsedConfig(canonicalConfigFilePath: NormalizedPath, forProject: ConfiguredProject) { const configFileExistenceInfo = this.configFileExistenceInfoCache.get(canonicalConfigFilePath)!; if (!configFileExistenceInfo.config?.projects.delete(forProject.canonicalConfigFilePath)) return; @@ -1769,7 +1775,7 @@ export class ProjectService { * Close the config file watcher in the cached ConfigFileExistenceInfo * if there arent any open files that are root of inferred project and there is no parsed config held by any project */ - /*@internal*/ + /** @internal */ private closeConfigFileWatcherOnReleaseOfOpenFile(configFileExistenceInfo: ConfigFileExistenceInfo) { // Close the config file watcher if there are no more open files that are root of inferred project // or if there are no projects that need to watch this config file existence info @@ -1817,7 +1823,7 @@ export class ProjectService { /** * This is called by inferred project whenever script info is added as a root */ - /* @internal */ + /** @internal */ startWatchingConfigFilesForInferredProjectRoot(info: ScriptInfo) { Debug.assert(info.isScriptOpen()); this.forEachConfigFileLocation(info, (canonicalConfigFilePath, configFileName) => { @@ -1847,7 +1853,7 @@ export class ProjectService { /** * This is called by inferred project whenever root script info is removed from it */ - /* @internal */ + /** @internal */ stopWatchingConfigFilesForInferredProjectRoot(info: ScriptInfo) { this.forEachConfigFileLocation(info, canonicalConfigFilePath => { const configFileExistenceInfo = this.configFileExistenceInfoCache.get(canonicalConfigFilePath); @@ -1916,7 +1922,7 @@ export class ProjectService { return undefined; } - /*@internal*/ + /** @internal */ findDefaultConfiguredProject(info: ScriptInfo) { if (!info.isScriptOpen()) return undefined; const configFileName = this.getConfigFileNameForFile(info); @@ -1980,7 +1986,7 @@ export class ProjectService { this.logger.endGroup(); } - /*@internal*/ + /** @internal */ findConfiguredProjectByProjectName(configFileName: NormalizedPath): ConfiguredProject | undefined { // make sure that casing of config file name is consistent const canonicalConfigFilePath = asNormalizedPath(this.toCanonicalFileName(configFileName)); @@ -2051,7 +2057,7 @@ export class ProjectService { return project; } - /*@internal*/ + /** @internal */ sendProjectTelemetry(project: ExternalProject | ConfiguredProject): void { if (this.seenProjects.has(project.projectName)) { setProjectOptionsUsed(project); @@ -2105,7 +2111,7 @@ export class ProjectService { project.setTypeAcquisition(typeAcquisition); } - /* @internal */ + /** @internal */ createConfiguredProject(configFileName: NormalizedPath) { tracing?.instant(tracing.Phase.Session, "createConfiguredProject", { configFilePath: configFileName }); this.logger.info(`Creating configuration project ${configFileName}`); @@ -2138,7 +2144,7 @@ export class ProjectService { return project; } - /* @internal */ + /** @internal */ private createConfiguredProjectWithDelayLoad(configFileName: NormalizedPath, reason: string) { const project = this.createConfiguredProject(configFileName); project.pendingReload = ConfigFileProgramReloadLevel.Full; @@ -2146,14 +2152,14 @@ export class ProjectService { return project; } - /* @internal */ + /** @internal */ createAndLoadConfiguredProject(configFileName: NormalizedPath, reason: string) { const project = this.createConfiguredProject(configFileName); this.loadConfiguredProject(project, reason); return project; } - /* @internal */ + /** @internal */ private createLoadAndUpdateConfiguredProject(configFileName: NormalizedPath, reason: string) { const project = this.createAndLoadConfiguredProject(configFileName, reason); project.updateGraph(); @@ -2163,7 +2169,7 @@ export class ProjectService { /** * Read the config file of the project, and update the project root file names. */ - /* @internal */ + /** @internal */ private loadConfiguredProject(project: ConfiguredProject, reason: string) { tracing?.push(tracing.Phase.Session, "loadConfiguredProject", { configFilePath: project.canonicalConfigFilePath }); this.sendProjectLoadingStartEvent(project, reason); @@ -2210,7 +2216,7 @@ export class ProjectService { tracing?.pop(); } - /*@internal*/ + /** @internal */ ensureParsedConfigUptoDate(configFilename: NormalizedPath, canonicalConfigFilePath: NormalizedPath, configFileExistenceInfo: ConfigFileExistenceInfo, forProject: ConfiguredProject): ConfigFileExistenceInfo { if (configFileExistenceInfo.config) { if (!configFileExistenceInfo.config.reloadLevel) return configFileExistenceInfo; @@ -2302,7 +2308,7 @@ export class ProjectService { return configFileExistenceInfo; } - /*@internal*/ + /** @internal */ watchWildcards(configFileName: NormalizedPath, { exists, config }: ConfigFileExistenceInfo, forProject: ConfiguredProject) { config!.projects.set(forProject.canonicalConfigFilePath, true); if (exists) { @@ -2323,7 +2329,7 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ stopWatchingWildCards(canonicalConfigFilePath: NormalizedPath, forProject: ConfiguredProject) { const configFileExistenceInfo = this.configFileExistenceInfoCache.get(canonicalConfigFilePath)!; if (!configFileExistenceInfo.config || @@ -2429,7 +2435,7 @@ export class ProjectService { /** * Reload the file names from config file specs and update the project graph */ - /*@internal*/ + /** @internal */ reloadFileNamesOfConfiguredProject(project: ConfiguredProject) { const fileNames = this.reloadFileNamesOfParsedConfig(project.getConfigFilePath(), this.configFileExistenceInfoCache.get(project.canonicalConfigFilePath)!.config!); project.updateErrorOnNoInputFiles(fileNames); @@ -2437,7 +2443,7 @@ export class ProjectService { return project.updateGraph(); } - /*@internal*/ + /** @internal */ private reloadFileNamesOfParsedConfig(configFileName: NormalizedPath, config: ParsedConfig) { if (config.reloadLevel === undefined) return config.parsedCommandLine!.fileNames; Debug.assert(config.reloadLevel === ConfigFileProgramReloadLevel.Partial); @@ -2453,7 +2459,7 @@ export class ProjectService { return fileNames; } - /*@internal*/ + /** @internal */ setFileNamesOfAutoImportProviderProject(project: AutoImportProviderProject, fileNames: string[]) { this.updateNonInferredProjectFiles(project, fileNames, fileNamePropertyReader); } @@ -2461,7 +2467,7 @@ export class ProjectService { /** * Read the config file of the project again by clearing the cache and update the project graph */ - /* @internal */ + /** @internal */ reloadConfiguredProject(project: ConfiguredProject, reason: string, isInitialLoad: boolean, clearSemanticCache: boolean) { // At this point, there is no reason to not have configFile in the host const host = project.getCachedDirectoryStructureHost(); @@ -2479,7 +2485,7 @@ export class ProjectService { this.sendConfigFileDiagEvent(project, configFileName); } - /* @internal */ + /** @internal */ private clearSemanticCache(project: Project) { project.resolutionCache.clear(); project.getLanguageService(/*ensureSynchronized*/ false).cleanupSemanticCache(); @@ -2596,7 +2602,7 @@ export class ProjectService { return project; } - /*@internal*/ + /** @internal */ getOrCreateScriptInfoNotOpenedByClient(uncheckedFileName: string, currentDirectory: string, hostToQueryFileExistsOn: DirectoryStructureHost) { return this.getOrCreateScriptInfoNotOpenedByClientForNormalizedPath( toNormalizedPath(uncheckedFileName), currentDirectory, /*scriptKind*/ undefined, @@ -2608,7 +2614,7 @@ export class ProjectService { return this.getScriptInfoForNormalizedPath(toNormalizedPath(uncheckedFileName)); } - /* @internal */ + /** @internal */ getScriptInfoOrConfig(uncheckedFileName: string): ScriptInfoOrConfig | undefined { const path = toNormalizedPath(uncheckedFileName); const info = this.getScriptInfoForNormalizedPath(path); @@ -2617,7 +2623,7 @@ export class ProjectService { return configProject && configProject.getCompilerOptions().configFile; } - /* @internal */ + /** @internal */ logErrorForScriptInfoNotFound(fileName: string): void { const names = arrayFrom(this.filenameToScriptInfo.entries()).map(([path, scriptInfo]) => ({ path, fileName: scriptInfo.fileName })); this.logger.msg(`Could not find file ${JSON.stringify(fileName)}.\nAll files are: ${JSON.stringify(names)}`, Msg.Err); @@ -2627,7 +2633,7 @@ export class ProjectService { * Returns the projects that contain script info through SymLink * Note that this does not return projects in info.containingProjects */ - /*@internal*/ + /** @internal */ getSymlinkedProjects(info: ScriptInfo): MultiMap | undefined { let projects: MultiMap | undefined; if (this.realpathToScriptInfos) { @@ -2740,7 +2746,7 @@ export class ProjectService { return result; } - /*@internal*/ + /** @internal */ watchPackageJsonsInNodeModules(dir: Path, project: Project): FileWatcher { const watcher = this.nodeModulesWatchers.get(dir) || this.createNodeModulesWatcher(dir); (watcher.affectedModuleSpecifierCacheProjects ||= new Set()).add(project.getProjectName()); @@ -2868,7 +2874,7 @@ export class ProjectService { return this.filenameToScriptInfo.get(fileName); } - /*@internal*/ + /** @internal */ getDocumentPositionMapper(project: Project, generatedFileName: string, sourceFileName?: string): DocumentPositionMapper | undefined { // Since declaration info and map file watches arent updating project's directory structure host (which can cache file structure) use host const declarationInfo = this.getOrCreateScriptInfoNotOpenedByClient(generatedFileName, project.currentDirectory, this.host); @@ -2977,7 +2983,7 @@ export class ProjectService { return fileWatcher; } - /*@internal*/ + /** @internal */ getSourceFileLike(fileName: string, projectNameOrProject: string | Project, declarationInfo?: ScriptInfo) { const project = (projectNameOrProject as Project).projectName ? projectNameOrProject as Project : this.findProject(projectNameOrProject as string); if (project) { @@ -3018,7 +3024,7 @@ export class ProjectService { return info.sourceFileLike; } - /*@internal*/ + /** @internal */ setPerformanceEventHandler(performanceEventHandler: PerformanceEventHandler) { this.performanceEventHandler = performanceEventHandler; } @@ -3076,12 +3082,12 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ getWatchOptions(project: Project) { return this.getWatchOptionsFromProjectWatchOptions(project.getWatchOptions()); } - /*@internal*/ + /** @internal */ private getWatchOptionsFromProjectWatchOptions(projectOptions: WatchOptions | undefined) { return projectOptions && this.hostConfiguration.watchOptions ? { ...this.hostConfiguration.watchOptions, ...projectOptions } : @@ -3271,7 +3277,7 @@ export class ProjectService { return this.openClientFileWithNormalizedPath(toNormalizedPath(fileName), fileContent, scriptKind, /*hasMixedContent*/ false, projectRootPath ? toNormalizedPath(projectRootPath) : undefined); } - /*@internal*/ + /** @internal */ getOriginalLocationEnsuringConfiguredProject(project: Project, location: DocumentPosition): DocumentPosition | undefined { const isSourceOfProjectReferenceRedirect = project.isSourceOfProjectReferenceRedirect(location.fileName); const originalLocation = isSourceOfProjectReferenceRedirect ? @@ -3502,7 +3508,7 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ loadAncestorProjectTree(forProjects?: ReadonlyCollection) { forProjects = forProjects || mapDefinedEntries( this.configuredProjects, @@ -3701,7 +3707,7 @@ export class ProjectService { * @param filename is absolute pathname */ closeClientFile(uncheckedFileName: string): void; - /*@internal*/ + /** @internal */ closeClientFile(uncheckedFileName: string, skipAssignOrphanScriptInfosToInferredProject: true): boolean; closeClientFile(uncheckedFileName: string, skipAssignOrphanScriptInfosToInferredProject?: true) { const info = this.getScriptInfoForNormalizedPath(toNormalizedPath(uncheckedFileName)); @@ -3724,7 +3730,7 @@ export class ProjectService { } } - /* @internal */ + /** @internal */ synchronizeProjectList(knownProjects: protocol.ProjectVersionInfo[], includeProjectReferenceRedirectInfo?: boolean): ProjectFilesWithTSDiagnostics[] { const files: ProjectFilesWithTSDiagnostics[] = []; this.collectChanges(knownProjects, this.externalProjects, includeProjectReferenceRedirectInfo, files); @@ -3733,7 +3739,7 @@ export class ProjectService { return files; } - /* @internal */ + /** @internal */ applyChangesInOpenFiles(openFiles: Iterator | undefined, changedFiles?: Iterator, closedFiles?: string[]): void { let openScriptInfos: ScriptInfo[] | undefined; let assignOrphanScriptInfosToInferredProject = false; @@ -3796,7 +3802,7 @@ export class ProjectService { } } - /* @internal */ + /** @internal */ applyChangesToFile(scriptInfo: ScriptInfo, changes: Iterator) { while (true) { const iterResult = changes.next(); @@ -4104,7 +4110,7 @@ export class ProjectService { return false; } - /*@internal*/ + /** @internal */ requestEnablePlugin(project: Project, pluginConfigEntry: PluginImport, searchPaths: string[], pluginConfigOverrides: Map | undefined) { if (!this.host.importPlugin && !this.host.require) { this.logger.info("Plugins were requested but not running in environment that supports 'require'. Nothing will be loaded"); @@ -4131,12 +4137,12 @@ export class ProjectService { project.endEnablePlugin(project.beginEnablePluginSync(pluginConfigEntry, searchPaths, pluginConfigOverrides)); } - /* @internal */ + /** @internal */ hasNewPluginEnablementRequests() { return !!this.pendingPluginEnablements; } - /* @internal */ + /** @internal */ hasPendingPluginEnablements() { return !!this.currentPluginEnablementPromise; } @@ -4144,7 +4150,7 @@ export class ProjectService { /** * Waits for any ongoing plugin enablement requests to complete. */ - /* @internal */ + /** @internal */ async waitForPendingPlugins() { while (this.currentPluginEnablementPromise) { await this.currentPluginEnablementPromise; @@ -4154,7 +4160,7 @@ export class ProjectService { /** * Starts enabling any requested plugins without waiting for the result. */ - /* @internal */ + /** @internal */ enableRequestedPlugins() { if (this.pendingPluginEnablements) { void this.enableRequestedPluginsAsync(); @@ -4222,7 +4228,7 @@ export class ProjectService { this.currentPluginConfigOverrides.set(args.pluginName, args.configuration); } - /*@internal*/ + /** @internal */ getPackageJsonsVisibleToFile(fileName: string, rootDir?: string): readonly ProjectPackageJsonInfo[] { const packageJsonCache = this.packageJsonCache; const rootPath = rootDir && this.toPath(rootDir); @@ -4250,7 +4256,7 @@ export class ProjectService { return result; } - /*@internal*/ + /** @internal */ getNearestAncestorDirectoryWithPackageJson(fileName: string): string | undefined { return forEachAncestorDirectory(fileName, directory => { switch (this.packageJsonCache.directoryHasPackageJson(this.toPath(directory))) { @@ -4264,7 +4270,7 @@ export class ProjectService { }); } - /*@internal*/ + /** @internal */ private watchPackageJsonFile(path: Path) { const watchers = this.packageJsonFilesMap || (this.packageJsonFilesMap = new Map()); if (!watchers.has(path)) { @@ -4294,13 +4300,13 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ private onAddPackageJson(path: Path) { this.packageJsonCache.addOrUpdate(path); this.watchPackageJsonFile(path); } - /*@internal*/ + /** @internal */ includePackageJsonAutoImports(): PackageJsonAutoImportPreference { switch (this.hostConfiguration.preferences.includePackageJsonAutoImports) { case "on": return PackageJsonAutoImportPreference.On; @@ -4309,7 +4315,7 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ private invalidateProjectPackageJson(packageJsonPath: Path | undefined) { this.configuredProjects.forEach(invalidate); this.inferredProjects.forEach(invalidate); @@ -4324,7 +4330,7 @@ export class ProjectService { } } - /*@internal*/ + /** @internal */ getIncompleteCompletionsCache() { return this.incompleteCompletionsCache ||= createIncompleteCompletionsCache(); } @@ -4345,9 +4351,9 @@ function createIncompleteCompletionsCache(): IncompleteCompletionsCache { }; } -/* @internal */ +/** @internal */ export type ScriptInfoOrConfig = ScriptInfo | TsConfigSourceFile; -/* @internal */ +/** @internal */ export function isConfigFile(config: ScriptInfoOrConfig): config is TsConfigSourceFile { return (config as TsConfigSourceFile).kind !== undefined; } diff --git a/src/server/project.ts b/src/server/project.ts index 6edaab1227cf4..1494528726bfe 100644 --- a/src/server/project.ts +++ b/src/server/project.ts @@ -39,10 +39,10 @@ export enum ProjectKind { Auxiliary, } -/* @internal */ +/** @internal */ export type Mutable = { -readonly [K in keyof T]: T[K]; }; -/* @internal */ +/** @internal */ export function countEachFileTypes(infos: ScriptInfo[], includeSizes = false): FileStats { const result: Mutable = { js: 0, jsSize: 0, @@ -101,12 +101,12 @@ export function allFilesAreJsOrDts(project: Project): boolean { return counts.ts === 0 && counts.tsx === 0; } -/* @internal */ +/** @internal */ export function hasNoTypeScriptSource(fileNames: string[]): boolean { return !fileNames.some(fileName => (fileExtensionIs(fileName, Extension.Ts) && !isDeclarationFileName(fileName)) || fileExtensionIs(fileName, Extension.Tsx)); } -/* @internal */ +/** @internal */ export interface ProjectFilesWithTSDiagnostics extends protocol.ProjectFiles { projectErrors: readonly Diagnostic[]; } @@ -133,7 +133,7 @@ export interface PluginModuleWithName { export type PluginModuleFactory = (mod: { typescript: typeof ts }) => PluginModule; -/* @internal */ +/** @internal */ export interface BeginEnablePluginResult { pluginConfigEntry: PluginImport; pluginConfigOverrides: Map | undefined; @@ -144,8 +144,9 @@ export interface BeginEnablePluginResult { /** * The project root can be script info - if root is present, * or it could be just normalized path if root wasn't present on the host(only for non inferred project) + * + * @internal */ -/* @internal */ export interface ProjectRootFile { fileName: NormalizedPath; info?: ScriptInfo; @@ -160,7 +161,7 @@ function isGeneratedFileWatcher(watch: GeneratedFileWatcherMap): watch is Genera return (watch as GeneratedFileWatcher).generatedFilePath !== undefined; } -/*@internal*/ +/** @internal */ export interface EmitResult { emitSkipped: boolean; diagnostics: readonly Diagnostic[]; @@ -177,7 +178,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo /*@internal*/ protected readonly plugins: PluginModuleWithName[] = []; - /*@internal*/ + /** @internal */ /** * This is map from files to unresolved imports in it * Maop does not contain entries for files that do not have unresolved imports @@ -185,14 +186,14 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo */ cachedUnresolvedImportsPerFile = new Map(); - /*@internal*/ + /** @internal */ lastCachedUnresolvedImportsList: SortedReadonlyArray | undefined; - /*@internal*/ + /** @internal */ private hasAddedorRemovedFiles = false; - /*@internal*/ + /** @internal */ private hasAddedOrRemovedSymlinks = false; - /*@internal*/ + /** @internal */ lastFileExceededProgramSize: string | undefined; // wrapper over the real language service that will suppress all semantic operations @@ -203,10 +204,10 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo readonly trace?: (s: string) => void; readonly realpath?: (path: string) => string; - /*@internal*/ + /** @internal */ hasInvalidatedResolutions: HasInvalidatedResolutions | undefined; - /*@internal*/ + /** @internal */ resolutionCache: ResolutionCache; private builderState: BuilderState | undefined; @@ -239,28 +240,28 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo protected isInitialLoadPending: () => boolean = returnFalse; - /*@internal*/ + /** @internal */ dirty = false; - /*@internal*/ + /** @internal */ typingFiles: SortedReadonlyArray = emptyArray; - /*@internal*/ + /** @internal */ originalConfiguredProjects: Set | undefined; - /*@internal*/ + /** @internal */ private packageJsonsForAutoImport: Set | undefined; - /*@internal*/ + /** @internal */ private noDtsResolutionProject?: AuxiliaryProject | undefined; - /*@internal*/ + /** @internal */ getResolvedProjectReferenceToRedirect(_fileName: string): ResolvedProjectReference | undefined { return undefined; } - /* @internal */ useSourceOfProjectReferenceRedirect?(): boolean; - /* @internal */ getParsedCommandLine?(fileName: string): ParsedCommandLine | undefined; + /** @internal */ useSourceOfProjectReferenceRedirect?(): boolean; + /** @internal */ getParsedCommandLine?(fileName: string): ParsedCommandLine | undefined; private readonly cancellationToken: ThrottledCancellationToken; @@ -286,7 +287,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return result.module; } - /*@internal*/ + /** @internal */ public static async importServicePluginAsync(moduleName: string, initialDir: string, host: ServerHost, log: (message: string) => void, logErrors?: (message: string) => void): Promise<{} | undefined> { Debug.assertIsDefined(host.importPlugin); const resolvedPath = combinePaths(initialDir, "node_modules"); @@ -306,31 +307,34 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return result.module; } - /*@internal*/ + /** @internal */ readonly currentDirectory: string; - /*@internal*/ + /** @internal */ + readonly projectName: string; + + /** @internal */ public directoryStructureHost: DirectoryStructureHost; - /*@internal*/ + /** @internal */ public readonly getCanonicalFileName: GetCanonicalFileName; - /*@internal*/ + /** @internal */ private exportMapCache: ExportInfoMap | undefined; - /*@internal*/ + /** @internal */ private changedFilesForExportMapCache: Set | undefined; - /*@internal*/ + /** @internal */ private moduleSpecifierCache = createModuleSpecifierCache(this); - /*@internal*/ + /** @internal */ private symlinks: SymlinkCache | undefined; - /*@internal*/ + /** @internal */ autoImportProviderHost: AutoImportProviderProject | false | undefined; - /*@internal*/ + /** @internal */ protected typeAcquisition: TypeAcquisition | undefined; - /*@internal*/ + /** @internal */ constructor( - /*@internal*/ readonly projectName: string, + projectName: string, readonly projectKind: ProjectKind, readonly projectService: ProjectService, private documentRegistry: DocumentRegistry, @@ -342,6 +346,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo directoryStructureHost: DirectoryStructureHost, currentDirectory: string | undefined, ) { + this.projectName = projectName; this.directoryStructureHost = directoryStructureHost; this.currentDirectory = this.projectService.getNormalizedAbsolutePath(currentDirectory || ""); this.getCanonicalFileName = this.projectService.toCanonicalFileName; @@ -408,7 +413,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.typingsCache.installPackage({ ...options, projectName: this.projectName, projectRootPath: this.toPath(this.currentDirectory) }); } - /*@internal*/ + /** @internal */ getGlobalTypingsCacheLocation() { return this.getGlobalCache(); } @@ -417,7 +422,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.projectService.typingsCache; } - /*@internal*/ + /** @internal */ getSymlinkCache(): SymlinkCache { if (!this.symlinks) { this.symlinks = createSymlinkCache(this.getCurrentDirectory(), this.getCanonicalFileName); @@ -561,17 +566,17 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.directoryStructureHost.getDirectories!(path); // TODO: GH#18217 } - /*@internal*/ + /** @internal */ getCachedDirectoryStructureHost(): CachedDirectoryStructureHost { return undefined!; // TODO: GH#18217 } - /*@internal*/ + /** @internal */ toPath(fileName: string) { return toPath(fileName, this.currentDirectory, this.projectService.toCanonicalFileName); } - /*@internal*/ + /** @internal */ watchDirectoryOfFailedLookupLocation(directory: string, cb: DirectoryWatcherCallback, flags: WatchDirectoryFlags) { return this.projectService.watchFactory.watchDirectory( directory, @@ -583,7 +588,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo ); } - /*@internal*/ + /** @internal */ watchAffectingFileLocation(file: string, cb: FileWatcherCallback) { return this.projectService.watchFactory.watchFile( file, @@ -595,12 +600,12 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo ); } - /*@internal*/ + /** @internal */ clearInvalidateResolutionOfFailedLookupTimer() { return this.projectService.throttledOperations.cancel(`${this.getProjectName()}FailedLookupInvalidation`); } - /*@internal*/ + /** @internal */ scheduleInvalidateResolutionsOfFailedLookupLocations() { this.projectService.throttledOperations.schedule(`${this.getProjectName()}FailedLookupInvalidation`, /*delay*/ 1000, () => { if (this.resolutionCache.invalidateResolutionsOfFailedLookupLocations()) { @@ -609,7 +614,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo }); } - /*@internal*/ + /** @internal */ invalidateResolutionsOfFailedLookupLocations() { if (this.clearInvalidateResolutionOfFailedLookupTimer() && this.resolutionCache.invalidateResolutionsOfFailedLookupLocations()) { @@ -618,12 +623,12 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /*@internal*/ + /** @internal */ onInvalidatedResolution() { this.projectService.delayUpdateProjectGraphAndEnsureProjectStructureForOpenFiles(this); } - /*@internal*/ + /** @internal */ watchTypeRootsDirectory(directory: string, cb: DirectoryWatcherCallback, flags: WatchDirectoryFlags) { return this.projectService.watchFactory.watchDirectory( directory, @@ -635,30 +640,30 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo ); } - /*@internal*/ + /** @internal */ hasChangedAutomaticTypeDirectiveNames() { return this.resolutionCache.hasChangedAutomaticTypeDirectiveNames(); } - /*@internal*/ + /** @internal */ onChangedAutomaticTypeDirectiveNames() { this.projectService.delayUpdateProjectGraphAndEnsureProjectStructureForOpenFiles(this); } - /*@internal*/ + /** @internal */ getGlobalCache() { return this.getTypeAcquisition().enable ? this.projectService.typingsInstaller.globalTypingsCacheLocation : undefined; } - /*@internal*/ + /** @internal */ globalCacheResolutionModuleName = JsTyping.nonRelativeModuleNameForTypingCache; - /*@internal*/ + /** @internal */ fileIsOpen(filePath: Path) { return this.projectService.openFiles.has(filePath); } - /*@internal*/ + /** @internal */ writeLog(s: string) { this.projectService.logger.info(s); } @@ -712,17 +717,17 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo this.languageService.clearSourceMapperCache(); } - /*@internal*/ + /** @internal */ getDocumentPositionMapper(generatedFileName: string, sourceFileName?: string): DocumentPositionMapper | undefined { return this.projectService.getDocumentPositionMapper(this, generatedFileName, sourceFileName); } - /*@internal*/ + /** @internal */ getSourceFileLike(fileName: string) { return this.projectService.getSourceFileLike(fileName, this); } - /*@internal*/ + /** @internal */ shouldEmitFile(scriptInfo: ScriptInfo | undefined) { return scriptInfo && !scriptInfo.isDynamicOrHasMixedContent() && @@ -839,7 +844,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.program.getSourceFileByPath(path); } - /* @internal */ + /** @internal */ getSourceFileOrConfigFile(path: Path): SourceFile | undefined { const options = this.program!.getCompilerOptions(); return path === options.configFilePath ? options.configFile : this.getSourceFile(path); @@ -917,7 +922,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.rootFiles && this.rootFiles.length > 0; } - /*@internal*/ + /** @internal */ isOrphan() { return false; } @@ -926,7 +931,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.rootFiles && this.rootFiles.map(info => info.fileName); } - /*@internal*/ + /** @internal */ getRootFilesMap() { return this.rootFilesMap; } @@ -988,7 +993,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return result; } - /* @internal */ + /** @internal */ getFileNamesWithRedirectInfo(includeProjectReferenceRedirectInfo: boolean) { return this.getFileNames().map((fileName): protocol.FileWithProjectReferenceRedirectInfo => ({ fileName, @@ -1075,7 +1080,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo (this.updatedFileNames || (this.updatedFileNames = new Set())).add(fileName); } - /*@internal*/ + /** @internal */ markFileAsDirty(changedFile: Path) { this.markAsDirty(); if (this.exportMapCache && !this.exportMapCache.isEmpty()) { @@ -1090,7 +1095,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /*@internal*/ + /** @internal */ onAutoImportProviderSettingsChanged() { if (this.autoImportProviderHost === false) { this.autoImportProviderHost = undefined; @@ -1100,7 +1105,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /*@internal*/ + /** @internal */ onPackageJsonChange(packageJsonPath: Path) { if (this.packageJsonsForAutoImport?.has(packageJsonPath)) { this.moduleSpecifierCache.clear(); @@ -1110,7 +1115,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /* @internal */ + /** @internal */ onFileAddedOrRemoved(isSymlink: boolean | undefined) { this.hasAddedorRemovedFiles = true; if (isSymlink) { @@ -1118,7 +1123,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /* @internal */ + /** @internal */ onDiscoveredSymlink() { this.hasAddedOrRemovedSymlinks = true; } @@ -1180,7 +1185,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return !hasNewProgram; } - /*@internal*/ + /** @internal */ updateTypingFiles(typingFiles: SortedReadonlyArray) { if (enumerateInsertsAndDeletes(typingFiles, this.typingFiles, getStringComparer(!this.useCaseSensitiveFileNames()), /*inserted*/ noop, @@ -1194,7 +1199,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /* @internal */ + /** @internal */ getCurrentProgram(): Program | undefined { return this.program; } @@ -1340,7 +1345,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return hasNewProgram; } - /* @internal */ + /** @internal */ sendPerformanceEvent(kind: PerformanceEvent["kind"], durationMs: number) { this.projectService.sendPerformanceEvent(kind, durationMs); } @@ -1388,7 +1393,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return !!this.missingFilesMap && this.missingFilesMap.has(path); } - /* @internal */ + /** @internal */ addGeneratedFileWatch(generatedFile: string, sourceFile: string) { if (outFile(this.compilerOptions)) { // Single watcher @@ -1473,7 +1478,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return strBuilder; } - /*@internal*/ + /** @internal */ print(writeProjectFileNames: boolean) { this.writeLog(`Project '${this.projectName}' (${ProjectKind[this.projectKind]})`); this.writeLog(this.filesToString(writeProjectFileNames && this.projectService.logger.hasLevel(LogLevel.verbose))); @@ -1501,12 +1506,12 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /*@internal*/ + /** @internal */ setWatchOptions(watchOptions: WatchOptions | undefined) { this.watchOptions = watchOptions; } - /*@internal*/ + /** @internal */ getWatchOptions(): WatchOptions | undefined { return this.watchOptions; } @@ -1521,7 +1526,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.typeAcquisition || {}; } - /* @internal */ + /** @internal */ getChangesSinceVersion(lastKnownVersion?: number, includeProjectReferenceRedirectInfo?: boolean): ProjectFilesWithTSDiagnostics { const includeProjectReferenceRedirectInfoIfRequested = includeProjectReferenceRedirectInfo @@ -1632,7 +1637,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo this.rootFilesMap.delete(info.path); } - /*@internal*/ + /** @internal */ isSourceOfProjectReferenceRedirect(fileName: string) { return !!this.program && this.program.isSourceOfProjectReferenceRedirect(fileName); } @@ -1675,7 +1680,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo /** * Performs the initial steps of enabling a plugin by finding and instantiating the module for a plugin synchronously using 'require'. */ - /*@internal*/ + /** @internal */ beginEnablePluginSync(pluginConfigEntry: PluginImport, searchPaths: string[], pluginConfigOverrides: Map | undefined): BeginEnablePluginResult { Debug.assertIsDefined(this.projectService.host.require); @@ -1692,7 +1697,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo /** * Performs the initial steps of enabling a plugin by finding and instantiating the module for a plugin asynchronously using dynamic `import`. */ - /*@internal*/ + /** @internal */ async beginEnablePluginAsync(pluginConfigEntry: PluginImport, searchPaths: string[], pluginConfigOverrides: Map | undefined): Promise { Debug.assertIsDefined(this.projectService.host.importPlugin); @@ -1715,7 +1720,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo /** * Performs the remaining steps of enabling a plugin after its module has been instantiated. */ - /*@internal*/ + /** @internal */ endEnablePlugin({ pluginConfigEntry, pluginConfigOverrides, resolvedModule, errorLogs }: BeginEnablePluginResult) { if (resolvedModule) { const configurationOverride = pluginConfigOverrides && pluginConfigOverrides.get(pluginConfigEntry.name); @@ -1772,7 +1777,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /*@internal*/ + /** @internal */ onPluginConfigurationChanged(pluginName: string, configuration: any) { this.plugins.filter(plugin => plugin.name === pluginName).forEach(plugin => { if (plugin.module.onConfigurationChanged) { @@ -1786,45 +1791,45 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo this.projectService.sendProjectsUpdatedInBackgroundEvent(); } - /*@internal*/ + /** @internal */ getPackageJsonsVisibleToFile(fileName: string, rootDir?: string): readonly ProjectPackageJsonInfo[] { if (this.projectService.serverMode !== LanguageServiceMode.Semantic) return emptyArray; return this.projectService.getPackageJsonsVisibleToFile(fileName, rootDir); } - /*@internal*/ + /** @internal */ getNearestAncestorDirectoryWithPackageJson(fileName: string): string | undefined { return this.projectService.getNearestAncestorDirectoryWithPackageJson(fileName); } - /*@internal*/ + /** @internal */ getPackageJsonsForAutoImport(rootDir?: string): readonly ProjectPackageJsonInfo[] { const packageJsons = this.getPackageJsonsVisibleToFile(combinePaths(this.currentDirectory, inferredTypesContainingFile), rootDir); this.packageJsonsForAutoImport = new Set(packageJsons.map(p => p.fileName)); return packageJsons; } - /* @internal */ + /** @internal */ getPackageJsonCache() { return this.projectService.packageJsonCache; } - /*@internal*/ + /** @internal */ getCachedExportInfoMap() { return this.exportMapCache ||= createCacheableExportInfoMap(this); } - /*@internal*/ + /** @internal */ clearCachedExportInfoMap() { this.exportMapCache?.clear(); } - /*@internal*/ + /** @internal */ getModuleSpecifierCache() { return this.moduleSpecifierCache; } - /*@internal*/ + /** @internal */ includePackageJsonAutoImports(): PackageJsonAutoImportPreference { if (this.projectService.includePackageJsonAutoImports() === PackageJsonAutoImportPreference.Off || !this.languageServiceEnabled || @@ -1835,7 +1840,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.projectService.includePackageJsonAutoImports(); } - /*@internal*/ + /** @internal */ getModuleResolutionHostForAutoImportProvider(): ModuleResolutionHost { if (this.program) { return { @@ -1852,7 +1857,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.projectService.host; } - /*@internal*/ + /** @internal */ getPackageJsonAutoImportProvider(): Program | undefined { if (this.autoImportProviderHost === false) { return undefined; @@ -1886,24 +1891,24 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo } } - /*@internal*/ + /** @internal */ private isDefaultProjectForOpenFiles(): boolean { return !!forEachEntry( this.projectService.openFiles, (_, fileName) => this.projectService.tryGetDefaultProjectForFile(toNormalizedPath(fileName)) === this); } - /*@internal*/ + /** @internal */ watchNodeModulesForPackageJsonChanges(directoryPath: string) { return this.projectService.watchPackageJsonsInNodeModules(this.toPath(directoryPath), this); } - /*@internal*/ + /** @internal */ getIncompleteCompletionsCache() { return this.projectService.getIncompleteCompletionsCache(); } - /*@internal*/ + /** @internal */ getNoDtsResolutionProject(rootFileNames: readonly string[]): Project { Debug.assert(this.projectService.serverMode === LanguageServiceMode.Semantic); if (!this.noDtsResolutionProject) { @@ -1935,7 +1940,7 @@ export abstract class Project implements LanguageServiceHost, ModuleResolutionHo return this.noDtsResolutionProject; } - /*@internal*/ + /** @internal */ private getCompilerOptionsForNoDtsResolutionProject() { return { ...this.getCompilerOptions(), @@ -2010,11 +2015,11 @@ export class InferredProject extends Project { /** this is canonical project root path */ readonly projectRootPath: string | undefined; - /*@internal*/ + /** @internal */ /** stored only if their is no projectRootPath and this isnt single inferred project */ readonly canonicalCurrentDirectory: string | undefined; - /*@internal*/ + /** @internal */ constructor( projectService: ProjectService, documentRegistry: DocumentRegistry, @@ -2063,7 +2068,7 @@ export class InferredProject extends Project { } } - /*@internal*/ + /** @internal */ isOrphan() { return !this.hasRoots(); } @@ -2109,7 +2114,7 @@ class AuxiliaryProject extends Project { return true; } - /*@internal*/ + /** @internal */ scheduleInvalidateResolutionsOfFailedLookupLocations(): void { // Invalidation will happen on-demand as part of updateGraph return; @@ -2117,10 +2122,10 @@ class AuxiliaryProject extends Project { } export class AutoImportProviderProject extends Project { - /*@internal*/ + /** @internal */ private static readonly maxDependencies = 10; - /*@internal*/ + /** @internal */ static getRootFileNames(dependencySelection: PackageJsonAutoImportPreference, hostProject: Project, moduleResolutionHost: ModuleResolutionHost, compilerOptions: CompilerOptions): string[] { if (!dependencySelection) { return ts.emptyArray; @@ -2240,7 +2245,7 @@ export class AutoImportProviderProject extends Project { } } - /*@internal*/ + /** @internal */ static readonly compilerOptionsOverrides: CompilerOptions = { diagnostics: false, skipLibCheck: true, @@ -2250,7 +2255,7 @@ export class AutoImportProviderProject extends Project { noLib: true, }; - /*@internal*/ + /** @internal */ static create(dependencySelection: PackageJsonAutoImportPreference, hostProject: Project, moduleResolutionHost: ModuleResolutionHost, documentRegistry: DocumentRegistry): AutoImportProviderProject | undefined { if (dependencySelection === PackageJsonAutoImportPreference.Off) { return undefined; @@ -2271,7 +2276,7 @@ export class AutoImportProviderProject extends Project { private rootFileNames: string[] | undefined; - /*@internal*/ + /** @internal */ constructor( private hostProject: Project, initialRootNames: string[], @@ -2295,7 +2300,7 @@ export class AutoImportProviderProject extends Project { this.getParsedCommandLine = maybeBind(this.hostProject, this.hostProject.getParsedCommandLine); } - /*@internal*/ + /** @internal */ isEmpty() { return !some(this.rootFileNames); } @@ -2324,7 +2329,7 @@ export class AutoImportProviderProject extends Project { return hasSameSetOfFiles; } - /*@internal*/ + /** @internal */ scheduleInvalidateResolutionsOfFailedLookupLocations(): void { // Invalidation will happen on-demand as part of updateGraph return; @@ -2347,12 +2352,12 @@ export class AutoImportProviderProject extends Project { throw new Error("AutoImportProviderProject language service should never be used. To get the program, use `project.getCurrentProgram()`."); } - /*@internal*/ + /** @internal */ onAutoImportProviderSettingsChanged(): never { throw new Error("AutoImportProviderProject is an auto import provider; use `markAsDirty()` instead."); } - /*@internal*/ + /** @internal */ onPackageJsonChange(): never { throw new Error("package.json changes should be notified on an AutoImportProvider's host project"); } @@ -2365,7 +2370,7 @@ export class AutoImportProviderProject extends Project { return this.hostProject.getProjectReferences(); } - /*@internal*/ + /** @internal */ includePackageJsonAutoImports() { return PackageJsonAutoImportPreference.Off; } @@ -2374,12 +2379,12 @@ export class AutoImportProviderProject extends Project { return { enable: false }; } - /*@internal*/ + /** @internal */ getSymlinkCache() { return this.hostProject.getSymlinkCache(); } - /*@internal*/ + /** @internal */ getModuleResolutionCache() { return this.hostProject.getCurrentProgram()?.getModuleResolutionCache(); } @@ -2391,15 +2396,15 @@ export class AutoImportProviderProject extends Project { * Otherwise it will create an InferredProject. */ export class ConfiguredProject extends Project { - /* @internal */ + /** @internal */ pendingReload: ConfigFileProgramReloadLevel | undefined; - /* @internal */ + /** @internal */ pendingReloadReason: string | undefined; - /* @internal */ + /** @internal */ openFileWatchTriggered = new Map(); - /*@internal*/ + /** @internal */ canConfigFileJsonReportNoInputFiles = false; /** Ref count to the project when opened from external project */ @@ -2408,22 +2413,22 @@ export class ConfiguredProject extends Project { private projectReferences: readonly ProjectReference[] | undefined; /** Potential project references before the project is actually loaded (read config file) */ - /*@internal*/ + /** @internal */ potentialProjectReferences: Set | undefined; - /*@internal*/ + /** @internal */ projectOptions?: ProjectOptions | true; - /*@internal*/ + /** @internal */ isInitialLoadPending: () => boolean = returnTrue; - /*@internal*/ + /** @internal */ sendLoadingProjectFinish = false; - /*@internal*/ + /** @internal */ private compilerHost?: CompilerHost; - /*@internal*/ + /** @internal */ constructor(configFileName: NormalizedPath, readonly canonicalConfigFilePath: NormalizedPath, projectService: ProjectService, @@ -2443,22 +2448,22 @@ export class ConfiguredProject extends Project { ); } - /* @internal */ + /** @internal */ setCompilerHost(host: CompilerHost) { this.compilerHost = host; } - /* @internal */ + /** @internal */ getCompilerHost(): CompilerHost | undefined { return this.compilerHost; } - /* @internal */ + /** @internal */ useSourceOfProjectReferenceRedirect() { return this.languageServiceEnabled; } - /* @internal */ + /** @internal */ getParsedCommandLine(fileName: string) { const configFileName = asNormalizedPath(normalizePath(fileName)); const canonicalConfigFilePath = asNormalizedPath(this.projectService.toCanonicalFileName(configFileName)); @@ -2476,12 +2481,12 @@ export class ConfiguredProject extends Project { return configFileExistenceInfo.exists ? configFileExistenceInfo.config!.parsedCommandLine : undefined; } - /* @internal */ + /** @internal */ onReleaseParsedCommandLine(fileName: string) { this.releaseParsedConfig(asNormalizedPath(this.projectService.toCanonicalFileName(asNormalizedPath(normalizePath(fileName))))); } - /* @internal */ + /** @internal */ private releaseParsedConfig(canonicalConfigFilePath: NormalizedPath) { this.projectService.stopWatchingWildCards(canonicalConfigFilePath, this); this.projectService.releaseParsedConfig(canonicalConfigFilePath, this); @@ -2518,7 +2523,7 @@ export class ConfiguredProject extends Project { return result; } - /*@internal*/ + /** @internal */ getCachedDirectoryStructureHost() { return this.directoryStructureHost as CachedDirectoryStructureHost; } @@ -2536,26 +2541,26 @@ export class ConfiguredProject extends Project { this.potentialProjectReferences = undefined; } - /*@internal*/ + /** @internal */ setPotentialProjectReference(canonicalConfigPath: NormalizedPath) { Debug.assert(this.isInitialLoadPending()); (this.potentialProjectReferences || (this.potentialProjectReferences = new Set())).add(canonicalConfigPath); } - /*@internal*/ + /** @internal */ getResolvedProjectReferenceToRedirect(fileName: string): ResolvedProjectReference | undefined { const program = this.getCurrentProgram(); return program && program.getResolvedProjectReferenceToRedirect(fileName); } - /*@internal*/ + /** @internal */ forEachResolvedProjectReference( cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined ): T | undefined { return this.getCurrentProgram()?.forEachResolvedProjectReference(cb); } - /*@internal*/ + /** @internal */ enablePluginsWithOptions(options: CompilerOptions, pluginConfigOverrides: ESMap | undefined): void { this.plugins.length = 0; if (!options.plugins?.length && !this.projectService.globalPlugins.length) return; @@ -2609,23 +2614,23 @@ export class ConfiguredProject extends Project { super.close(); } - /* @internal */ + /** @internal */ addExternalProjectReference() { this.externalProjectRefCount++; } - /* @internal */ + /** @internal */ deleteExternalProjectReference() { this.externalProjectRefCount--; } - /* @internal */ + /** @internal */ isSolution() { return this.getRootFilesMap().size === 0 && !this.canConfigFileJsonReportNoInputFiles; } - /* @internal */ + /** @internal */ /** Find the configured project from the project references in project which contains the info directly */ getDefaultChildProjectFromProjectWithReferences(info: ScriptInfo) { return forEachResolvedProjectReferenceProject( @@ -2639,7 +2644,7 @@ export class ConfiguredProject extends Project { } /** Returns true if the project is needed by any of the open script info/external project */ - /* @internal */ + /** @internal */ hasOpenRef() { if (!!this.externalProjectRefCount) { return true; @@ -2676,7 +2681,7 @@ export class ConfiguredProject extends Project { ) || false; } - /*@internal*/ + /** @internal */ hasExternalProjectRef() { return !!this.externalProjectRefCount; } @@ -2685,7 +2690,7 @@ export class ConfiguredProject extends Project { return getEffectiveTypeRoots(this.getCompilationSettings(), this.directoryStructureHost) || []; } - /*@internal*/ + /** @internal */ updateErrorOnNoInputFiles(fileNames: string[]) { updateErrorForNoInputFiles(fileNames, this.getConfigFilePath(), this.getCompilerOptions().configFile!.configFileSpecs!, this.projectErrors!, this.canConfigFileJsonReportNoInputFiles); } @@ -2697,7 +2702,7 @@ export class ConfiguredProject extends Project { */ export class ExternalProject extends Project { excludedFiles: readonly NormalizedPath[] = []; - /*@internal*/ + /** @internal */ constructor(public externalProjectName: string, projectService: ProjectService, documentRegistry: DocumentRegistry, @@ -2732,17 +2737,17 @@ export class ExternalProject extends Project { } } -/* @internal */ +/** @internal */ export function isInferredProject(project: Project): project is InferredProject { return project.projectKind === ProjectKind.Inferred; } -/* @internal */ +/** @internal */ export function isConfiguredProject(project: Project): project is ConfiguredProject { return project.projectKind === ProjectKind.Configured; } -/* @internal */ +/** @internal */ export function isExternalProject(project: Project): project is ExternalProject { return project.projectKind === ProjectKind.External; } diff --git a/src/server/protocol.ts b/src/server/protocol.ts index 420c3240e46a3..7d0c25f951a29 100644 --- a/src/server/protocol.ts +++ b/src/server/protocol.ts @@ -15,7 +15,7 @@ import { export const enum CommandTypes { JsxClosingTag = "jsxClosingTag", Brace = "brace", - /* @internal */ + /** @internal */ BraceFull = "brace-full", BraceCompletion = "braceCompletion", GetSpanOfEnclosingComment = "getSpanOfEnclosingComment", @@ -24,36 +24,36 @@ export const enum CommandTypes { /** @deprecated Prefer CompletionInfo -- see comment on CompletionsResponse */ Completions = "completions", CompletionInfo = "completionInfo", - /* @internal */ + /** @internal */ CompletionsFull = "completions-full", CompletionDetails = "completionEntryDetails", - /* @internal */ + /** @internal */ CompletionDetailsFull = "completionEntryDetails-full", CompileOnSaveAffectedFileList = "compileOnSaveAffectedFileList", CompileOnSaveEmitFile = "compileOnSaveEmitFile", Configure = "configure", Definition = "definition", - /* @internal */ + /** @internal */ DefinitionFull = "definition-full", DefinitionAndBoundSpan = "definitionAndBoundSpan", - /* @internal */ + /** @internal */ DefinitionAndBoundSpanFull = "definitionAndBoundSpan-full", Implementation = "implementation", - /* @internal */ + /** @internal */ ImplementationFull = "implementation-full", - /* @internal */ + /** @internal */ EmitOutput = "emit-output", Exit = "exit", FileReferences = "fileReferences", - /* @internal */ + /** @internal */ FileReferencesFull = "fileReferences-full", Format = "format", Formatonkey = "formatonkey", - /* @internal */ + /** @internal */ FormatFull = "format-full", - /* @internal */ + /** @internal */ FormatonkeyFull = "formatonkey-full", - /* @internal */ + /** @internal */ FormatRangeFull = "formatRange-full", Geterr = "geterr", GeterrForProject = "geterrForProject", @@ -61,34 +61,34 @@ export const enum CommandTypes { SyntacticDiagnosticsSync = "syntacticDiagnosticsSync", SuggestionDiagnosticsSync = "suggestionDiagnosticsSync", NavBar = "navbar", - /* @internal */ + /** @internal */ NavBarFull = "navbar-full", Navto = "navto", - /* @internal */ + /** @internal */ NavtoFull = "navto-full", NavTree = "navtree", NavTreeFull = "navtree-full", /** @deprecated */ Occurrences = "occurrences", DocumentHighlights = "documentHighlights", - /* @internal */ + /** @internal */ DocumentHighlightsFull = "documentHighlights-full", Open = "open", Quickinfo = "quickinfo", - /* @internal */ + /** @internal */ QuickinfoFull = "quickinfo-full", References = "references", - /* @internal */ + /** @internal */ ReferencesFull = "references-full", Reload = "reload", Rename = "rename", - /* @internal */ + /** @internal */ RenameInfoFull = "rename-full", - /* @internal */ + /** @internal */ RenameLocationsFull = "renameLocations-full", Saveto = "saveto", SignatureHelp = "signatureHelp", - /* @internal */ + /** @internal */ SignatureHelpFull = "signatureHelp-full", FindSourceDefinition = "findSourceDefinition", Status = "status", @@ -99,65 +99,65 @@ export const enum CommandTypes { OpenExternalProject = "openExternalProject", OpenExternalProjects = "openExternalProjects", CloseExternalProject = "closeExternalProject", - /* @internal */ + /** @internal */ SynchronizeProjectList = "synchronizeProjectList", - /* @internal */ + /** @internal */ ApplyChangedToOpenFiles = "applyChangedToOpenFiles", UpdateOpen = "updateOpen", - /* @internal */ + /** @internal */ EncodedSyntacticClassificationsFull = "encodedSyntacticClassifications-full", - /* @internal */ + /** @internal */ EncodedSemanticClassificationsFull = "encodedSemanticClassifications-full", - /* @internal */ + /** @internal */ Cleanup = "cleanup", GetOutliningSpans = "getOutliningSpans", - /* @internal */ + /** @internal */ GetOutliningSpansFull = "outliningSpans", // Full command name is different for backward compatibility purposes TodoComments = "todoComments", Indentation = "indentation", DocCommentTemplate = "docCommentTemplate", - /* @internal */ + /** @internal */ CompilerOptionsDiagnosticsFull = "compilerOptionsDiagnostics-full", - /* @internal */ + /** @internal */ NameOrDottedNameSpan = "nameOrDottedNameSpan", - /* @internal */ + /** @internal */ BreakpointStatement = "breakpointStatement", CompilerOptionsForInferredProjects = "compilerOptionsForInferredProjects", GetCodeFixes = "getCodeFixes", - /* @internal */ + /** @internal */ GetCodeFixesFull = "getCodeFixes-full", GetCombinedCodeFix = "getCombinedCodeFix", - /* @internal */ + /** @internal */ GetCombinedCodeFixFull = "getCombinedCodeFix-full", ApplyCodeActionCommand = "applyCodeActionCommand", GetSupportedCodeFixes = "getSupportedCodeFixes", GetApplicableRefactors = "getApplicableRefactors", GetEditsForRefactor = "getEditsForRefactor", - /* @internal */ + /** @internal */ GetEditsForRefactorFull = "getEditsForRefactor-full", OrganizeImports = "organizeImports", - /* @internal */ + /** @internal */ OrganizeImportsFull = "organizeImports-full", GetEditsForFileRename = "getEditsForFileRename", - /* @internal */ + /** @internal */ GetEditsForFileRenameFull = "getEditsForFileRename-full", ConfigurePlugin = "configurePlugin", SelectionRange = "selectionRange", - /* @internal */ + /** @internal */ SelectionRangeFull = "selectionRange-full", ToggleLineComment = "toggleLineComment", - /* @internal */ + /** @internal */ ToggleLineCommentFull = "toggleLineComment-full", ToggleMultilineComment = "toggleMultilineComment", - /* @internal */ + /** @internal */ ToggleMultilineCommentFull = "toggleMultilineComment-full", CommentSelection = "commentSelection", - /* @internal */ + /** @internal */ CommentSelectionFull = "commentSelection-full", UncommentSelection = "uncommentSelection", - /* @internal */ + /** @internal */ UncommentSelectionFull = "uncommentSelection-full", PrepareCallHierarchy = "prepareCallHierarchy", ProvideCallHierarchyIncomingCalls = "provideCallHierarchyIncomingCalls", @@ -402,16 +402,18 @@ export interface OutliningSpansResponse extends Response { /** * Request to obtain outlining spans in file. + * + * @internal */ -/* @internal */ export interface OutliningSpansRequestFull extends FileRequest { command: CommandTypes.GetOutliningSpansFull; } /** * Response to OutliningSpansRequest request. + * + * @internal */ -/* @internal */ export interface OutliningSpansResponseFull extends Response { body?: ts.OutliningSpan[]; } @@ -560,8 +562,9 @@ export interface FileLocationRequestArgs extends FileRequestArgs { /** * Position (can be specified instead of line/offset pair) + * + * @internal */ - /* @internal */ position?: number; } @@ -758,8 +761,9 @@ export interface FileRangeRequestArgs extends FileRequestArgs { /** * Position (can be specified instead of line/offset pair) + * + * @internal */ - /* @internal */ startPosition?: number; /** @@ -774,8 +778,9 @@ export interface FileRangeRequestArgs extends FileRequestArgs { /** * Position (can be specified instead of line/offset pair) + * + * @internal */ - /* @internal */ endPosition?: number; } @@ -837,16 +842,18 @@ export interface GetSupportedCodeFixesResponse extends Response { /** * A request to get encoded Syntactic classifications for a span in the file + * + * @internal */ -/** @internal */ export interface EncodedSyntacticClassificationsRequest extends FileRequest { arguments: EncodedSyntacticClassificationsRequestArgs; } /** * Arguments for EncodedSyntacticClassificationsRequest request. + * + * @internal */ -/** @internal */ export interface EncodedSyntacticClassificationsRequestArgs extends FileRequestArgs { /** * Start position of the span. @@ -1264,13 +1271,13 @@ export interface RenameRequest extends FileLocationRequest { arguments: RenameRequestArgs; } -/* @internal */ +/** @internal */ export interface RenameFullRequest extends FileLocationRequest { readonly command: CommandTypes.RenameLocationsFull; readonly arguments: RenameRequestArgs; } -/* @internal */ +/** @internal */ export interface RenameFullResponse extends Response { readonly body: readonly RenameLocation[]; } @@ -1424,8 +1431,9 @@ export type ExternalProjectCompilerOptions = CompilerOptions & CompileOnSaveMixi /** * Contains information about current project version + * + * @internal */ -/* @internal */ export interface ProjectVersionInfo { /** * Project name @@ -1494,8 +1502,9 @@ export interface ProjectChanges { * if files is set - then this is the entire set of files in the project * if changes is set - then this is the set of changes that should be applied to existing project * otherwise - assume that nothing is changed + * + * @internal */ -/* @internal */ export interface ProjectFiles { /** * Information about project verison @@ -1515,8 +1524,9 @@ export interface ProjectFiles { /** * Combines project information with project level errors. + * + * @internal */ -/* @internal */ export interface ProjectFilesWithDiagnostics extends ProjectFiles { /** * List of errors in project @@ -1526,8 +1536,9 @@ export interface ProjectFilesWithDiagnostics extends ProjectFiles { /** * Represents set of changes in open file + * + * @internal */ -/* @internal */ export interface ChangedOpenFile { /** * Name of file @@ -1779,16 +1790,18 @@ export interface CloseExternalProjectResponse extends Response { /** * Request to check if given list of projects is up-to-date and synchronize them if necessary + * + * @internal */ -/* @internal */ export interface SynchronizeProjectListRequest extends Request { arguments: SynchronizeProjectListRequestArgs; } /** * Arguments to SynchronizeProjectListRequest + * + * @internal */ -/* @internal */ export interface SynchronizeProjectListRequestArgs { /** * List of last known projects @@ -1803,16 +1816,18 @@ export interface SynchronizeProjectListRequestArgs { /** * Request to synchronize list of open files with the client + * + * @internal */ -/* @internal */ export interface ApplyChangedToOpenFilesRequest extends Request { arguments: ApplyChangedToOpenFilesRequestArgs; } /** * Arguments to ApplyChangedToOpenFilesRequest + * + * @internal */ -/* @internal */ export interface ApplyChangedToOpenFilesRequestArgs { /** * List of newly open files @@ -2055,8 +2070,9 @@ export interface FormatRequestArgs extends FileLocationRequestArgs { /** * End position of the range for which to format text in file. + * + * @internal */ - /* @internal */ endPosition?: number; /** * Format options to be used. @@ -2968,7 +2984,7 @@ export interface LargeFileReferencedEventBody { maxFileSize: number; } -/*@internal*/ +/** @internal */ export type AnyEvent = RequestCompletedEvent | DiagnosticEvent diff --git a/src/server/scriptInfo.ts b/src/server/scriptInfo.ts index aa160e17d2d1c..25c77fe3d4dc4 100644 --- a/src/server/scriptInfo.ts +++ b/src/server/scriptInfo.ts @@ -17,7 +17,7 @@ export interface ScriptInfoVersion { text: number; } -/* @internal */ +/** @internal */ export class TextStorage { version: ScriptInfoVersion; @@ -290,13 +290,13 @@ export function isDynamicFileName(fileName: NormalizedPath) { (stringContains(fileName, ":^") && !stringContains(fileName, directorySeparator)); } -/*@internal*/ +/** @internal */ export interface DocumentRegistrySourceFileCache { key: DocumentRegistryBucketKeyWithMode; sourceFile: SourceFile; } -/*@internal*/ +/** @internal */ export interface SourceMapFileWatcher { watcher: FileWatcher; sourceInfos?: Set; @@ -310,35 +310,35 @@ export class ScriptInfo { private formatSettings: FormatCodeSettings | undefined; private preferences: protocol.UserPreferences | undefined; - /* @internal */ + /** @internal */ fileWatcher: FileWatcher | undefined; private textStorage: TextStorage; - /*@internal*/ + /** @internal */ readonly isDynamic: boolean; - /*@internal*/ + /** @internal */ /** Set to real path if path is different from info.path */ private realpath: Path | undefined; - /*@internal*/ + /** @internal */ cacheSourceFile: DocumentRegistrySourceFileCache | undefined; - /*@internal*/ + /** @internal */ mTime?: number; - /*@internal*/ + /** @internal */ sourceFileLike?: SourceFileLike; - /*@internal*/ + /** @internal */ sourceMapFilePath?: Path | SourceMapFileWatcher | false; // Present on sourceMapFile info - /*@internal*/ + /** @internal */ declarationInfoPath?: Path; - /*@internal*/ + /** @internal */ sourceInfos?: Set; - /*@internal*/ + /** @internal */ documentPositionMapper?: DocumentPositionMapper | false; constructor( @@ -360,17 +360,17 @@ export class ScriptInfo { : getScriptKindFromFileName(fileName); } - /*@internal*/ + /** @internal */ getVersion() { return this.textStorage.version; } - /*@internal*/ + /** @internal */ getTelemetryFileSize() { return this.textStorage.getTelemetryFileSize(); } - /*@internal*/ + /** @internal */ public isDynamicOrHasMixedContent() { return this.hasMixedContent || this.isDynamic; } @@ -423,7 +423,7 @@ export class ScriptInfo { } } - /*@internal*/ + /** @internal */ getRealpathIfDifferent(): Path | undefined { return this.realpath && this.realpath !== this.path ? this.realpath : undefined; } @@ -592,7 +592,7 @@ export class ScriptInfo { this.host.writeFile(fileName, getSnapshotText(this.textStorage.getSnapshot())); } - /*@internal*/ + /** @internal */ delayReloadNonMixedContentFile() { Debug.assert(!this.isDynamicOrHasMixedContent()); this.textStorage.delayReloadFromFileIntoText(); @@ -614,7 +614,7 @@ export class ScriptInfo { return false; } - /*@internal*/ + /** @internal */ getAbsolutePositionAndLineText(line: number): AbsolutePositionAndLineText { return this.textStorage.getAbsolutePositionAndLineText(line); } @@ -634,7 +634,7 @@ export class ScriptInfo { return !forEach(this.containingProjects, p => !p.isOrphan()); } - /*@internal*/ + /** @internal */ isContainedByBackgroundProject() { return some( this.containingProjects, @@ -653,7 +653,7 @@ export class ScriptInfo { * @param offset 1 based index */ lineOffsetToPosition(line: number, offset: number): number; - /*@internal*/ + /** @internal */ lineOffsetToPosition(line: number, offset: number, allowEdits?: true): number; // eslint-disable-line @typescript-eslint/unified-signatures lineOffsetToPosition(line: number, offset: number, allowEdits?: true): number { return this.textStorage.lineOffsetToPosition(line, offset, allowEdits); @@ -670,12 +670,12 @@ export class ScriptInfo { return this.scriptKind === ScriptKind.JS || this.scriptKind === ScriptKind.JSX; } - /*@internal*/ + /** @internal */ getLineInfo(): LineInfo { return this.textStorage.getLineInfo(); } - /*@internal*/ + /** @internal */ closeSourceMapFileWatcher() { if (this.sourceMapFilePath && !isString(this.sourceMapFilePath)) { closeFileWatcherOf(this.sourceMapFilePath); diff --git a/src/server/session.ts b/src/server/session.ts index 1a3d38309f617..2b84b2188e5db 100644 --- a/src/server/session.ts +++ b/src/server/session.ts @@ -3531,7 +3531,7 @@ export interface HandlerResponse { responseRequired?: boolean; } -/* @internal */ // Exported only for tests +/** @internal */ // Exported only for tests export function getLocationInNewDocument(oldText: string, renameFilename: string, renameLocation: number, edits: readonly FileTextChanges[]): protocol.Location { const newText = applyEdits(oldText, renameFilename, edits); const { line, character } = computeLineAndCharacterOfPosition(computeLineStarts(newText), renameLocation); diff --git a/src/server/types.ts b/src/server/types.ts index 4f76ed311af00..3ebc7655948a5 100644 --- a/src/server/types.ts +++ b/src/server/types.ts @@ -21,6 +21,6 @@ export interface ServerHost extends System { gc?(): void; trace?(s: string): void; require?(initialPath: string, moduleName: string): ModuleImportResult; - /*@internal*/ + /** @internal */ importPlugin?(root: string, moduleName: string): Promise; } diff --git a/src/server/typingsCache.ts b/src/server/typingsCache.ts index ae47f2d76e20b..fa35a6842ee91 100644 --- a/src/server/typingsCache.ts +++ b/src/server/typingsCache.ts @@ -86,7 +86,7 @@ function unresolvedImportsChanged(imports1: SortedReadonlyArray | undefi return !arrayIsEqualTo(imports1, imports2); } -/*@internal*/ +/** @internal */ export class TypingsCache { private readonly perProjectCache = new Map(); diff --git a/src/server/utilities.ts b/src/server/utilities.ts index 03fb2ded566e5..95d2483593a85 100644 --- a/src/server/utilities.ts +++ b/src/server/utilities.ts @@ -106,8 +106,11 @@ export function indent(str: string): string { return indentStr + str.replace(/\n/g, indentStr); } -/** @internal */ -/** Put stringified JSON on the next line, indented. */ +/** + * Put stringified JSON on the next line, indented. + * + * @internal + */ export function stringifyIndented(json: {}): string { return indentStr + JSON.stringify(json); } diff --git a/src/server/utilitiesPublic.ts b/src/server/utilitiesPublic.ts index 758a8bce01e45..4af5e8394bede 100644 --- a/src/server/utilitiesPublic.ts +++ b/src/server/utilitiesPublic.ts @@ -102,7 +102,7 @@ export function createNormalizedPathMap(): NormalizedPathMap { }; } -/*@internal*/ +/** @internal */ export interface ProjectOptions { configHasExtendsProperty: boolean; /** @@ -122,12 +122,12 @@ export function makeInferredProjectName(counter: number): string { return `/dev/null/inferredProject${counter}*`; } -/*@internal*/ +/** @internal */ export function makeAutoImportProviderProjectName(counter: number): string { return `/dev/null/autoImportProviderProject${counter}*`; } -/*@internal*/ +/** @internal */ export function makeAuxiliaryProjectName(counter: number): string { return `/dev/null/auxiliaryProject${counter}*`; } diff --git a/src/services/breakpoints.ts b/src/services/breakpoints.ts index a39b675707331..5b823d698d651 100644 --- a/src/services/breakpoints.ts +++ b/src/services/breakpoints.ts @@ -13,9 +13,10 @@ import { TypeAssertion, VariableDeclaration, VariableDeclarationList, VariableStatement, WhileStatement, WithStatement, } from "./_namespaces/ts"; -/** @internal */ /** * Get the breakpoint span in given sourceFile + * + * @internal */ export function spanInSourceFileAtLocation(sourceFile: SourceFile, position: number) { // Cannot set breakpoint in dts file diff --git a/src/services/callHierarchy.ts b/src/services/callHierarchy.ts index 0c57afa9a2e6e..941cb68946a37 100644 --- a/src/services/callHierarchy.ts +++ b/src/services/callHierarchy.ts @@ -244,8 +244,11 @@ function findImplementationOrAllInitialDeclarations(typeChecker: TypeChecker, no return findAllInitialDeclarations(typeChecker, node) ?? node; } -/** @internal */ -/** Resolves the call hierarchy declaration for a node. */ +/** + * Resolves the call hierarchy declaration for a node. + * + * @internal + */ export function resolveCallHierarchyDeclaration(program: Program, location: Node): CallHierarchyDeclaration | CallHierarchyDeclaration[] | undefined { // A call hierarchy item must refer to either a SourceFile, Module Declaration, Class Static Block, or something intrinsically callable that has a name: // - Class Declarations @@ -315,8 +318,11 @@ export function resolveCallHierarchyDeclaration(program: Program, location: Node } } -/** @internal */ -/** Creates a `CallHierarchyItem` for a call hierarchy declaration. */ +/** + * Creates a `CallHierarchyItem` for a call hierarchy declaration. + * + * @internal + */ export function createCallHierarchyItem(program: Program, node: CallHierarchyDeclaration): CallHierarchyItem { const sourceFile = node.getSourceFile(); const name = getCallHierarchyItemName(program, node); @@ -365,8 +371,11 @@ function convertCallSiteGroupToIncomingCall(program: Program, entries: readonly return createCallHierarchyIncomingCall(createCallHierarchyItem(program, entries[0].declaration), map(entries, entry => createTextSpanFromRange(entry.range))); } -/** @internal */ -/** Gets the call sites that call into the provided call hierarchy declaration. */ +/** + * Gets the call sites that call into the provided call hierarchy declaration. + * + * @internal + */ export function getIncomingCalls(program: Program, declaration: CallHierarchyDeclaration, cancellationToken: CancellationToken): CallHierarchyIncomingCall[] { // Source files and modules have no incoming calls. if (isSourceFile(declaration) || isModuleDeclaration(declaration) || isClassStaticBlockDeclaration(declaration)) { @@ -575,8 +584,11 @@ function convertCallSiteGroupToOutgoingCall(program: Program, entries: readonly return createCallHierarchyOutgoingCall(createCallHierarchyItem(program, entries[0].declaration), map(entries, entry => createTextSpanFromRange(entry.range))); } -/** @internal */ -/** Gets the call sites that call out of the provided call hierarchy declaration. */ +/** + * Gets the call sites that call out of the provided call hierarchy declaration. + * + * @internal + */ export function getOutgoingCalls(program: Program, declaration: CallHierarchyDeclaration): CallHierarchyOutgoingCall[] { if (declaration.flags & NodeFlags.Ambient || isMethodSignature(declaration)) { return []; diff --git a/src/services/classifier.ts b/src/services/classifier.ts index ef5dcf76ae51d..ebff8cc4473f5 100644 --- a/src/services/classifier.ts +++ b/src/services/classifier.ts @@ -467,7 +467,7 @@ function classFromKind(token: SyntaxKind): ClassificationType { } } -/* @internal */ +/** @internal */ export function getSemanticClassifications(typeChecker: TypeChecker, cancellationToken: CancellationToken, sourceFile: SourceFile, classifiableNames: ReadonlySet<__String>, span: TextSpan): ClassifiedSpan[] { return convertClassificationsToSpans(getEncodedSemanticClassifications(typeChecker, cancellationToken, sourceFile, classifiableNames, span)); } @@ -495,7 +495,7 @@ function checkForClassificationCancellation(cancellationToken: CancellationToken } } -/* @internal */ +/** @internal */ export function getEncodedSemanticClassifications(typeChecker: TypeChecker, cancellationToken: CancellationToken, sourceFile: SourceFile, classifiableNames: ReadonlySet<__String>, span: TextSpan): Classifications { const spans: number[] = []; sourceFile.forEachChild(function cb(node: Node): void { @@ -610,12 +610,12 @@ function convertClassificationsToSpans(classifications: Classifications): Classi return result; } -/* @internal */ +/** @internal */ export function getSyntacticClassifications(cancellationToken: CancellationToken, sourceFile: SourceFile, span: TextSpan): ClassifiedSpan[] { return convertClassificationsToSpans(getEncodedSyntacticClassifications(cancellationToken, sourceFile, span)); } -/* @internal */ +/** @internal */ export function getEncodedSyntacticClassifications(cancellationToken: CancellationToken, sourceFile: SourceFile, span: TextSpan): Classifications { const spanStart = span.start; const spanLength = span.length; diff --git a/src/services/classifier2020.ts b/src/services/classifier2020.ts index 7b8c7e1dbb980..5ffb74881c933 100644 --- a/src/services/classifier2020.ts +++ b/src/services/classifier2020.ts @@ -8,8 +8,6 @@ import { SyntaxKind, TextSpan, textSpanIntersectsWith, Type, TypeChecker, VariableDeclaration, } from "./_namespaces/ts"; -/** @internal */ - /** @internal */ export const enum TokenEncodingConsts { typeOffset = 8, @@ -26,8 +24,11 @@ export const enum TokenModifier { declaration, static, async, readonly, defaultLibrary, local } -/** @internal */ -/** This is mainly used internally for testing */ +/** + * This is mainly used internally for testing + * + * @internal + */ export function getSemanticClassifications(program: Program, cancellationToken: CancellationToken, sourceFile: SourceFile, span: TextSpan): ClassifiedSpan2020[] { const classifications = getEncodedSemanticClassifications(program, cancellationToken, sourceFile, span); diff --git a/src/services/codefixes/helpers.ts b/src/services/codefixes/helpers.ts index dacfd89765750..c54f6da012d3e 100644 --- a/src/services/codefixes/helpers.ts +++ b/src/services/codefixes/helpers.ts @@ -18,13 +18,14 @@ import { } from "../_namespaces/ts"; import { ImportAdder } from "../_namespaces/ts.codefix"; -/** @internal */ /** * Finds members of the resolved type that are missing in the class pointed to by class decl * and generates source code for the missing members. * @param possiblyMissingSymbols The collection of symbols to filter and then get insertions for. * @param importAdder If provided, type annotations will use identifier type references instead of ImportTypeNodes, and the missing imports will be added to the importAdder. * @returns Empty string iff there are no member insertions. + * + * @internal */ export function createMissingMemberNodes( classDeclaration: ClassLikeDeclaration, @@ -65,10 +66,11 @@ export const enum PreserveOptionalFlags { All = Method | Property } -/** @internal */ /** * `addClassElement` will not be called if we can't figure out a representation for `symbol` in `enclosingDeclaration`. * @param body If defined, this will be the body of the member node passed to `addClassElement`. Otherwise, the body will default to a stub. + * + * @internal */ export function addNewNodeForMemberSymbol( symbol: Symbol, @@ -729,11 +731,12 @@ export function findJsonProperty(obj: ObjectLiteralExpression, name: string): Pr return find(obj.properties, (p): p is PropertyAssignment => isPropertyAssignment(p) && !!p.name && isStringLiteral(p.name) && p.name.text === name); } -/** @internal */ /** * Given a type node containing 'import("./a").SomeType>', * returns an equivalent type reference node with any nested ImportTypeNodes also replaced * with type references, and a list of symbols that must be imported to use the type reference. + * + * @internal */ export function tryGetAutoImportableReferenceFromTypeNode(importTypeNode: TypeNode | undefined, scriptTarget: ScriptTarget) { let symbols: Symbol[] | undefined; diff --git a/src/services/codefixes/importFixes.ts b/src/services/codefixes/importFixes.ts index f07c1e33c94aa..b02eeed8f80f4 100644 --- a/src/services/codefixes/importFixes.ts +++ b/src/services/codefixes/importFixes.ts @@ -67,9 +67,10 @@ registerCodeFix({ }, }); -/** @internal */ /** * Computes multiple import additions to a file and writes them to a ChangeTracker. + * + * @internal */ export interface ImportAdder { hasFixes(): boolean; @@ -266,9 +267,10 @@ function createImportAdderWorker(sourceFile: SourceFile, program: Program, useAu } } -/** @internal */ /** * Computes module specifiers for multiple import additions to a file. + * + * @internal */ export interface ImportSpecifierResolver { getModuleSpecifierForBestExportInfo( @@ -886,10 +888,11 @@ function getUmdSymbol(token: Node, checker: TypeChecker): Symbol | undefined { : undefined; } -/** @internal */ /** * @param forceImportKeyword Indicates that the user has already typed `import`, so the result must start with `import`. * (In other words, do not allow `const x = require("...")` for JS files.) + * + * @internal */ export function getImportKind(importingFile: SourceFile, exportKind: ExportKind, compilerOptions: CompilerOptions, forceImportKeyword?: boolean): ImportKind { switch (exportKind) { diff --git a/src/services/completions.ts b/src/services/completions.ts index 9a4cc6a4bd634..3b41db679f975 100644 --- a/src/services/completions.ts +++ b/src/services/completions.ts @@ -100,7 +100,6 @@ export const SortText = { }, }; -/** @internal */ /** * Special values for `CompletionInfo['source']` used to disambiguate * completion items with the same `name`. (Each completion item must @@ -111,6 +110,8 @@ export const SortText = { * is the module specifier of the suggestion. To avoid collisions, * the values here should not be a module specifier we would ever * generate for an auto-import. + * + * @internal */ export enum CompletionSource { /** Completions that require `this.` insertion text */ diff --git a/src/services/documentHighlights.ts b/src/services/documentHighlights.ts index f6a5e2f5eabeb..fb049851355b7 100644 --- a/src/services/documentHighlights.ts +++ b/src/services/documentHighlights.ts @@ -18,7 +18,7 @@ export interface DocumentHighlights { highlightSpans: HighlightSpan[]; } -/* @internal */ +/** @internal */ export namespace DocumentHighlights { export function getDocumentHighlights(program: Program, cancellationToken: CancellationToken, sourceFile: SourceFile, position: number, sourceFilesToSearch: readonly SourceFile[]): DocumentHighlights[] | undefined { const node = getTouchingPropertyName(sourceFile, position); diff --git a/src/services/documentRegistry.ts b/src/services/documentRegistry.ts index d9197886cf043..7ca869b38b038 100644 --- a/src/services/documentRegistry.ts +++ b/src/services/documentRegistry.ts @@ -104,8 +104,9 @@ export interface DocumentRegistry { * @param fileName The name of the file to be released * @param compilationSettings The compilation settings used to acquire the file * @param scriptKind The script kind of the file to be released + * + * @deprecated pass scriptKind and impliedNodeFormat for correctness */ - /**@deprecated pass scriptKind and impliedNodeFormat for correctness */ releaseDocument(fileName: string, compilationSettings: CompilerOptions, scriptKind?: ScriptKind): void; /** * Informs the DocumentRegistry that a file is not needed any longer. @@ -124,13 +125,13 @@ export interface DocumentRegistry { releaseDocumentWithKey(path: Path, key: DocumentRegistryBucketKey, scriptKind?: ScriptKind): void; releaseDocumentWithKey(path: Path, key: DocumentRegistryBucketKey, scriptKind: ScriptKind, impliedNodeFormat: SourceFile["impliedNodeFormat"]): void; // eslint-disable-line @typescript-eslint/unified-signatures - /*@internal*/ + /** @internal */ getLanguageServiceRefCounts(path: Path, scriptKind: ScriptKind): [string, number | undefined][]; reportStats(): string; } -/*@internal*/ +/** @internal */ export interface ExternalDocumentCache { setDocument(key: DocumentRegistryBucketKeyWithMode, path: Path, sourceFile: SourceFile): void; getDocument(key: DocumentRegistryBucketKeyWithMode, path: Path): SourceFile | undefined; @@ -156,9 +157,9 @@ export function createDocumentRegistry(useCaseSensitiveFileNames?: boolean, curr return createDocumentRegistryInternal(useCaseSensitiveFileNames, currentDirectory); } -/*@internal*/ +/** @internal */ export type DocumentRegistryBucketKeyWithMode = string & { __documentRegistryBucketKeyWithMode: any; }; -/*@internal*/ +/** @internal */ export function createDocumentRegistryInternal(useCaseSensitiveFileNames?: boolean, currentDirectory = "", externalCache?: ExternalDocumentCache): DocumentRegistry { // Maps from compiler setting target (ES3, ES5, etc.) to all the cached documents we have // for those settings. diff --git a/src/services/exportAsModule.ts b/src/services/exportAsModule.ts index da2c68619ca4e..757f9f7cd34fe 100644 --- a/src/services/exportAsModule.ts +++ b/src/services/exportAsModule.ts @@ -3,7 +3,7 @@ import * as ts from "./_namespaces/ts"; // Here we expose the TypeScript services as an external module // so that it may be consumed easily like a node module. // @ts-ignore -/* @internal */ declare const module: { exports: {} }; +/** @internal */ declare const module: { exports: {} }; if (typeof module !== "undefined" && module.exports) { module.exports = ts; -} \ No newline at end of file +} diff --git a/src/services/findAllReferences.ts b/src/services/findAllReferences.ts index 1ccd8d74e0491..5ef8f6436b66e 100644 --- a/src/services/findAllReferences.ts +++ b/src/services/findAllReferences.ts @@ -638,8 +638,11 @@ function isWriteAccessForReference(node: Node): boolean { return !!decl && declarationIsWriteAccess(decl) || node.kind === SyntaxKind.DefaultKeyword || isWriteAccess(node); } -/** @internal */ -/** Whether a reference, `node`, is a definition of the `target` symbol */ +/** + * Whether a reference, `node`, is a definition of the `target` symbol + * + * @internal + */ export function isDeclarationOfSymbol(node: Node, target: Symbol | undefined): boolean { if (!target) return false; const source = getDeclarationFromName(node) || @@ -712,8 +715,11 @@ function declarationIsWriteAccess(decl: Declaration): boolean { } } -/** @internal */ -/** Encapsulates the core find-all-references algorithm. */ +/** + * Encapsulates the core find-all-references algorithm. + * + * @internal + */ export namespace Core { /** Core find-all-references algorithm. Handles special cases before delegating to `getReferencedSymbolsForSymbol`. */ export function getReferencedSymbolsForNode(position: number, node: Node, program: Program, sourceFiles: readonly SourceFile[], cancellationToken: CancellationToken, options: Options = {}, sourceFilesSet: ReadonlySet = new Set(sourceFiles.map(f => f.fileName))): readonly SymbolAndEntries[] | undefined { diff --git a/src/services/formatting/formatting.ts b/src/services/formatting/formatting.ts index b3913f66ed82f..0d53a1474d57a 100644 --- a/src/services/formatting/formatting.ts +++ b/src/services/formatting/formatting.ts @@ -1316,9 +1316,9 @@ function formatSpanWorker( const enum LineAction { None, LineAdded, LineRemoved } -/** @internal */ /** - * @param precedingToken pass `null` if preceding token was already computed and result was `undefined`. + * + * @internal */ export function getRangeOfEnclosingComment( sourceFile: SourceFile, diff --git a/src/services/globalThisShim.ts b/src/services/globalThisShim.ts index c7bc8a28e1f16..9a8978bdb2644 100644 --- a/src/services/globalThisShim.ts +++ b/src/services/globalThisShim.ts @@ -7,7 +7,7 @@ import { TypeScriptServicesFactory, versionMajorMinor } from "./_namespaces/ts"; // #region The polyfill starts here. /* eslint-disable no-var */ -/* @internal */ +/** @internal */ declare global { // Module transform: converted from ambient declaration /** @internal */ @@ -62,4 +62,4 @@ if (typeof process === "undefined" || process.browser) { //@ts-ignore globalThis.toolsVersion = versionMajorMinor; -} \ No newline at end of file +} diff --git a/src/services/goToDefinition.ts b/src/services/goToDefinition.ts index fe14c8cc23563..1a8ebd80f4843 100644 --- a/src/services/goToDefinition.ts +++ b/src/services/goToDefinition.ts @@ -424,8 +424,11 @@ function getDefinitionFromSymbol(typeChecker: TypeChecker, symbol: Symbol, node: } } -/** @internal */ -/** Creates a DefinitionInfo from a Declaration, using the declaration's name if possible. */ +/** + * Creates a DefinitionInfo from a Declaration, using the declaration's name if possible. + * + * @internal + */ export function createDefinitionInfo(declaration: Declaration, checker: TypeChecker, symbol: Symbol, node: Node, unverified?: boolean, failedAliasResolution?: boolean): DefinitionInfo { const symbolName = checker.symbolToString(symbol); // Do not get scoped name, just the name of the symbol const symbolKind = SymbolDisplay.getSymbolKind(checker, symbol, node); diff --git a/src/services/importTracker.ts b/src/services/importTracker.ts index 21d318d2b54cb..33b2162189449 100644 --- a/src/services/importTracker.ts +++ b/src/services/importTracker.ts @@ -29,8 +29,11 @@ export interface ImportsResult { /** @internal */ export type ImportTracker = (exportSymbol: Symbol, exportInfo: ExportInfo, isForRename: boolean) => ImportsResult; -/** @internal */ -/** Creates the imports map and returns an ImportTracker that uses it. Call this lazily to avoid calling `getDirectImportsMap` unnecessarily. */ +/** + * Creates the imports map and returns an ImportTracker that uses it. Call this lazily to avoid calling `getDirectImportsMap` unnecessarily. + * + * @internal + */ export function createImportTracker(sourceFiles: readonly SourceFile[], sourceFilesSet: ReadonlySet, checker: TypeChecker, cancellationToken: CancellationToken | undefined): ImportTracker { const allDirectImports = getDirectImportsMap(sourceFiles, checker, cancellationToken); return (exportSymbol, exportInfo, isForRename) => { @@ -39,8 +42,11 @@ export function createImportTracker(sourceFiles: readonly SourceFile[], sourceFi }; } -/** @internal */ -/** Info about an exported symbol to perform recursive search on. */ +/** + * Info about an exported symbol to perform recursive search on. + * + * @internal + */ export interface ExportInfo { exportingModuleSymbol: Symbol; exportKind: ExportKind; @@ -479,13 +485,14 @@ export interface ExportedSymbol { exportInfo: ExportInfo; } -/** @internal */ /** * Given a local reference, we might notice that it's an import/export and recursively search for references of that. * If at an import, look locally for the symbol it imports. * If at an export, look for all imports of it. * This doesn't handle export specifiers; that is done in `getReferencesAtExportSpecifier`. * @param comingFromExport If we are doing a search for all exports, don't bother looking backwards for the imported symbol, since that's the reason we're here. + * + * @internal */ export function getImportOrExportSymbol(node: Node, symbol: Symbol, checker: TypeChecker, comingFromExport: boolean): ImportedSymbol | ExportedSymbol | undefined { return comingFromExport ? getExport() : getExport() || getImport(); diff --git a/src/services/jsDoc.ts b/src/services/jsDoc.ts index a8335e8e77589..b6b7ba77b0cbe 100644 --- a/src/services/jsDoc.ts +++ b/src/services/jsDoc.ts @@ -337,7 +337,6 @@ export function getJSDocParameterNameCompletionDetails(name: string): Completion }; } -/** @internal */ /** * Checks if position points to a valid position to add JSDoc comments, and if so, * returns the appropriate template. Otherwise returns an empty string. @@ -360,6 +359,8 @@ export function getJSDocParameterNameCompletionDetails(name: string): Completion * @param fileName The file in which to perform the check. * @param position The (character-indexed) position in the file where the check should * be performed. + * + * @internal */ export function getDocCommentTemplateAtPosition(newLine: string, sourceFile: SourceFile, position: number, options?: DocCommentTemplateOptions): TextInsertion | undefined { const tokenAtPos = getTokenAtPosition(sourceFile, position); diff --git a/src/services/organizeImports.ts b/src/services/organizeImports.ts index d5cf85d076cfe..7dfb4558e1c30 100644 --- a/src/services/organizeImports.ts +++ b/src/services/organizeImports.ts @@ -10,12 +10,13 @@ import { tryCast, UserPreferences, } from "./_namespaces/ts"; -/** @internal */ /** * Organize imports by: * 1) Removing unused imports * 2) Coalescing imports from the same module * 3) Sorting imports + * + * @internal */ export function organizeImports( sourceFile: SourceFile, @@ -244,9 +245,10 @@ function getExternalModuleName(specifier: Expression) { } // Internal for testing -/** @internal */ /** * @param importGroup a list of ImportDeclarations, all with the same module name. + * + * @internal */ export function coalesceImports(importGroup: readonly ImportDeclaration[]) { if (importGroup.length === 0) { @@ -385,9 +387,10 @@ function getCategorizedImports(importGroup: readonly ImportDeclaration[]) { } // Internal for testing -/** @internal */ /** * @param exportGroup a list of ExportDeclarations, all with the same module name. + * + * @internal */ export function coalesceExports(exportGroup: readonly ExportDeclaration[]) { if (exportGroup.length === 0) { @@ -484,8 +487,11 @@ export function compareImportOrExportSpecifiers the refactor you want const refactors = new Map(); -/** @internal */ -/** @param name An unique code associated with each refactor. Does not have to be human-readable. */ +/** + * @param name An unique code associated with each refactor. Does not have to be human-readable. + * + * @internal + */ export function registerRefactor(name: string, refactor: Refactor) { refactors.set(name, refactor); } diff --git a/src/services/refactors/extractSymbol.ts b/src/services/refactors/extractSymbol.ts index 5658571535987..90bd6ed39a50a 100644 --- a/src/services/refactors/extractSymbol.ts +++ b/src/services/refactors/extractSymbol.ts @@ -49,10 +49,11 @@ registerRefactor(refactorName, { getAvailableActions: getRefactorActionsToExtractSymbol, }); -/** @internal */ /** * Compute the associated code actions * Exported for tests. + * + * @internal */ export function getRefactorActionsToExtractSymbol(context: RefactorContext): readonly ApplicableRefactorInfo[] { const requestedRefactor = context.kind; @@ -196,8 +197,11 @@ export function getRefactorActionsToExtractSymbol(context: RefactorContext): rea } } -/* Exported for tests */ -/** @internal */ +/** + * Exported for tests + * + * @internal + */ export function getRefactorEditsToExtractSymbol(context: RefactorContext, actionName: string): RefactorEditInfo | undefined { const rangeToExtract = getRangeToExtract(context.file, getRefactorContextSpan(context)); const targetRange = rangeToExtract.targetRange!; // TODO:GH#18217 @@ -292,14 +296,15 @@ type RangeToExtract = { */ type Scope = FunctionLikeDeclaration | SourceFile | ModuleBlock | ClassLikeDeclaration; -/** @internal */ +// exported only for tests /** * getRangeToExtract takes a span inside a text file and returns either an expression or an array * of statements representing the minimum set of nodes needed to extract the entire span. This * process may fail, in which case a set of errors is returned instead. These errors are shown to * users if they have the provideRefactorNotApplicableReason option set. + * + * @internal */ -// exported only for tests export function getRangeToExtract(sourceFile: SourceFile, span: TextSpan, invoked = true): RangeToExtract { const { length } = span; if (length === 0 && !invoked) { diff --git a/src/services/refactors/helpers.ts b/src/services/refactors/helpers.ts index 24ffc608fa727..acafb54f1e36a 100644 --- a/src/services/refactors/helpers.ts +++ b/src/services/refactors/helpers.ts @@ -1,23 +1,27 @@ -/** @internal */ + /** * Returned by refactor functions when some error message needs to be surfaced to users. + * + * @internal */ export interface RefactorErrorInfo { error: string; } -/** @internal */ /** * Checks if some refactor info has refactor error info. + * + * @internal */ export function isRefactorErrorInfo(info: unknown): info is RefactorErrorInfo { return (info as RefactorErrorInfo).error !== undefined; } -/** @internal */ /** * Checks if string "known" begins with string "requested". * Used to match requested kinds with a known kind. + * + * @internal */ export function refactorKindBeginsWith(known: string, requested: string | undefined): boolean { if(!requested) return true; diff --git a/src/services/services.ts b/src/services/services.ts index 4588c64ea9bc0..10a1299bcc15e 100644 --- a/src/services/services.ts +++ b/src/services/services.ts @@ -473,7 +473,7 @@ class IdentifierObject extends TokenOrIdentifierObject implements Identifier { _unaryExpressionBrand: any; _expressionBrand: any; _declarationBrand: any; - /*@internal*/typeArguments!: NodeArray; + /** @internal */typeArguments!: NodeArray; constructor(_kind: SyntaxKind.Identifier, pos: number, end: number) { super(pos, end); } @@ -995,12 +995,12 @@ function getServicesObjectAllocator(): ObjectAllocator { /// Language Service -/* @internal */ +/** @internal */ export interface DisplayPartsSymbolWriter extends EmitTextWriter { displayParts(): SymbolDisplayPart[]; } -/* @internal */ +/** @internal */ export function toEditorSettings(options: FormatCodeOptions | FormatCodeSettings): FormatCodeSettings; export function toEditorSettings(options: EditorOptions | EditorSettings): EditorSettings; export function toEditorSettings(optionsAsMap: MapLike): MapLike { @@ -1194,8 +1194,11 @@ class CancellationTokenObject implements CancellationToken { } } -/* @internal */ -/** A cancellation that throttles calls to the host */ +/** + * A cancellation that throttles calls to the host + * + * @internal + */ export class ThrottledCancellationToken implements CancellationToken { // Store when we last tried to cancel. Checking cancellation can be expensive (as we have // to marshall over to the host layer). So we only bother actually checking once enough @@ -2798,8 +2801,11 @@ export function createLanguageService( return ls; } -/* @internal */ -/** Names in the name table are escaped, so an identifier `__foo` will have a name table entry `___foo`. */ +/** + * Names in the name table are escaped, so an identifier `__foo` will have a name table entry `___foo`. + * + * @internal + */ export function getNameTable(sourceFile: SourceFile): UnderscoreEscapedMap { if (!sourceFile.nameTable) { initializeNameTable(sourceFile); @@ -2844,8 +2850,9 @@ function literalIsName(node: StringLiteralLike | NumericLiteral): boolean { /** * Returns the containing object literal property declaration given a possible name node, e.g. "a" in x = { "a": 1 } + * + * @internal */ -/* @internal */ export function getContainingObjectLiteralElement(node: Node): ObjectLiteralElementWithName | undefined { const element = getContainingObjectLiteralElementWorker(node); return element && (isObjectLiteralExpression(element.parent) || isJsxAttributes(element.parent)) ? element as ObjectLiteralElementWithName : undefined; @@ -2868,7 +2875,7 @@ function getContainingObjectLiteralElementWorker(node: Node): ObjectLiteralEleme return undefined; } -/* @internal */ +/** @internal */ export type ObjectLiteralElementWithName = ObjectLiteralElement & { name: PropertyName; parent: ObjectLiteralExpression | JsxAttributes }; function getSymbolAtLocationForQuickInfo(node: Node, checker: TypeChecker): Symbol | undefined { @@ -2883,8 +2890,11 @@ function getSymbolAtLocationForQuickInfo(node: Node, checker: TypeChecker): Symb return checker.getSymbolAtLocation(node); } -/** Gets all symbols for one property. Does not get symbols for every property. */ -/* @internal */ +/** + * Gets all symbols for one property. Does not get symbols for every property. + * + * @internal + */ export function getPropertySymbolsFromContextualType(node: ObjectLiteralElementWithName, checker: TypeChecker, contextualType: Type, unionSymbolOk: boolean): readonly Symbol[] { const name = getNameFromPropertyName(node.name); if (!name) return emptyArray; diff --git a/src/services/shims.ts b/src/services/shims.ts index b3ba7f3e8ab09..6303302620d7b 100644 --- a/src/services/shims.ts +++ b/src/services/shims.ts @@ -28,7 +28,7 @@ import { // limitations under the License. // -/* @internal */ +/** @internal */ let debugObjectHost: { CollectGarbage(): void } = (function (this: any) { // eslint-disable-line prefer-const return this; })(); @@ -74,8 +74,11 @@ export interface Logger { error(s: string): void; } -/** @internal */ -/** Public interface of the host of a language service shim instance. */ +/** + * Public interface of the host of a language service shim instance. + * + * @internal + */ export interface LanguageServiceShimHost extends Logger { getCompilationSettings(): string; @@ -103,8 +106,11 @@ export interface LanguageServiceShimHost extends Logger { directoryExists(directoryName: string): boolean; } -/** @internal */ -/** Public interface of the core-services host instance used in managed side */ +/** + * Public interface of the core-services host instance used in managed side + * + * @internal + */ export interface CoreServicesShimHost extends Logger { directoryExists(directoryName: string): boolean; fileExists(fileName: string): boolean; @@ -140,8 +146,11 @@ export interface ShimsFileReference { length: number; } -/** @internal */ -/** Public interface of a language service instance shim. */ +/** + * Public interface of a language service instance shim. + * + * @internal + */ export interface ShimFactory { registerShim(shim: Shim): void; unregisterShim(shim: Shim): void; diff --git a/src/services/sourcemaps.ts b/src/services/sourcemaps.ts index f954eea53b8ff..73079ef532e76 100644 --- a/src/services/sourcemaps.ts +++ b/src/services/sourcemaps.ts @@ -142,10 +142,11 @@ export function getSourceMapper(host: SourceMapperHost): SourceMapper { } } -/** @internal */ /** * string | undefined to contents of map file to create DocumentPositionMapper from it * DocumentPositionMapper | false to give back cached DocumentPositionMapper + * + * @internal */ export type ReadMapFile = (mapFileName: string, mapFileNameFromDts: string | undefined) => string | undefined | DocumentPositionMapper | false; diff --git a/src/services/textChanges.ts b/src/services/textChanges.ts index 0f3562715c517..2751851140903 100644 --- a/src/services/textChanges.ts +++ b/src/services/textChanges.ts @@ -110,7 +110,6 @@ function hasCommentsBeforeLineBreak(text: string, start: number) { return false; } -/** @internal */ /** * Usually node.pos points to a position immediately after the previous token. * If this position is used as a beginning of the span to remove - it might lead to removing the trailing trivia of the previous node, i.e: @@ -123,6 +122,8 @@ function hasCommentsBeforeLineBreak(text: string, start: number) { * By default when removing nodes we adjust start and end positions to respect specification of the trivia above. * If pos\end should be interpreted literally (that is, withouth including leading and trailing trivia), `leadingTriviaOption` should be set to `LeadingTriviaOption.Exclude` * and `trailingTriviaOption` to `TrailingTriviaOption.Exclude`. + * + * @internal */ export interface ConfigurableStartEnd extends ConfigurableStart, ConfigurableEnd {} @@ -1635,9 +1636,12 @@ namespace deleteDeclaration { } } -/** @internal */ -/** Warning: This deletes comments too. See `copyComments` in `convertFunctionToEs6Class`. */ // Exported for tests only! (TODO: improve tests to not need this) +/** + * Warning: This deletes comments too. See `copyComments` in `convertFunctionToEs6Class`. + * + * @internal + */ export function deleteNode(changes: ChangeTracker, sourceFile: SourceFile, node: Node, options: ConfigurableStartEnd = { leadingTriviaOption: LeadingTriviaOption.IncludeAll }): void { const startPosition = getAdjustedStartPosition(sourceFile, node, options); const endPosition = getAdjustedEndPosition(sourceFile, node, options); diff --git a/src/services/transpile.ts b/src/services/transpile.ts index d588995353023..47c881cae053f 100644 --- a/src/services/transpile.ts +++ b/src/services/transpile.ts @@ -127,8 +127,11 @@ export function transpile(input: string, compilerOptions?: CompilerOptions, file let commandLineOptionsStringToEnum: CommandLineOptionOfCustomType[]; -/** JS users may pass in string values for enum compiler options (such as ModuleKind), so convert. */ -/*@internal*/ +/** + * JS users may pass in string values for enum compiler options (such as ModuleKind), so convert. + * + * @internal + */ export function fixupCompilerOptions(options: CompilerOptions, diagnostics: Diagnostic[]): CompilerOptions { // Lazily create this value to fix module loading errors. commandLineOptionsStringToEnum = commandLineOptionsStringToEnum || diff --git a/src/services/types.ts b/src/services/types.ts index eb6efd686df6c..044ac4132caee 100644 --- a/src/services/types.ts +++ b/src/services/types.ts @@ -15,10 +15,10 @@ declare module "../compiler/types" { getChildCount(sourceFile?: SourceFile): number; getChildAt(index: number, sourceFile?: SourceFile): Node; getChildren(sourceFile?: SourceFile): Node[]; - /* @internal */ + /** @internal */ getChildren(sourceFile?: SourceFileLike): Node[]; // eslint-disable-line @typescript-eslint/unified-signatures getStart(sourceFile?: SourceFile, includeJsDocComment?: boolean): number; - /* @internal */ + /** @internal */ getStart(sourceFile?: SourceFileLike, includeJsDocComment?: boolean): number; // eslint-disable-line @typescript-eslint/unified-signatures getFullStart(): number; getEnd(): number; @@ -28,10 +28,10 @@ declare module "../compiler/types" { getFullText(sourceFile?: SourceFile): string; getText(sourceFile?: SourceFile): string; getFirstToken(sourceFile?: SourceFile): Node | undefined; - /* @internal */ + /** @internal */ getFirstToken(sourceFile?: SourceFileLike): Node | undefined; // eslint-disable-line @typescript-eslint/unified-signatures getLastToken(sourceFile?: SourceFile): Node | undefined; - /* @internal */ + /** @internal */ getLastToken(sourceFile?: SourceFileLike): Node | undefined; // eslint-disable-line @typescript-eslint/unified-signatures // See ts.forEachChild for documentation. forEachChild(cbNode: (node: Node) => T | undefined, cbNodeArray?: (nodes: NodeArray) => T | undefined): T | undefined; @@ -61,10 +61,10 @@ declare module "../compiler/types" { getName(): string; getDeclarations(): Declaration[] | undefined; getDocumentationComment(typeChecker: TypeChecker | undefined): SymbolDisplayPart[]; - /* @internal */ + /** @internal */ getContextualDocumentationComment(context: Node | undefined, checker: TypeChecker | undefined): SymbolDisplayPart[] getJsDocTags(checker?: TypeChecker): JSDocTagInfo[]; - /* @internal */ + /** @internal */ getContextualJsDocTags(context: Node | undefined, checker: TypeChecker | undefined): JSDocTagInfo[]; } } @@ -83,8 +83,8 @@ declare module "../compiler/types" { getNumberIndexType(): Type | undefined; getBaseTypes(): BaseType[] | undefined; getNonNullableType(): Type; - /*@internal*/ getNonOptionalType(): Type; - /*@internal*/ isNullableType(): boolean; + /** @internal */ getNonOptionalType(): Type; + /** @internal */ isNullableType(): boolean; getConstraint(): Type | undefined; getDefault(): Type | undefined; @@ -124,11 +124,11 @@ declare module "../compiler/types" { declare module "../compiler/types" { // Module transform: converted from interface augmentation export interface SourceFile { - /* @internal */ version: string; - /* @internal */ scriptSnapshot: IScriptSnapshot | undefined; - /* @internal */ nameTable: UnderscoreEscapedMap | undefined; + /** @internal */ version: string; + /** @internal */ scriptSnapshot: IScriptSnapshot | undefined; + /** @internal */ nameTable: UnderscoreEscapedMap | undefined; - /* @internal */ getNamedDeclarations(): ESMap; + /** @internal */ getNamedDeclarations(): ESMap; getLineAndCharacterOfPosition(pos: number): LineAndCharacter; getLineEndOfPosition(pos: number): number; @@ -136,7 +136,7 @@ declare module "../compiler/types" { getPositionOfLineAndCharacter(line: number, character: number): number; update(newText: string, textChangeRange: TextChangeRange): SourceFile; - /* @internal */ sourceMapper?: DocumentPositionMapper; + /** @internal */ sourceMapper?: DocumentPositionMapper; } } @@ -226,7 +226,7 @@ export interface InstallPackageOptions { packageName: string; } -/* @internal */ +/** @internal */ export const enum PackageJsonDependencyGroup { Dependencies = 1 << 0, DevDependencies = 1 << 1, @@ -235,7 +235,7 @@ export const enum PackageJsonDependencyGroup { All = Dependencies | DevDependencies | PeerDependencies | OptionalDependencies, } -/* @internal */ +/** @internal */ export interface ProjectPackageJsonInfo { fileName: string; parseable: boolean; @@ -247,12 +247,12 @@ export interface ProjectPackageJsonInfo { has(dependencyName: string, inGroups?: PackageJsonDependencyGroup): boolean; } -/* @internal */ +/** @internal */ export interface FormattingHost { getNewLine?(): string; } -/* @internal */ +/** @internal */ export const enum PackageJsonAutoImportPreference { Off, On, @@ -326,12 +326,12 @@ export interface LanguageServiceHost extends GetEffectiveTypeRootsHost, MinimalR resolveModuleNames?(moduleNames: string[], containingFile: string, reusedNames: string[] | undefined, redirectedReference: ResolvedProjectReference | undefined, options: CompilerOptions, containingSourceFile?: SourceFile, resolutionInfo?: ModuleResolutionInfo): (ResolvedModule | undefined)[]; getResolvedModuleWithFailedLookupLocationsFromCache?(modulename: string, containingFile: string, resolutionMode?: ModuleKind.CommonJS | ModuleKind.ESNext): ResolvedModuleWithFailedLookupLocations | undefined; resolveTypeReferenceDirectives?(typeDirectiveNames: string[] | FileReference[], containingFile: string, redirectedReference: ResolvedProjectReference | undefined, options: CompilerOptions, containingFileMode?: SourceFile["impliedNodeFormat"] | undefined): (ResolvedTypeReferenceDirective | undefined)[]; - /* @internal */ hasInvalidatedResolutions?: HasInvalidatedResolutions; - /* @internal */ hasChangedAutomaticTypeDirectiveNames?: HasChangedAutomaticTypeDirectiveNames; - /* @internal */ getGlobalTypingsCacheLocation?(): string | undefined; - /* @internal */ getSymlinkCache?(files?: readonly SourceFile[]): SymlinkCache; + /** @internal */ hasInvalidatedResolutions?: HasInvalidatedResolutions; + /** @internal */ hasChangedAutomaticTypeDirectiveNames?: HasChangedAutomaticTypeDirectiveNames; + /** @internal */ getGlobalTypingsCacheLocation?(): string | undefined; + /** @internal */ getSymlinkCache?(files?: readonly SourceFile[]): SymlinkCache; /* Lets the Program from a AutoImportProviderProject use its host project's ModuleResolutionCache */ - /* @internal */ getModuleResolutionCache?(): ModuleResolutionCache | undefined; + /** @internal */ getModuleResolutionCache?(): ModuleResolutionCache | undefined; /* * Required for full import and type reference completions. @@ -348,23 +348,23 @@ export interface LanguageServiceHost extends GetEffectiveTypeRootsHost, MinimalR installPackage?(options: InstallPackageOptions): Promise; writeFile?(fileName: string, content: string): void; - /* @internal */ getDocumentPositionMapper?(generatedFileName: string, sourceFileName?: string): DocumentPositionMapper | undefined; - /* @internal */ getSourceFileLike?(fileName: string): SourceFileLike | undefined; - /* @internal */ getPackageJsonsVisibleToFile?(fileName: string, rootDir?: string): readonly ProjectPackageJsonInfo[]; - /* @internal */ getNearestAncestorDirectoryWithPackageJson?(fileName: string): string | undefined; - /* @internal */ getPackageJsonsForAutoImport?(rootDir?: string): readonly ProjectPackageJsonInfo[]; - /* @internal */ getCachedExportInfoMap?(): ExportInfoMap; - /* @internal */ getModuleSpecifierCache?(): ModuleSpecifierCache; - /* @internal */ setCompilerHost?(host: CompilerHost): void; - /* @internal */ useSourceOfProjectReferenceRedirect?(): boolean; - /* @internal */ getPackageJsonAutoImportProvider?(): Program | undefined; - /* @internal */ sendPerformanceEvent?(kind: PerformanceEvent["kind"], durationMs: number): void; + /** @internal */ getDocumentPositionMapper?(generatedFileName: string, sourceFileName?: string): DocumentPositionMapper | undefined; + /** @internal */ getSourceFileLike?(fileName: string): SourceFileLike | undefined; + /** @internal */ getPackageJsonsVisibleToFile?(fileName: string, rootDir?: string): readonly ProjectPackageJsonInfo[]; + /** @internal */ getNearestAncestorDirectoryWithPackageJson?(fileName: string): string | undefined; + /** @internal */ getPackageJsonsForAutoImport?(rootDir?: string): readonly ProjectPackageJsonInfo[]; + /** @internal */ getCachedExportInfoMap?(): ExportInfoMap; + /** @internal */ getModuleSpecifierCache?(): ModuleSpecifierCache; + /** @internal */ setCompilerHost?(host: CompilerHost): void; + /** @internal */ useSourceOfProjectReferenceRedirect?(): boolean; + /** @internal */ getPackageJsonAutoImportProvider?(): Program | undefined; + /** @internal */ sendPerformanceEvent?(kind: PerformanceEvent["kind"], durationMs: number): void; getParsedCommandLine?(fileName: string): ParsedCommandLine | undefined; - /* @internal */ onReleaseParsedCommandLine?(configFileName: string, oldResolvedRef: ResolvedProjectReference | undefined, optionOptions: CompilerOptions): void; - /* @internal */ getIncompleteCompletionsCache?(): IncompleteCompletionsCache; + /** @internal */ onReleaseParsedCommandLine?(configFileName: string, oldResolvedRef: ResolvedProjectReference | undefined, optionOptions: CompilerOptions): void; + /** @internal */ getIncompleteCompletionsCache?(): IncompleteCompletionsCache; } -/* @internal */ +/** @internal */ export const emptyOptions = {}; export type WithMetadata = T & { metadata?: unknown; }; @@ -514,10 +514,10 @@ export interface LanguageService { getSmartSelectionRange(fileName: string, position: number): SelectionRange; - /*@internal*/ + /** @internal */ // eslint-disable-next-line @typescript-eslint/unified-signatures getDefinitionAtPosition(fileName: string, position: number, searchOtherFilesOnly: false, stopAtAlias: boolean): readonly DefinitionInfo[] | undefined; - /*@internal*/ + /** @internal */ // eslint-disable-next-line @typescript-eslint/unified-signatures getDefinitionAtPosition(fileName: string, position: number, searchOtherFilesOnly: boolean, stopAtAlias: false): readonly DefinitionInfo[] | undefined; getDefinitionAtPosition(fileName: string, position: number): readonly DefinitionInfo[] | undefined; @@ -590,15 +590,15 @@ export interface LanguageService { getEmitOutput(fileName: string, emitOnlyDtsFiles?: boolean, forceDtsEmit?: boolean): EmitOutput; getProgram(): Program | undefined; - /*@internal*/ getCurrentProgram(): Program | undefined; + /** @internal */ getCurrentProgram(): Program | undefined; - /* @internal */ getNonBoundSourceFile(fileName: string): SourceFile; - /* @internal */ getAutoImportProvider(): Program | undefined; + /** @internal */ getNonBoundSourceFile(fileName: string): SourceFile; + /** @internal */ getAutoImportProvider(): Program | undefined; /// Returns true if a suitable symbol was found in the project. /// May set isDefinition properties in `referencedSymbols` to false. /// May add elements to `knownSymbolSpans`. - /* @internal */ updateIsDefinitionOfReferencedSymbols(referencedSymbols: readonly ReferencedSymbol[], knownSymbolSpans: Set): boolean; + /** @internal */ updateIsDefinitionOfReferencedSymbols(referencedSymbols: readonly ReferencedSymbol[], knownSymbolSpans: Set): boolean; toggleLineComment(fileName: string, textRange: TextRange): TextChange[]; toggleMultilineComment(fileName: string, textRange: TextRange): TextChange[]; @@ -844,9 +844,9 @@ export interface CombinedCodeActions { export type CodeActionCommand = InstallPackageAction; export interface InstallPackageAction { - /* @internal */ readonly type: "install package"; - /* @internal */ readonly file: string; - /* @internal */ readonly packageName: string; + /** @internal */ readonly type: "install package"; + /** @internal */ readonly file: string; + /** @internal */ readonly packageName: string; } /** @@ -1084,7 +1084,7 @@ export function getDefaultFormatCodeSettings(newLineCharacter?: string): FormatC }; } -/* @internal */ +/** @internal */ export const testFormatSettings = getDefaultFormatCodeSettings("\n"); export interface DefinitionInfo extends DocumentSpan { @@ -1099,8 +1099,8 @@ export interface DefinitionInfo extends DocumentSpan { * may be "incomplete" if this span has yet to be checked. */ isLocal?: boolean; - /* @internal */ isAmbient?: boolean; - /* @internal */ failedAliasResolution?: boolean; + /** @internal */ isAmbient?: boolean; + /** @internal */ failedAliasResolution?: boolean; } export interface DefinitionInfoAndBoundSpan { diff --git a/src/services/utilities.ts b/src/services/utilities.ts index 9edfd86931060..fa38c0dab0e79 100644 --- a/src/services/utilities.ts +++ b/src/services/utilities.ts @@ -60,7 +60,7 @@ import { unescapeLeadingUnderscores, UserPreferences, VariableDeclaration, visitEachChild, VoidExpression, YieldExpression, } from "./_namespaces/ts"; -/* @internal */ // Don't expose that we use this +/** @internal */ // Don't expose that we use this // Based on lib.es6.d.ts declare global { // Module transform: converted from ambient declaration @@ -71,7 +71,7 @@ declare global { all(values: (T | PromiseLike)[]): Promise; } } -/* @internal */ +/** @internal */ declare global { // Module transform: converted from ambient declaration /** @internal */ @@ -640,9 +640,10 @@ export function startEndOverlapsWithStartEnd(start1: number, end1: number, start return start < end; } -/** @internal */ /** * Assumes `candidate.start <= position` holds. + * + * @internal */ export function positionBelongsToNode(candidate: Node, position: number, sourceFile: SourceFile): boolean { Debug.assert(candidate.pos <= position); @@ -1196,43 +1197,50 @@ function getAdjustedLocation(node: Node, forRename: boolean): Node { return node; } -/** @internal */ /** * Adjusts the location used for "find references" and "go to definition" when the cursor was not * on a property name. + * + * @internal */ export function getAdjustedReferenceLocation(node: Node): Node { return getAdjustedLocation(node, /*forRename*/ false); } -/** @internal */ /** * Adjusts the location used for "rename" when the cursor was not on a property name. + * + * @internal */ export function getAdjustedRenameLocation(node: Node): Node { return getAdjustedLocation(node, /*forRename*/ true); } -/** @internal */ /** * Gets the token whose text has range [start, end) and * position >= start and (position < end or (position === end && token is literal or keyword or identifier)) + * + * @internal */ export function getTouchingPropertyName(sourceFile: SourceFile, position: number): Node { return getTouchingToken(sourceFile, position, n => isPropertyNameLiteral(n) || isKeyword(n.kind) || isPrivateIdentifier(n)); } -/** @internal */ /** * Returns the token if position is in [start, end). * If position === end, returns the preceding token if includeItemAtEndPosition(previousToken) === true + * + * @internal */ export function getTouchingToken(sourceFile: SourceFile, position: number, includePrecedingTokenAtEndPosition?: (n: Node) => boolean): Node { return getTokenAtPositionWorker(sourceFile, position, /*allowPositionInLeadingTrivia*/ false, includePrecedingTokenAtEndPosition, /*includeEndPosition*/ false); } -/** @internal */ -/** Returns a token if position is in [start-of-leading-trivia, end) */ +/** + * Returns a token if position is in [start-of-leading-trivia, end) + * + * @internal + */ export function getTokenAtPosition(sourceFile: SourceFile, position: number): Node { return getTokenAtPositionWorker(sourceFile, position, /*allowPositionInLeadingTrivia*/ true, /*includePrecedingTokenAtEndPosition*/ undefined, /*includeEndPosition*/ false); } @@ -1333,10 +1341,11 @@ function getTokenAtPositionWorker(sourceFile: SourceFile, position: number, allo } } -/** @internal */ /** * Returns the first token where position is in [start, end), * excluding `JsxText` tokens containing only whitespace. + * + * @internal */ export function findFirstNonJsxWhitespaceToken(sourceFile: SourceFile, position: number): Node | undefined { let tokenAtPosition = getTokenAtPosition(sourceFile, position); @@ -1348,7 +1357,6 @@ export function findFirstNonJsxWhitespaceToken(sourceFile: SourceFile, position: return tokenAtPosition; } -/** @internal */ /** * The token on the left of the position is the token that strictly includes the position * or sits to the left of the cursor if it is on a boundary. For example @@ -1356,6 +1364,8 @@ export function findFirstNonJsxWhitespaceToken(sourceFile: SourceFile, position: * fo|o -> will return foo * foo |bar -> will return foo * + * + * @internal */ export function findTokenOnLeftOfPosition(file: SourceFile, position: number): Node | undefined { // Ideally, getTokenAtPosition should return a token. However, it is currently @@ -1388,10 +1398,11 @@ export function findNextToken(previousToken: Node, parent: Node, sourceFile: Sou } } -/** @internal */ /** * Finds the rightmost token satisfying `token.end <= position`, * excluding `JsxText` tokens containing only whitespace. + * + * @internal */ export function findPrecedingToken(position: number, sourceFile: SourceFileLike, startNode: Node, excludeJsdoc?: boolean): Node | undefined; /** @internal */ @@ -1517,9 +1528,9 @@ export function isInString(sourceFile: SourceFile, position: number, previousTok return false; } -/** @internal */ /** - * returns true if the position is in between the open and close elements of an JSX expression. + * + * @internal */ export function isInsideJsxElementOrAttribute(sourceFile: SourceFile, position: number) { const token = getTokenAtPosition(sourceFile, position); @@ -1795,12 +1806,13 @@ export function getPossibleTypeArgumentsInfo(tokenIn: Node | undefined, sourceFi return undefined; } -/** @internal */ /** * Returns true if the cursor at position in sourceFile is within a comment. * * @param tokenAtPosition Must equal `getTokenAtPosition(sourceFile, position)` * @param predicate Additional predicate to test on the comment range. + * + * @internal */ export function isInComment(sourceFile: SourceFile, position: number, tokenAtPosition?: Node): CommentRange | undefined { return formatting.getRangeOfEnclosingComment(sourceFile, position, /*precedingToken*/ undefined, tokenAtPosition); @@ -2029,14 +2041,20 @@ export function isTypeKeywordTokenOrIdentifier(node: Node) { return isTypeKeywordToken(node) || isIdentifier(node) && node.text === "type"; } -/** @internal */ -/** True if the symbol is for an external module, as opposed to a namespace. */ +/** + * True if the symbol is for an external module, as opposed to a namespace. + * + * @internal + */ export function isExternalModuleSymbol(moduleSymbol: Symbol): boolean { return !!(moduleSymbol.flags & SymbolFlags.Module) && moduleSymbol.name.charCodeAt(0) === CharacterCodes.doubleQuote; } -/** @internal */ -/** Returns `true` the first time it encounters a node and `false` afterwards. */ +/** + * Returns `true` the first time it encounters a node and `false` afterwards. + * + * @internal + */ export type NodeSeenTracker = (node: T) => boolean; /** @internal */ export function nodeSeenTracker(): NodeSeenTracker { @@ -2294,11 +2312,12 @@ export function documentSpansEqual(a: DocumentSpan, b: DocumentSpan): boolean { return a.fileName === b.fileName && textSpansEqual(a.textSpan, b.textSpan); } -/** @internal */ /** * Iterates through 'array' by index and performs the callback on each element of array until the callback * returns a truthy value, then returns that value. * If no such value is found, the callback is applied to each element of array and undefined is returned. + * + * @internal */ export function forEachUnique(array: readonly T[] | undefined, callback: (element: T, index: number) => U): U | undefined { if (array) { @@ -2635,9 +2654,10 @@ function findLinkNameEnd(text: string) { } const carriageReturnLineFeed = "\r\n"; -/** @internal */ /** * The default is CRLF. + * + * @internal */ export function getNewLineOrDefaultFromHost(host: FormattingHost, formatSettings?: FormatCodeSettings) { return formatSettings?.newLineCharacter || @@ -2747,12 +2767,13 @@ export function getPrecedingNonSpaceCharacterPosition(text: string, position: nu return position + 1; } -/** @internal */ /** * Creates a deep, memberwise clone of a node with no source map location. * * WARNING: This is an expensive operation and is only intended to be used in refactorings * and code fixes (because those are triggered by explicit user actions). + * + * @internal */ export function getSynthesizedDeepClone(node: T, includeTrivia = true): T { const clone = node && getSynthesizedDeepCloneWorker(node); @@ -2822,26 +2843,29 @@ export function getSynthesizedDeepClonesWithReplacements( return factory.createNodeArray(nodes.map(n => getSynthesizedDeepCloneWithReplacements(n, includeTrivia, replaceNode)), nodes.hasTrailingComma); } -/** @internal */ /** * Sets EmitFlags to suppress leading and trailing trivia on the node. + * + * @internal */ export function suppressLeadingAndTrailingTrivia(node: Node) { suppressLeadingTrivia(node); suppressTrailingTrivia(node); } -/** @internal */ /** * Sets EmitFlags to suppress leading trivia on the node. + * + * @internal */ export function suppressLeadingTrivia(node: Node) { addEmitFlagsRecursively(node, EmitFlags.NoLeadingComments, getFirstChild); } -/** @internal */ /** * Sets EmitFlags to suppress trailing trivia on the node. + * + * @internal */ export function suppressTrailingTrivia(node: Node) { addEmitFlagsRecursively(node, EmitFlags.NoTrailingComments, getLastChild); @@ -2888,11 +2912,12 @@ export function getUniqueName(baseName: string, sourceFile: SourceFile): string return nameText; } -/** @internal */ /** * @return The index of the (only) reference to the extracted symbol. We want the cursor * to be on the reference, rather than the declaration, because it's closer to where the * user was before extracting it. + * + * @internal */ export function getRenameLocation(edits: readonly FileTextChanges[], renameFilename: string, name: string, preferLastLocation: boolean): number { let delta = 0; @@ -2931,13 +2956,14 @@ export function copyTrailingComments(sourceNode: Node, targetNode: Node, sourceF forEachTrailingCommentRange(sourceFile.text, sourceNode.end, getAddCommentsFunction(targetNode, sourceFile, commentKind, hasTrailingNewLine, addSyntheticTrailingComment)); } -/** @internal */ /** * This function copies the trailing comments for the token that comes before `sourceNode`, as leading comments of `targetNode`. * This is useful because sometimes a comment that refers to `sourceNode` will be a leading comment for `sourceNode`, according to the * notion of trivia ownership, and instead will be a trailing comment for the token before `sourceNode`, e.g.: * `function foo(\* not leading comment for a *\ a: string) {}` * The comment refers to `a` but belongs to the `(` token, but we might want to copy it. + * + * @internal */ export function copyTrailingAsLeadingComments(sourceNode: Node, targetNode: Node, sourceFile: SourceFile, commentKind?: CommentKind, hasTrailingNewLine?: boolean) { forEachTrailingCommentRange(sourceFile.text, sourceNode.pos, getAddCommentsFunction(targetNode, sourceFile, commentKind, hasTrailingNewLine, addSyntheticLeadingComment)); @@ -2968,7 +2994,7 @@ function indexInTextChange(change: string, name: string): number { return idx === -1 ? -1 : idx + 1; } -/* @internal */ +/** @internal */ export function needsParentheses(expression: Expression): boolean { return isBinaryExpression(expression) && expression.operatorToken.kind === SyntaxKind.CommaToken || isObjectLiteralExpression(expression) @@ -3528,12 +3554,12 @@ export function getDiagnosticsWithinSpan(span: TextSpan, sortedFileDiagnostics: return result; } -/* @internal */ +/** @internal */ export function getRefactorContextSpan({ startPosition, endPosition }: RefactorContext): TextSpan { return createTextSpanFromBounds(startPosition, endPosition === undefined ? startPosition : endPosition); } -/* @internal */ +/** @internal */ export function getFixableErrorSpanExpression(sourceFile: SourceFile, span: TextSpan): Expression | undefined { const token = getTokenAtPosition(sourceFile, span.start); // Checker has already done work to determine that await might be possible, and has attached @@ -3549,10 +3575,11 @@ export function getFixableErrorSpanExpression(sourceFile: SourceFile, span: Text return expression; } -/** @internal */ /** * If the provided value is an array, the mapping function is applied to each element; otherwise, the mapping function is applied * to the provided value itself. + * + * @internal */ export function mapOneOrMany(valueOrArray: T | readonly T[], f: (x: T, i: number) => U): U | U[]; /** @internal */ @@ -3566,9 +3593,10 @@ export function mapOneOrMany(valueOrArray: T | readonly T[] | undefined, f return valueOrArray ? isArray(valueOrArray) ? resultSelector(map(valueOrArray, f)) : f(valueOrArray, 0) : undefined; } -/** @internal */ /** * If the provided value is an array, the first element of the array is returned; otherwise, the provided value is returned instead. + * + * @internal */ export function firstOrOnly(valueOrArray: T | readonly T[]): T { return isArray(valueOrArray) ? first(valueOrArray) : valueOrArray; @@ -3618,7 +3646,6 @@ function getSymbolParentOrFail(symbol: Symbol) { }).join(", ")}.`); } -/** @internal */ /** * Useful to check whether a string contains another string at a specific index * without allocating another string or traversing the entire contents of the outer string. @@ -3636,6 +3663,8 @@ function getSymbolParentOrFail(symbol: Symbol) { * @param haystack The string that potentially contains `needle`. * @param needle The string whose content might sit within `haystack`. * @param startIndex The index within `haystack` to start searching for `needle`. + * + * @internal */ export function stringContainsAt(haystack: string, needle: string, startIndex: number) { const needleLength = needle.length; @@ -3698,9 +3727,10 @@ export function diagnosticToString(diag: DiagnosticAndArguments): string { : getLocaleSpecificMessage(diag); } -/** @internal */ /** * Get format code settings for a code writing context (e.g. when formatting text changes or completions code). + * + * @internal */ export function getFormatCodeSettingsForWriting({ options }: formatting.FormatContext, sourceFile: SourceFile): FormatCodeSettings { const shouldAutoDetectSemicolonPreference = !options.semicolons || options.semicolons === SemicolonPreference.Ignore; diff --git a/src/typingsInstallerCore/typingsInstaller.ts b/src/typingsInstallerCore/typingsInstaller.ts index ad08facc3c2aa..c40443366380c 100644 --- a/src/typingsInstallerCore/typingsInstaller.ts +++ b/src/typingsInstallerCore/typingsInstaller.ts @@ -42,7 +42,7 @@ function typingToFileName(cachePath: string, packageName: string, installTypingH } } -/*@internal*/ +/** @internal */ export function installNpmPackages(npmPath: string, tsVersion: string, packageNames: string[], install: (command: string) => boolean) { let hasError = false; for (let remaining = packageNames.length; remaining > 0;) { @@ -53,7 +53,7 @@ export function installNpmPackages(npmPath: string, tsVersion: string, packageNa return hasError; } -/*@internal*/ +/** @internal */ export function getNpmCommandForInstallation(npmPath: string, tsVersion: string, packageNames: string[], remaining: number) { const sliceStart = packageNames.length - remaining; let command: string, toSlice = remaining; @@ -116,7 +116,7 @@ export abstract class TypingsInstaller { private inFlightRequestCount = 0; abstract readonly typesRegistry: ESMap>; - /*@internal*/ + /** @internal */ private readonly watchFactory: WatchFactory; constructor( @@ -551,7 +551,7 @@ export abstract class TypingsInstaller { protected readonly latestDistTag = "latest"; } -/* @internal */ +/** @internal */ export function typingsName(packageName: string): string { return `@types/${packageName}@ts${versionMajorMinor}`; } diff --git a/src/webServer/webServer.ts b/src/webServer/webServer.ts index c50019081df94..11980d1a0e49c 100644 --- a/src/webServer/webServer.ts +++ b/src/webServer/webServer.ts @@ -226,7 +226,7 @@ export function createWebSystem(host: WebHost, args: string[], getExecutingFileP // createSHA256Hash // telemetry of the project // Logging related - // /*@internal*/ bufferFrom?(input: string, encoding?: string): Buffer; + // /** @internal */ bufferFrom?(input: string, encoding?: string): Buffer; // gc?(): void; // getMemoryUsage?(): number; };