Fix all internal JSDoc comments

If these are regular comments, then they won't appear in our d.ts files.
But, now we are relying on an external d.ts bundler to produce our final
merged, so they need to be present in the "input" d.ts files, meaning
they have to be JSDoc comments.

These comments only work today because all of our builds load their TS
files from scratch, so they see the actual source files and their
non-JSDoc comments.

The comments also need to be attached to a declaration, not floating,
otherwise they won't be used by api-extractor, so move them if needed.

src/compiler/commandLineParser.ts

@@ -21,7 +21,7 @@ import {
     unescapeLeadingUnderscores, WatchDirectoryFlags, WatchDirectoryKind, WatchFileKind, WatchOptions,
 } from "./_namespaces/ts";
 
-/* @internal */
+/** @internal */
 export const compileOnSaveCommandLineOption: CommandLineOption = {
     name: "compileOnSave",
     type: "boolean",
@@ -36,7 +36,7 @@ const jsxOptionMap = new Map(getEntries({
     "react-jsxdev": JsxEmit.ReactJSXDev,
 }));
 
-/* @internal */
+/** @internal */
 export const inverseJsxOptionMap = new Map(arrayFrom(mapIterator(jsxOptionMap.entries(), ([key, value]: [string, JsxEmit]) => ["" + value, key] as const)));
 
 // NOTE: The order here is important to default lib ordering as entries will have the same
@@ -122,19 +122,21 @@ const libEntries: [string, string][] = [
  * An array of supported "lib" reference file names used to determine the order for inclusion
  * when referenced, as well as for spelling suggestions. This ensures the correct ordering for
  * overload resolution when a type declared in one lib is extended by another.
+ *
+ * @internal
  */
-/* @internal */
 export const libs = libEntries.map(entry => entry[0]);
 
 /**
  * A map of lib names to lib files. This map is used both for parsing the "lib" command line
  * option as well as for resolving lib reference directives.
+ *
+ * @internal
  */
-/* @internal */
 export const libMap = new Map(libEntries);
 
 // Watch related options
-/* @internal */
+/** @internal */
 export const optionsForWatch: CommandLineOption[] = [
     {
         name: "watchFile",
@@ -207,7 +209,7 @@ export const optionsForWatch: CommandLineOption[] = [
     },
 ];
 
-/* @internal */
+/** @internal */
 export const commonOptionsWithBuild: CommandLineOption[] = [
     {
         name: "help",
@@ -395,7 +397,7 @@ export const commonOptionsWithBuild: CommandLineOption[] = [
     },
 ];
 
-/* @internal */
+/** @internal */
 export const targetOptionDeclaration: CommandLineOptionOfCustomType = {
     name: "target",
     shortName: "t",
@@ -424,7 +426,7 @@ export const targetOptionDeclaration: CommandLineOptionOfCustomType = {
     defaultValueDescription: ScriptTarget.ES3,
 };
 
-/*@internal*/
+/** @internal */
 export const moduleOptionDeclaration: CommandLineOptionOfCustomType = {
     name: "module",
     shortName: "m",
@@ -1372,42 +1374,42 @@ const commandOptionsWithoutBuild: CommandLineOption[] = [
     }
 ];
 
-/* @internal */
+/** @internal */
 export const optionDeclarations: CommandLineOption[] = [
     ...commonOptionsWithBuild,
     ...commandOptionsWithoutBuild,
 ];
 
-/* @internal */
+/** @internal */
 export const semanticDiagnosticsOptionDeclarations: readonly CommandLineOption[] =
     optionDeclarations.filter(option => !!option.affectsSemanticDiagnostics);
 
-/* @internal */
+/** @internal */
 export const affectsEmitOptionDeclarations: readonly CommandLineOption[] =
     optionDeclarations.filter(option => !!option.affectsEmit);
 
-/* @internal */
+/** @internal */
 export const affectsDeclarationPathOptionDeclarations: readonly CommandLineOption[] =
     optionDeclarations.filter(option => !!option.affectsDeclarationPath);
 
-/* @internal */
+/** @internal */
 export const moduleResolutionOptionDeclarations: readonly CommandLineOption[] =
     optionDeclarations.filter(option => !!option.affectsModuleResolution);
 
-/* @internal */
+/** @internal */
 export const sourceFileAffectingCompilerOptions: readonly CommandLineOption[] = optionDeclarations.filter(option =>
     !!option.affectsSourceFile || !!option.affectsModuleResolution || !!option.affectsBindDiagnostics);
 
-/* @internal */
+/** @internal */
 export const optionsAffectingProgramStructure: readonly CommandLineOption[] =
     optionDeclarations.filter(option => !!option.affectsProgramStructure);
 
-/* @internal */
+/** @internal */
 export const transpileOptionValueCompilerOptions: readonly CommandLineOption[] = optionDeclarations.filter(option =>
     hasProperty(option, "transpileOptionValue"));
 
 // Build related options
-/* @internal */
+/** @internal */
 export const optionsForBuild: CommandLineOption[] = [
     {
         name: "verbose",
@@ -1442,13 +1444,13 @@ export const optionsForBuild: CommandLineOption[] = [
     }
 ];
 
-/* @internal */
+/** @internal */
 export const buildOpts: CommandLineOption[] = [
     ...commonOptionsWithBuild,
     ...optionsForBuild
 ];
 
-/* @internal */
+/** @internal */
 export const typeAcquisitionDeclarations: CommandLineOption[] = [
     {
         /* @deprecated typingOptions.enableAutoDiscovery
@@ -1486,13 +1488,13 @@ export const typeAcquisitionDeclarations: CommandLineOption[] = [
     },
 ];
 
-/* @internal */
+/** @internal */
 export interface OptionsNameMap {
     optionsNameMap: ESMap<string, CommandLineOption>;
     shortOptionNames: ESMap<string, string>;
 }
 
-/*@internal*/
+/** @internal */
 export function createOptionNameMap(optionDeclarations: readonly CommandLineOption[]): OptionsNameMap {
     const optionsNameMap = new Map<string, CommandLineOption>();
     const shortOptionNames = new Map<string, string>();
@@ -1508,7 +1510,7 @@ export function createOptionNameMap(optionDeclarations: readonly CommandLineOpti
 
 let optionsNameMapCache: OptionsNameMap;
 
-/* @internal */
+/** @internal */
 export function getOptionsNameMap(): OptionsNameMap {
     return optionsNameMapCache ||= createOptionNameMap(optionDeclarations);
 }
@@ -1518,7 +1520,7 @@ const compilerOptionsAlternateMode: AlternateModeDiagnostics = {
     getOptionsNameMap: getBuildOptionsNameMap
 };
 
-/* @internal */
+/** @internal */
 export const defaultInitCompilerOptions: CompilerOptions = {
     module: ModuleKind.CommonJS,
     target: ScriptTarget.ES2016,
@@ -1528,7 +1530,7 @@ export const defaultInitCompilerOptions: CompilerOptions = {
     skipLibCheck: true
 };
 
-/* @internal */
+/** @internal */
 export function convertEnableAutoDiscoveryToEnable(typeAcquisition: TypeAcquisition): TypeAcquisition {
     // Convert deprecated typingOptions.enableAutoDiscovery to typeAcquisition.enable
     if (typeAcquisition && typeAcquisition.enableAutoDiscovery !== undefined && typeAcquisition.enable === undefined) {
@@ -1541,7 +1543,7 @@ export function convertEnableAutoDiscoveryToEnable(typeAcquisition: TypeAcquisit
     return typeAcquisition;
 }
 
-/* @internal */
+/** @internal */
 export function createCompilerDiagnosticForInvalidCustomType(opt: CommandLineOptionOfCustomType): Diagnostic {
     return createDiagnosticForInvalidCustomType(opt, createCompilerDiagnostic);
 }
@@ -1551,12 +1553,12 @@ function createDiagnosticForInvalidCustomType(opt: CommandLineOptionOfCustomType
     return createDiagnostic(Diagnostics.Argument_for_0_option_must_be_Colon_1, `--${opt.name}`, namesOfType);
 }
 
-/* @internal */
+/** @internal */
 export function parseCustomTypeOption(opt: CommandLineOptionOfCustomType, value: string, errors: Push<Diagnostic>) {
     return convertJsonOptionOfCustomType(opt, trimString(value || ""), errors);
 }
 
-/* @internal */
+/** @internal */
 export function parseListTypeOption(opt: CommandLineOptionOfListType, value = "", errors: Push<Diagnostic>): (string | number)[] | undefined {
     value = trimString(value);
     if (startsWith(value, "-")) {
@@ -1576,12 +1578,12 @@ export function parseListTypeOption(opt: CommandLineOptionOfListType, value = ""
     }
 }
 
-/*@internal*/
+/** @internal */
 export interface OptionsBase {
     [option: string]: CompilerOptionsValue | TsConfigSourceFile | undefined;
 }
 
-/*@internal*/
+/** @internal */
 export interface ParseCommandLineWorkerDiagnostics extends DidYouMeanOptionsDiagnostics {
     getOptionsNameMap: () => OptionsNameMap;
     optionTypeMismatchDiagnostic: DiagnosticMessage;
@@ -1607,7 +1609,7 @@ function createUnknownOptionError(
         createDiagnostics(diagnostics.unknownOptionDiagnostic, unknownOptionErrorText || unknownOption);
 }
 
-/*@internal*/
+/** @internal */
 export function parseCommandLineWorker(
     diagnostics: ParseCommandLineWorkerDiagnostics,
     commandLine: readonly string[],
@@ -1764,7 +1766,7 @@ function parseOptionValue(
     return i;
 }
 
-/*@internal*/
+/** @internal */
 export const compilerOptionsDidYouMeanDiagnostics: ParseCommandLineWorkerDiagnostics = {
     alternateMode: compilerOptionsAlternateMode,
     getOptionsNameMap,
@@ -1795,7 +1797,7 @@ function getOptionDeclarationFromName(getOptionNameMap: () => OptionsNameMap, op
     return optionsNameMap.get(optionName);
 }
 
-/*@internal*/
+/** @internal */
 export interface ParsedBuildCommand {
     buildOptions: BuildOptions;
     watchOptions: WatchOptions | undefined;
@@ -1822,7 +1824,7 @@ const buildOptionsDidYouMeanDiagnostics: ParseCommandLineWorkerDiagnostics = {
     optionTypeMismatchDiagnostic: Diagnostics.Build_option_0_requires_a_value_of_type_1
 };
 
-/*@internal*/
+/** @internal */
 export function parseBuildCommand(args: readonly string[]): ParsedBuildCommand {
     const { options, watchOptions, fileNames: projects, errors } = parseCommandLineWorker(
         buildOptionsDidYouMeanDiagnostics,
@@ -1852,7 +1854,7 @@ export function parseBuildCommand(args: readonly string[]): ParsedBuildCommand {
     return { buildOptions, watchOptions, projects, errors };
 }
 
-/* @internal */
+/** @internal */
 export function getDiagnosticText(_message: DiagnosticMessage, ..._args: any[]): string {
     const diagnostic = createCompilerDiagnostic.apply(undefined, arguments);
     return diagnostic.messageText as string;
@@ -1942,7 +1944,7 @@ export function readJsonConfigFile(fileName: string, readFile: (path: string) =>
     return isString(textOrDiagnostic) ? parseJsonText(fileName, textOrDiagnostic) : { fileName, parseDiagnostics: [textOrDiagnostic] } as TsConfigSourceFile;
 }
 
-/*@internal*/
+/** @internal */
 export function tryReadFile(fileName: string, readFile: (path: string) => string | undefined): string | Diagnostic {
     let text: string | undefined;
     try {
@@ -2070,7 +2072,7 @@ function getTsconfigRootOptionsMap() {
     return _tsconfigRootOptions;
 }
 
-/*@internal*/
+/** @internal */
 interface JsonConversionNotifier {
     /**
      * Notifies parent option object is being set with the optionKey and a valid optionValue
@@ -2134,8 +2136,9 @@ export function convertToObject(sourceFile: JsonSourceFile, errors: Push<Diagnos
  * Convert the json syntax tree into the json value and report errors
  * This returns the json value (apart from checking errors) only if returnValue provided is true.
  * Otherwise it just checks the errors and returns undefined
+ *
+ * @internal
  */
-/*@internal*/
 export function convertToObjectWorker(
     sourceFile: JsonSourceFile,
     rootExpression: Expression | undefined,
@@ -2381,8 +2384,9 @@ export interface ConvertToTSConfigHost {
  * @param configParseResult options to be generated into tsconfig.json
  * @param configFileName name of the parsed config file - output paths will be generated relative to this
  * @param host provides current directory and case sensitivity services
+ *
+ * @internal
  */
-/** @internal */
 export function convertToTSConfig(configParseResult: ParsedCommandLine, configFileName: string, host: ConvertToTSConfigHost): TSConfig {
     const getCanonicalFileName = createGetCanonicalFileName(host.useCaseSensitiveFileNames);
     const files = map(
@@ -2425,7 +2429,7 @@ export function convertToTSConfig(configParseResult: ParsedCommandLine, configFi
     return config;
 }
 
-/*@internal*/
+/** @internal */
 export function optionMapToObject(optionMap: ESMap<string, CompilerOptionsValue>): object {
     return {
         ...arrayFrom(optionMap.entries()).reduce((prev, cur) => ({ ...prev, [cur[0]]: cur[1] }), {}),
@@ -2469,7 +2473,7 @@ function getCustomTypeMapOfCommandLineOption(optionDefinition: CommandLineOption
     }
 }
 
-/* @internal */
+/** @internal */
 export function getNameOfCompilerOptionValue(value: CompilerOptionsValue, customTypeMap: ESMap<string, string | number>): string | undefined {
     // There is a typeMap associated with this command-line option so use it to map value back to its name
     return forEachEntry(customTypeMap, (mapValue, key) => {
@@ -2479,7 +2483,7 @@ export function getNameOfCompilerOptionValue(value: CompilerOptionsValue, custom
     });
 }
 
-/* @internal */
+/** @internal */
 export function serializeCompilerOptions(
     options: CompilerOptions,
     pathOptions?: { configFilePath: string, useCaseSensitiveFileNames: boolean }
@@ -2580,8 +2584,9 @@ function getSerializedCompilerOption(options: CompilerOptions): ESMap<string, Co
  * Generate tsconfig configuration when running command line "--init"
  * @param options commandlineOptions to be generated into tsconfig.json
  * @param fileNames array of filenames to be generated into tsconfig.json
+ *
+ * @internal
  */
-/* @internal */
 export function generateTSConfig(options: CompilerOptions, fileNames: readonly string[], newLine: string): string {
     const compilerOptionsMap = getSerializedCompilerOption(options);
     return writeConfigurations();
@@ -2670,7 +2675,7 @@ export function generateTSConfig(options: CompilerOptions, fileNames: readonly s
     }
 }
 
-/* @internal */
+/** @internal */
 export function convertToOptionsWithAbsolutePaths(options: CompilerOptions, toAbsolutePath: (path: string) => string) {
     const result: CompilerOptions = {};
     const optionsNameMap = getOptionsNameMap().optionsNameMap;
@@ -2730,7 +2735,7 @@ export function parseJsonSourceFileConfigFileContent(sourceFile: TsConfigSourceF
     return result;
 }
 
-/*@internal*/
+/** @internal */
 export function setConfigFileInOptions(options: CompilerOptions, configFile: TsConfigSourceFile | undefined) {
     if (configFile) {
         Object.defineProperty(options, "configFile", { enumerable: false, writable: false, value: configFile });
@@ -2747,7 +2752,7 @@ function directoryOfCombinedPath(fileName: string, basePath: string) {
     return getDirectoryPath(getNormalizedAbsolutePath(fileName, basePath));
 }
 
-/*@internal*/
+/** @internal */
 export const defaultIncludeSpec = "**/*";
 
 /**
@@ -2947,12 +2952,12 @@ function shouldReportNoInputFiles(fileNames: string[], canJsonReportNoInutFiles:
     return fileNames.length === 0 && canJsonReportNoInutFiles && (!resolutionStack || resolutionStack.length === 0);
 }
 
-/*@internal*/
+/** @internal */
 export function canJsonReportNoInputFiles(raw: any) {
     return !hasProperty(raw, "files") && !hasProperty(raw, "references");
 }
 
-/*@internal*/
+/** @internal */
 export function updateErrorForNoInputFiles(fileNames: string[], configFileName: string, configFileSpecs: ConfigFileSpecs, configParseDiagnostics: Diagnostic[], canJsonReportNoInutFiles: boolean) {
     const existingErrors = configParseDiagnostics.length;
     if (shouldReportNoInputFiles(fileNames, canJsonReportNoInutFiles)) {
@@ -3308,7 +3313,7 @@ function convertOptionsFromJson(optionsNameMap: ESMap<string, CommandLineOption>
     return defaultOptions;
 }
 
-/*@internal*/
+/** @internal */
 export function convertJsonOption(opt: CommandLineOption, value: any, basePath: string, errors: Push<Diagnostic>): CompilerOptionsValue {
     if (isCompilerOptionsValue(opt, value)) {
         const optType = opt.type;
@@ -3410,8 +3415,9 @@ const wildcardDirectoryPattern = /^[^*?]*(?=\/[^/]*[*?])/;
  * @param options Compiler options.
  * @param host The host used to resolve files and directories.
  * @param extraFileExtensions optionaly file extra file extension information from host
+ *
+ * @internal
  */
-/* @internal */
 export function getFileNamesFromConfigSpecs(
     configFileSpecs: ConfigFileSpecs,
     basePath: string,
@@ -3501,7 +3507,7 @@ export function getFileNamesFromConfigSpecs(
     return literalFiles.concat(wildcardFiles, arrayFrom(wildCardJsonFileMap.values()));
 }
 
-/* @internal */
+/** @internal */
 export function isExcludedFile(
     pathToCheck: string,
     spec: ConfigFileSpecs,
@@ -3538,7 +3544,7 @@ function invalidDotDotAfterRecursiveWildcard(s: string) {
     return lastDotIndex > wildcardIndex;
 }
 
-/* @internal */
+/** @internal */
 export function matchesExclude(
     pathToCheck: string,
     excludeSpecs: readonly string[] | undefined,
@@ -3729,8 +3735,9 @@ function removeWildcardFilesWithLowerPriorityExtension(file: string, wildcardFil
 /**
  * Produces a cleaned version of compiler options with personally identifying info (aka, paths) removed.
  * Also converts enum values back to strings.
+ *
+ * @internal
  */
-/* @internal */
 export function convertCompilerOptionsForTelemetry(opts: CompilerOptions): CompilerOptions {
     const out: CompilerOptions = {};
     for (const key in opts) {