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 12e9c2c70dda6..788a145cc85cf 100644 --- a/src/compiler/builder.ts +++ b/src/compiler/builder.ts @@ -92,9 +92,10 @@ export const enum BuilderFileEmit { Full } -/** @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 { @@ -809,15 +810,17 @@ export type ProgramBuildInfoBuilderStateFileInfo = 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", @@ -342,7 +344,7 @@ export const commonOptionsWithBuild: CommandLineOption[] = [ }, ]; -/* @internal */ +/** @internal */ export const targetOptionDeclaration: CommandLineOptionOfCustomType = { name: "target", shortName: "t", @@ -371,7 +373,7 @@ export const targetOptionDeclaration: CommandLineOptionOfCustomType = { defaultValueDescription: ScriptTarget.ES3, }; -/*@internal*/ +/** @internal */ export const moduleOptionDeclaration: CommandLineOptionOfCustomType = { name: "module", shortName: "m", @@ -1377,42 +1379,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", @@ -1447,13 +1449,13 @@ export const optionsForBuild: CommandLineOption[] = [ } ]; -/* @internal */ +/** @internal */ export const buildOpts: CommandLineOption[] = [ ...commonOptionsWithBuild, ...optionsForBuild ]; -/* @internal */ +/** @internal */ export const typeAcquisitionDeclarations: CommandLineOption[] = [ { /* @deprecated typingOptions.enableAutoDiscovery @@ -1491,13 +1493,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(); @@ -1513,7 +1515,7 @@ export function createOptionNameMap(optionDeclarations: readonly CommandLineOpti let optionsNameMapCache: OptionsNameMap; -/* @internal */ +/** @internal */ export function getOptionsNameMap(): OptionsNameMap { return optionsNameMapCache ||= createOptionNameMap(optionDeclarations); } @@ -1523,7 +1525,7 @@ const compilerOptionsAlternateMode: AlternateModeDiagnostics = { getOptionsNameMap: getBuildOptionsNameMap }; -/* @internal */ +/** @internal */ export const defaultInitCompilerOptions: CompilerOptions = { module: ModuleKind.CommonJS, target: ScriptTarget.ES2016, @@ -1533,7 +1535,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) { @@ -1546,7 +1548,7 @@ export function convertEnableAutoDiscoveryToEnable(typeAcquisition: TypeAcquisit return typeAcquisition; } -/* @internal */ +/** @internal */ export function createCompilerDiagnosticForInvalidCustomType(opt: CommandLineOptionOfCustomType): Diagnostic { return createDiagnosticForInvalidCustomType(opt, createCompilerDiagnostic); } @@ -1556,12 +1558,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, "-")) { @@ -1581,12 +1583,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; @@ -1612,7 +1614,7 @@ function createUnknownOptionError( createDiagnostics(diagnostics.unknownOptionDiagnostic, unknownOptionErrorText || unknownOption); } -/*@internal*/ +/** @internal */ export function parseCommandLineWorker( diagnostics: ParseCommandLineWorkerDiagnostics, commandLine: readonly string[], @@ -1769,7 +1771,7 @@ function parseOptionValue( return i; } -/*@internal*/ +/** @internal */ export const compilerOptionsDidYouMeanDiagnostics: ParseCommandLineWorkerDiagnostics = { alternateMode: compilerOptionsAlternateMode, getOptionsNameMap, @@ -1800,7 +1802,7 @@ function getOptionDeclarationFromName(getOptionNameMap: () => OptionsNameMap, op return optionsNameMap.get(optionName); } -/*@internal*/ +/** @internal */ export interface ParsedBuildCommand { buildOptions: BuildOptions; watchOptions: WatchOptions | undefined; @@ -1827,7 +1829,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, @@ -1857,7 +1859,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; @@ -1947,7 +1949,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 { @@ -2075,7 +2077,7 @@ function getTsconfigRootOptionsMap() { return _tsconfigRootOptions; } -/*@internal*/ +/** @internal */ interface JsonConversionNotifier { /** * Notifies parent option object is being set with the optionKey and a valid optionValue @@ -2139,8 +2141,9 @@ export function convertToObject(sourceFile: JsonSourceFile, errors: Push): object { return { ...arrayFrom(optionMap.entries()).reduce((prev, cur) => ({ ...prev, [cur[0]]: cur[1] }), {}), @@ -2474,7 +2478,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) => { @@ -2484,7 +2488,7 @@ export function getNameOfCompilerOptionValue(value: CompilerOptionsValue, custom }); } -/* @internal */ +/** @internal */ export function serializeCompilerOptions( options: CompilerOptions, pathOptions?: { configFilePath: string, useCaseSensitiveFileNames: boolean } @@ -2585,8 +2589,9 @@ function getSerializedCompilerOption(options: CompilerOptions): ESMap string) { const result: CompilerOptions = {}; const optionsNameMap = getOptionsNameMap().optionsNameMap; @@ -2735,7 +2740,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 }); @@ -2752,7 +2757,7 @@ function directoryOfCombinedPath(fileName: string, basePath: string) { return getDirectoryPath(getNormalizedAbsolutePath(fileName, basePath)); } -/*@internal*/ +/** @internal */ export const defaultIncludeSpec = "**/*"; /** @@ -2952,12 +2957,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)) { @@ -3313,7 +3318,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; @@ -3415,8 +3420,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, @@ -3506,7 +3512,7 @@ export function getFileNamesFromConfigSpecs( return literalFiles.concat(wildcardFiles, arrayFrom(wildCardJsonFileMap.values())); } -/* @internal */ +/** @internal */ export function isExcludedFile( pathToCheck: string, spec: ConfigFileSpecs, @@ -3543,7 +3549,7 @@ function invalidDotDotAfterRecursiveWildcard(s: string) { return lastDotIndex > wildcardIndex; } -/* @internal */ +/** @internal */ export function matchesExclude( pathToCheck: string, excludeSpecs: readonly string[] | undefined, @@ -3734,8 +3740,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 eed25e41113a2..2d371afea0c7f 100644 --- a/src/compiler/emitter.ts +++ b/src/compiler/emitter.ts @@ -81,12 +81,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. * @@ -95,6 +94,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, @@ -151,7 +152,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; @@ -162,7 +163,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) { @@ -186,7 +187,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 : @@ -204,7 +205,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), @@ -263,7 +264,7 @@ function getOwnOutputFileNames(configFile: ParsedCommandLine, inputFileName: str } } -/*@internal*/ +/** @internal */ export function getCommonSourceDirectory( options: CompilerOptions, emittedFiles: () => readonly string[], @@ -295,7 +296,7 @@ export function getCommonSourceDirectory( return commonSourceDirectory; } -/*@internal*/ +/** @internal */ export function getCommonSourceDirectoryOfConfig({ options, fileNames }: ParsedCommandLine, ignoreCase: boolean): string { return getCommonSourceDirectory( options, @@ -305,7 +306,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)) { @@ -334,7 +335,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 } = getOutputPathsForBundle(configFile.options, /*forceDtsPaths*/ false); @@ -356,7 +357,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, emitOnlyDtsFiles?: boolean, onlyBuildInfo?: boolean, forceDtsEmit?: boolean): EmitResult { const compilerOptions = host.getCompilerOptions(); @@ -726,17 +727,17 @@ export function emitFiles(resolver: EmitResolver, host: EmitHost, targetSourceFi } } -/*@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, @@ -781,11 +782,14 @@ 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[]; -/*@internal*/ +/** @internal */ export interface EmitUsingBuildInfoHost extends ModuleResolutionHost { getCurrentDirectory(): string; getCanonicalFileName(fileName: string): string; @@ -822,7 +826,7 @@ function createSourceFilesFromBundleBuildInfo(bundle: BundleBuildInfo, buildInfo }); } -/*@internal*/ +/** @internal */ export function emitUsingBuildInfo( config: ParsedCommandLine, host: EmitUsingBuildInfoHost, 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 a64390415114a..d053bac81ec62 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; @@ -6848,7 +6850,7 @@ export function createInputFiles( declarationMapPath: string | undefined, declarationMapText: string | undefined ): InputFiles; -/*@internal*/ +/** @internal */ export function createInputFiles( javascriptText: string, declarationText: 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 5d71e9490452a..87fef65c11f70 100644 --- a/src/compiler/moduleNameResolver.ts +++ b/src/compiler/moduleNameResolver.ts @@ -19,13 +19,13 @@ import { 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(); const memoizedReverseKeys = new Map(); @@ -791,7 +793,7 @@ export function createModeAwareCache(): ModeAwareCache { } } -/* @internal */ +/** @internal */ export function zipToModeAwareCache(file: SourceFile, keys: readonly string[] | readonly FileReference[], values: readonly V[]): ModeAwareCache { Debug.assert(keys.length === values.length); const map = createModeAwareCache(); @@ -810,7 +812,7 @@ export function createModuleResolutionCache( getCanonicalFileName: (s: string) => string, options?: CompilerOptions ): ModuleResolutionCache; -/*@internal*/ +/** @internal */ export function createModuleResolutionCache( currentDirectory: string, getCanonicalFileName: GetCanonicalFileName, @@ -937,7 +939,7 @@ export function createTypeReferenceDirectiveResolutionCache( options?: CompilerOptions, packageJsonInfoCache?: PackageJsonInfoCache, ): TypeReferenceDirectiveResolutionCache; -/*@internal*/ +/** @internal */ export function createTypeReferenceDirectiveResolutionCache( currentDirectory: string, getCanonicalFileName: GetCanonicalFileName, @@ -1267,8 +1269,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) { @@ -1277,7 +1280,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 @@ -1349,7 +1352,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) { @@ -1515,9 +1518,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); } @@ -1531,8 +1534,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); @@ -1708,7 +1712,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, @@ -1813,7 +1817,7 @@ function loadEntrypointsFromExportMap( } } -/*@internal*/ +/** @internal */ export function getTemporaryModuleResolutionState(packageJsonInfoCache: PackageJsonInfoCache | undefined, host: ModuleResolutionHost, options: CompilerOptions): ModuleResolutionState { return { host, @@ -1829,12 +1833,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; @@ -1844,8 +1848,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(); @@ -1859,7 +1864,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"); @@ -2005,7 +2010,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] === "@") { @@ -2014,7 +2019,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, ".")); } @@ -2395,7 +2400,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; @@ -2565,12 +2570,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); @@ -2581,7 +2586,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) { @@ -2590,7 +2595,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) : @@ -2672,8 +2677,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 241384aa1acee..15d7c33af725a 100644 --- a/src/compiler/program.ts +++ b/src/compiler/program.ts @@ -73,7 +73,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 => { @@ -123,7 +123,7 @@ export function createCompilerHost(options: CompilerOptions, setParentNodes?: bo return createCompilerHostWorker(options, setParentNodes); } -/*@internal*/ +/** @internal */ export function createCompilerHostWorker(options: CompilerOptions, setParentNodes?: boolean, system = sys): CompilerHost { const existingDirectories = new Map(); const getCanonicalFileName = createGetCanonicalFileName(system.useCaseSensitiveFileNames); @@ -209,7 +209,7 @@ export function createCompilerHostWorker(options: CompilerOptions, setParentNode return compilerHost; } -/*@internal*/ +/** @internal */ interface CompilerHostLikeForCache { fileExists(fileName: string): boolean; readFile(fileName: string, encoding?: string): string | undefined; @@ -218,7 +218,7 @@ interface CompilerHostLikeForCache { writeFile?: WriteFileCallback; } -/*@internal*/ +/** @internal */ export function changeCompilerHostLikeToUseCache( host: CompilerHostLikeForCache, toPath: (fileName: string) => Path, @@ -334,7 +334,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()); @@ -460,7 +460,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; @@ -533,7 +533,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 []; @@ -565,8 +565,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"]; } @@ -596,7 +596,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; @@ -643,7 +643,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) { @@ -664,7 +664,7 @@ export function getResolutionModeOverrideForClause(clause: AssertClause | undefi return elem.value.text === "import" ? ModuleKind.ESNext : ModuleKind.CommonJS; } -/* @internal */ +/** @internal */ export function loadWithModeAwareCache(names: string[], containingFile: SourceFile, containingFileName: string, redirectedReference: ResolvedProjectReference | undefined, loader: (name: string, resolverMode: ModuleKind.CommonJS | ModuleKind.ESNext | undefined, containingFileName: string, redirectedReference: ResolvedProjectReference | undefined) => T): T[] { if (names.length === 0) { return []; @@ -688,7 +688,7 @@ export function loadWithModeAwareCache(names: string[], containingFile: Sourc return resolutions; } -/* @internal */ +/** @internal */ export function forEachResolvedProjectReference( resolvedProjectReferences: readonly (ResolvedProjectReference | undefined)[] | undefined, cb: (resolvedProjectReference: ResolvedProjectReference, parent: ResolvedProjectReference | undefined) => T | undefined @@ -733,7 +733,7 @@ function forEachProjectReference( } } -/* @internal */ +/** @internal */ export const inferredTypesContainingFile = "__inferred type names__.ts"; interface DiagnosticCache { @@ -741,7 +741,7 @@ interface DiagnosticCache { allDiagnostics?: readonly T[]; } -/*@internal*/ +/** @internal */ export function isReferencedFile(reason: FileIncludeReason | undefined): reason is ReferencedFile { switch (reason?.kind) { case FileIncludeKind.Import: @@ -754,7 +754,7 @@ export function isReferencedFile(reason: FileIncludeReason | undefined): reason } } -/*@internal*/ +/** @internal */ export interface ReferenceFileLocation { file: SourceFile; pos: number; @@ -762,19 +762,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; @@ -805,8 +805,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[], @@ -912,7 +913,7 @@ export function getImpliedNodeFormatForFile(fileName: Path, packageJsonInfoCache return typeof result === "object" ? result.impliedNodeFormat : result; } -/*@internal*/ +/** @internal */ export function getImpliedNodeFormatForFileWorker( fileName: string, packageJsonInfoCache: PackageJsonInfoCache | undefined, @@ -4271,10 +4272,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, @@ -4315,12 +4316,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; @@ -4331,7 +4332,7 @@ interface CompilerHostLike { onUnRecoverableConfigFileDiagnostic?: DiagnosticReporter; } -/* @internal */ +/** @internal */ export function parseConfigHostFromCompilerHostLike(host: CompilerHostLike, directoryStructureHost: DirectoryStructureHost = host): ParseConfigFileHost { return { fileExists: f => directoryStructureHost.fileExists(f), @@ -4352,7 +4353,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, readFile: (path: string) => string | undefined) { if (!projectReferences) return emptyArray; let nodes: InputFiles[] | undefined; @@ -4382,11 +4383,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) { @@ -4426,7 +4428,7 @@ function getModuleNames({ imports, moduleAugmentations }: SourceFile): string[] 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 1a1c5bcc760fb..b12ef53352562 100644 --- a/src/compiler/resolutionCache.ts +++ b/src/compiler/resolutionCache.ts @@ -17,8 +17,11 @@ import { returnTrue, Set, some, SourceFile, startsWith, 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; @@ -124,12 +127,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 27204635b5c81..f353e8db7fb69 100644 --- a/src/compiler/sourcemap.ts +++ b/src/compiler/sourcemap.ts @@ -349,9 +349,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 553fbc6680e6a..dac2670b72c61 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 ad20ff97b4d16..a927555fbee97 100644 --- a/src/compiler/tsbuild.ts +++ b/src/compiler/tsbuild.ts @@ -174,4 +174,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 895a03afe62d1..c454d528b9ac6 100644 --- a/src/compiler/tsbuildPublic.ts +++ b/src/compiler/tsbuildPublic.ts @@ -37,24 +37,24 @@ 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; 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; } @@ -81,7 +81,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 { @@ -98,8 +98,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(); } @@ -131,10 +134,10 @@ 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*/ afterEmitBundle?(config: ParsedCommandLine): void; + /** @internal */ afterEmitBundle?(config: ParsedCommandLine): void; // For testing - /*@internal*/ now?(): Date; + /** @internal */ now?(): Date; } export interface SolutionBuilderHost extends SolutionBuilderHostBase { @@ -144,22 +147,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; } @@ -172,12 +175,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; } /** @@ -682,8 +685,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 d522515d3eafd..37e10cb3f0cca 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,9 +4282,9 @@ export interface ParseConfigHost { export type ResolvedConfigFileName = string & { _isResolvedConfigFileName: never }; export interface WriteFileCallbackData { - /*@internal*/ sourceMapUrlPos?: number; - /*@internal*/ buildInfo?: BuildInfo; - /*@internal*/ diagnostics?: readonly DiagnosticWithLocation[]; + /** @internal */ sourceMapUrlPos?: number; + /** @internal */ buildInfo?: BuildInfo; + /** @internal */ diagnostics?: readonly DiagnosticWithLocation[]; } export type WriteFileCallback = ( fileName: string, @@ -4288,7 +4304,7 @@ export interface CancellationToken { throwIfCancellationRequested(): void; } -/*@internal*/ +/** @internal */ export enum FileIncludeKind { RootFile, SourceFromProjectReference, @@ -4301,49 +4317,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 | @@ -4351,13 +4367,13 @@ export type FileIncludeReason = ReferencedFile | AutomaticTypeDirectiveFile; -/*@internal*/ +/** @internal */ export const enum FilePreprocessingDiagnosticsKind { FilePreprocessingReferencedDiagnostic, FilePreprocessingFileExplainingDiagnostic } -/*@internal*/ +/** @internal */ export interface FilePreprocessingReferencedDiagnostic { kind: FilePreprocessingDiagnosticsKind.FilePreprocessingReferencedDiagnostic; reason: ReferencedFile; @@ -4365,7 +4381,7 @@ export interface FilePreprocessingReferencedDiagnostic { args?: (string | number | undefined)[]; } -/*@internal*/ +/** @internal */ export interface FilePreprocessingFileExplainingDiagnostic { kind: FilePreprocessingDiagnosticsKind.FilePreprocessingFileExplainingDiagnostic; file?: Path; @@ -4374,7 +4390,7 @@ export interface FilePreprocessingFileExplainingDiagnostic { args?: (string | number | undefined)[]; } -/*@internal*/ +/** @internal */ export type FilePreprocessingDiagnostics = FilePreprocessingReferencedDiagnostic | FilePreprocessingFileExplainingDiagnostic; export interface Program extends ScriptReferenceHost { @@ -4392,12 +4408,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; /** @@ -4411,7 +4428,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, emitOnlyDtsFiles?: boolean, customTransformers?: CustomTransformers, forceDtsEmit?: boolean): EmitResult; // eslint-disable-line @typescript-eslint/unified-signatures getOptionsDiagnostics(cancellationToken?: CancellationToken): readonly Diagnostic[]; @@ -4421,21 +4438,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; @@ -4444,53 +4461,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*/ getProgramBuildInfo?(): ProgramBuildInfo | undefined; - /*@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 */ getProgramBuildInfo?(): ProgramBuildInfo | undefined; + /** @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 { @@ -4499,7 +4538,7 @@ export interface ResolvedProjectReference { references?: readonly (ResolvedProjectReference | undefined)[]; } -/* @internal */ +/** @internal */ export const enum StructureIsReused { Not, SafeModules, @@ -4522,7 +4561,7 @@ export interface CustomTransformers { afterDeclarations?: (TransformerFactory | CustomTransformerFactory)[]; } -/*@internal*/ +/** @internal */ export interface EmitTransformers { scriptTransformers: readonly TransformerFactory[]; declarationTransformers: readonly TransformerFactory[]; @@ -4543,7 +4582,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; @@ -4577,10 +4616,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; @@ -4595,54 +4634,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. */ @@ -4652,7 +4697,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. @@ -4680,10 +4725,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[]; @@ -4691,12 +4736,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. @@ -4704,31 +4749,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[]; @@ -4737,43 +4790,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, @@ -4783,47 +4838,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: @@ -4833,24 +4892,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 @@ -4859,29 +4928,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 @@ -4923,11 +4992,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, @@ -5002,13 +5071,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[] }; @@ -5017,7 +5086,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; @@ -5033,14 +5102,14 @@ interface SymbolWriter extends SymbolTracker { clear(): void; } -/* @internal */ +/** @internal */ export const enum SymbolAccessibility { Accessible, NotAccessible, CannotBeNamed } -/* @internal */ +/** @internal */ export const enum SyntheticSymbolKind { UnionOrIntersection, Spread @@ -5088,52 +5157,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 @@ -5144,7 +5213,7 @@ export type LateVisibilityPaintedStatement = | InterfaceDeclaration | EnumDeclaration; -/* @internal */ +/** @internal */ export interface SymbolVisibilityResult { accessibility: SymbolAccessibility; aliasesToMakeVisible?: LateVisibilityPaintedStatement[]; // aliases that need to have this symbol visible @@ -5152,12 +5221,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; @@ -5165,7 +5234,7 @@ export interface AllAccessorDeclarations { setAccessor: SetAccessorDeclaration | undefined; } -/* @internal */ +/** @internal */ export interface AllDecorators { decorators: readonly Decorator[] | undefined; parameters?: readonly (readonly Decorator[] | undefined)[]; @@ -5173,8 +5242,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. @@ -5217,7 +5289,7 @@ export enum TypeReferenceSerializationKind { ObjectType, } -/* @internal */ +/** @internal */ export interface EmitResolver { hasGlobalName(name: string): boolean; getReferencedExportContainer(node: Identifier, prefixLocals?: boolean): SourceFile | ModuleDeclaration | EnumDeclaration | undefined; @@ -5292,7 +5364,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, @@ -5340,22 +5412,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 { @@ -5366,18 +5438,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 @@ -5426,13 +5498,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 @@ -5460,18 +5532,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; @@ -5519,14 +5591,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 @@ -5555,7 +5630,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 @@ -5616,21 +5691,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, @@ -5639,9 +5714,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, @@ -5650,78 +5725,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) @@ -5774,78 +5849,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). */ @@ -5854,11 +5929,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; } @@ -5885,26 +5960,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 @@ -5919,9 +5994,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 } @@ -5952,43 +6027,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 @@ -5996,12 +6071,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; @@ -6018,14 +6093,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 @@ -6035,7 +6110,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. @@ -6043,7 +6118,7 @@ export interface FreshObjectLiteralType extends ResolvedType { regularType: ResolvedType; // Regular version of fresh type } -/* @internal */ +/** @internal */ export interface IterationTypes { readonly yieldType: Type; readonly returnType: Type; @@ -6051,7 +6126,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; @@ -6062,46 +6137,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, @@ -6121,7 +6199,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; @@ -6133,7 +6211,7 @@ export type TypeVariable = TypeParameter | IndexedAccessType; // keyof T types (TypeFlags.Index) export interface IndexType extends InstantiableType { type: InstantiableType | UnionOrIntersectionType; - /* @internal */ + /** @internal */ stringsOnly: boolean; } @@ -6156,13 +6234,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; } @@ -6188,7 +6266,7 @@ export interface SubstitutionType extends InstantiableType { constraint: Type; // Constraint that target type is known to satisfy } -/* @internal */ +/** @internal */ export const enum JsxReferenceKind { Component, Function, @@ -6200,7 +6278,7 @@ export const enum SignatureKind { Construct, } -/* @internal */ +/** @internal */ export const enum SignatureFlags { None = 0, @@ -6223,44 +6301,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 } @@ -6276,7 +6354,7 @@ export interface IndexInfo { declaration?: IndexSignatureDeclaration; } -/* @internal */ +/** @internal */ export const enum TypeMapKind { Simple, Array, @@ -6286,7 +6364,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 } @@ -6312,7 +6390,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) @@ -6324,7 +6402,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) @@ -6339,8 +6417,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, @@ -6348,10 +6427,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) @@ -6364,13 +6443,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 @@ -6378,7 +6457,7 @@ export interface WideningContext { resolvedProperties?: Symbol[]; // Properties occurring in sibling object literals } -/* @internal */ +/** @internal */ export const enum AssignmentDeclarationKind { None, /// exports.name = expr @@ -6421,7 +6500,7 @@ export interface DiagnosticMessage { message: string; reportsUnnecessary?: {}; reportsDeprecated?: {}; - /* @internal */ + /** @internal */ elidedInCompatabilityPyramid?: boolean; } @@ -6445,7 +6524,7 @@ export interface Diagnostic extends DiagnosticRelatedInformation { reportsDeprecated?: {} source?: string; relatedInformation?: DiagnosticRelatedInformation[]; - /* @internal */ skippedOn?: keyof CompilerOptions; + /** @internal */ skippedOn?: keyof CompilerOptions; } export interface DiagnosticRelatedInformation { @@ -6463,7 +6542,7 @@ export interface DiagnosticWithLocation extends Diagnostic { length: number; } -/* @internal*/ +/** @internal */ export interface DiagnosticWithDetachedLocation extends Diagnostic { file: undefined; fileName: string; @@ -6477,7 +6556,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; @@ -6551,29 +6630,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; @@ -6584,22 +6670,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; @@ -6609,7 +6695,7 @@ export interface CompilerOptions { moduleDetection?: ModuleDetectionKind; newLine?: NewLineKind; noEmit?: boolean; - /*@internal*/noEmitForJsFiles?: boolean; + /** @internal */noEmitForJsFiles?: boolean; noEmitHelpers?: boolean; noEmitOnError?: boolean; noErrorTruncation?: boolean; @@ -6625,23 +6711,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; @@ -6664,7 +6754,7 @@ export interface CompilerOptions { stripInternal?: boolean; suppressExcessPropertyErrors?: boolean; suppressImplicitAnyIndexErrors?: boolean; - /* @internal */ suppressOutputPathCheck?: boolean; + /** @internal */ suppressOutputPathCheck?: boolean; target?: ScriptTarget; traceResolution?: boolean; useUnknownInCatchVariables?: boolean; @@ -6672,10 +6762,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; @@ -6808,7 +6898,7 @@ export const enum WatchDirectoryFlags { Recursive = 1 << 0, } -/* @internal */ +/** @internal */ export interface ConfigFileSpecs { filesSpecs: readonly string[] | undefined; /** @@ -6826,7 +6916,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 } }; @@ -6840,7 +6930,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 @@ -6867,37 +6957,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[]; @@ -6905,24 +6995,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, @@ -7157,11 +7247,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[] } @@ -7184,13 +7274,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 CompilerHost extends ModuleResolutionHost { @@ -7223,35 +7313,36 @@ 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 */ disableUseFileVersionAsSignature?: boolean; + /** @internal */ storeFilesChangingSignatureDuringEmit?: boolean; } -/** 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, @@ -7346,11 +7437,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 @@ -7368,23 +7459,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}` @@ -7422,11 +7513,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 { @@ -7443,14 +7534,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; @@ -7458,8 +7549,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) @@ -7513,7 +7605,7 @@ export const enum EmitHint { JsxAttributeValue, // Emitting a JSX attribute value } -/* @internal */ +/** @internal */ export interface SourceFileMayBeEmittedHost { getCompilerOptions(): CompilerOptions; isSourceFileFromExternalLibrary(file: SourceFile): boolean; @@ -7521,7 +7613,7 @@ export interface SourceFileMayBeEmittedHost { isSourceOfProjectReferenceRedirect(fileName: string): boolean; } -/* @internal */ +/** @internal */ export interface EmitHost extends ScriptReferenceHost, ModuleSpecifierResolutionHost, SourceFileMayBeEmittedHost { getSourceFiles(): readonly SourceFile[]; useCaseSensitiveFileNames(): boolean; @@ -7544,7 +7636,7 @@ export interface EmitHost extends ScriptReferenceHost, ModuleSpecifierResolution createHash?(data: string): string; } -/* @internal */ +/** @internal */ export interface PropertyDescriptorAttributes { enumerable?: boolean | Expression; configurable?: boolean | Expression; @@ -7566,7 +7658,7 @@ export const enum OuterExpressionKinds { ExcludeJSDocTypeAssertion = 1 << 4, } -/* @internal */ +/** @internal */ export type OuterExpression = | ParenthesizedExpression | TypeAssertion @@ -7577,13 +7669,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; @@ -7618,7 +7710,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; @@ -7630,7 +7722,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; @@ -7640,10 +7732,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; // @@ -7653,7 +7745,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; @@ -7662,8 +7754,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. @@ -7675,7 +7767,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. @@ -7687,17 +7779,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 @@ -7713,7 +7805,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 @@ -7775,7 +7867,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; @@ -7902,11 +7994,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; @@ -8024,7 +8116,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 @@ -8179,30 +8271,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; @@ -8260,19 +8352,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. * @@ -8287,9 +8379,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* @@ -8300,8 +8394,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 @@ -8311,8 +8407,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 @@ -8322,16 +8420,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. * @@ -8339,8 +8441,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. * @@ -8351,62 +8455,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 @@ -8422,8 +8540,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; @@ -8440,21 +8558,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; @@ -8498,7 +8619,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 { @@ -8593,14 +8714,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", @@ -8616,51 +8737,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 @@ -8669,31 +8790,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; @@ -8701,7 +8822,7 @@ export interface BundleFileInfo { sources?: SourceFileInfo; } -/*@internal*/ +/** @internal */ export interface BundleBuildInfo { js?: BundleFileInfo; dts?: BundleFileInfo; @@ -8709,7 +8830,7 @@ export interface BundleBuildInfo { sourceFiles: readonly string[]; } -/* @internal */ +/** @internal */ export interface BuildInfo { bundle?: BundleBuildInfo; program?: ProgramBuildInfo; @@ -8764,16 +8885,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 { @@ -8781,23 +8902,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; @@ -8810,8 +8931,9 @@ export interface RawSourceMap { /** * Generates a source map. + * + * @internal */ -/* @internal */ export interface SourceMapGenerator { getSources(): readonly string[]; /** @@ -8848,7 +8970,7 @@ export interface SourceMapGenerator { toString(): string; } -/* @internal */ +/** @internal */ export interface DocumentPositionMapperHost { getSourceFileLike(fileName: string): SourceFileLike | undefined; getCanonicalFileName(path: string): string; @@ -8857,20 +8979,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; @@ -8894,12 +9017,12 @@ export interface GetEffectiveTypeRootsHost { getCurrentDirectory?(): string; } -/* @internal */ +/** @internal */ export interface HasCurrentDirectory { getCurrentDirectory(): string; } -/*@internal*/ +/** @internal */ export interface ModuleSpecifierResolutionHost { useCaseSensitiveFileNames?(): boolean; fileExists(path: string): boolean; @@ -8919,26 +9042,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; @@ -8949,7 +9072,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 @@ -8979,7 +9102,7 @@ export interface TextChangeRange { newLength: number; } -/* @internal */ +/** @internal */ export interface DiagnosticCollection { // Adds a diagnostic to this diagnostic collection. add(diagnostic: Diagnostic): void; @@ -9088,7 +9211,7 @@ export const enum ListFormat { JSDocComment = MultiLine | AsteriskDelimited, } -/* @internal */ +/** @internal */ export const enum PragmaKindFlags { None = 0, /** @@ -9112,14 +9235,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] @@ -9132,7 +9255,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; @@ -9222,15 +9346,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; @@ -9274,7 +9399,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 e077ec8d900f7..71009dd489b47 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); @@ -460,10 +467,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); @@ -526,9 +534,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); @@ -539,9 +548,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); @@ -552,11 +562,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 @@ -691,18 +702,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; @@ -915,19 +928,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); } @@ -982,9 +999,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 @@ -1691,12 +1709,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) { @@ -1962,9 +1981,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) { @@ -2016,7 +2036,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. @@ -2024,6 +2043,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) { @@ -2090,9 +2111,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; @@ -2100,9 +2122,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; @@ -2455,11 +2478,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 */ @@ -2482,18 +2506,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); @@ -2527,8 +2553,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) && @@ -2539,8 +2568,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)); @@ -2555,10 +2587,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) { @@ -2574,7 +2607,6 @@ export function getAssignedExpandoInitializer(node: Node | undefined): Expressio } } -/** @internal */ /** * Recognized expando initializers are: * 1. (function() {})() -- IIFEs @@ -2584,6 +2616,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)) { @@ -2625,8 +2659,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; @@ -2639,7 +2676,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 @@ -2648,6 +2684,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)) { @@ -2712,27 +2750,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) || @@ -2784,8 +2834,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; @@ -2797,7 +2848,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; @@ -3139,8 +3190,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; @@ -3193,8 +3247,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) { @@ -3302,10 +3359,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) { @@ -3361,11 +3419,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; @@ -3603,8 +3662,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 : @@ -3746,7 +3808,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. @@ -3754,6 +3815,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); @@ -3838,9 +3901,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"; @@ -4454,11 +4518,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 = @@ -4510,11 +4575,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; @@ -4784,9 +4850,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); @@ -4835,9 +4902,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] : @@ -4851,8 +4919,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'."); @@ -4867,7 +4938,6 @@ export interface EmitFileNames { buildInfoPath?: string | undefined; } -/** @internal */ /** * Gets the source files that are expected to have an emit output. * @@ -4876,6 +4946,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(); @@ -4899,8 +4971,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)) && @@ -4987,8 +5062,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; @@ -5085,11 +5163,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; @@ -5103,10 +5182,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) ? @@ -5124,10 +5204,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); @@ -5194,10 +5275,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, @@ -5448,11 +5530,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); @@ -5463,11 +5546,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); @@ -5489,21 +5573,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; @@ -5571,8 +5657,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; @@ -5732,8 +5821,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)); } @@ -5777,9 +5869,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 = ""; @@ -5925,43 +6018,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; @@ -5970,9 +6067,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; @@ -5981,22 +6079,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); @@ -6077,10 +6177,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); @@ -6146,8 +6247,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; } @@ -6241,9 +6345,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 @@ -6264,9 +6369,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, @@ -6294,9 +6400,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 @@ -6370,8 +6477,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; @@ -6633,12 +6743,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)) { @@ -7361,10 +7471,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); @@ -7473,8 +7584,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); @@ -7494,8 +7608,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); @@ -7635,9 +7752,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 */ @@ -7755,10 +7873,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("*"); @@ -7785,8 +7904,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; } @@ -7796,10 +7918,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); @@ -7828,11 +7951,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[] = []; @@ -7922,10 +8046,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; @@ -8061,8 +8186,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; @@ -8070,8 +8196,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; @@ -8079,8 +8206,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); } @@ -8088,18 +8216,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 { @@ -8111,10 +8241,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 { @@ -8126,10 +8257,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 { @@ -8146,10 +8278,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 { @@ -8182,19 +8315,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); @@ -8326,7 +8461,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 046ee571a4d03..4ef6c79ebde1d 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 0dfc5fa92ee56..5048c99522a49 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, @@ -719,9 +726,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()))); @@ -798,9 +806,10 @@ export interface CreateWatchCompilerHostOfConfigFileInput({ configFileName, optionsToExtend, watchOptionsToExtend, extraFileExtensions, @@ -823,9 +832,10 @@ export interface CreateWatchCompilerHostOfFilesAndCompilerOptionsInput({ rootFiles, options, watchOptions, projectReferences, diff --git a/src/compiler/watchPublic.ts b/src/compiler/watchPublic.ts index cc7bfb9fc815a..cce52629b8b1a 100644 --- a/src/compiler/watchPublic.ts +++ b/src/compiler/watchPublic.ts @@ -25,7 +25,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) { @@ -141,9 +141,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; @@ -204,8 +206,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; @@ -214,8 +217,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 066e952bd0dcf..3b531914d532d 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 22ad7f82051b5..919c1fad7bf73 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 f74c962b38f4c..b8f98c3969efe 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 bed85b5649731..09600bc485250 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 1178bd48d4115..b34a462c0cd4f 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): (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; };