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.

Author: jakebailey

Diff for: 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 for: scripts/processDiagnosticMessages.mjs

@@ -9,6 +9,7 @@ import fs from "fs";
     isEarly?: boolean;
     elidedInCompatabilityPyramid?: boolean;
 }} DiagnosticDetails */
+void 0;
 
 /** @typedef {Map<string, DiagnosticDetails>} InputDiagnosticMessageTable */
 

Diff for: scripts/word2md.mjs

@@ -60,6 +60,7 @@ const sys = (() => {
         subscript?: boolean;
     };
 }} FindReplaceOptions */
+void 0;
 
 /**
  * @param {Word.Document} doc

Diff for: src/compiler/builder.ts

@@ -39,8 +39,11 @@ export interface ReusableDiagnosticRelatedInformation {
 /** @internal */
 export type ReusableDiagnosticMessageChain = DiagnosticMessageChain;
 
-/** @internal */
-/** Signature (Hash of d.ts emitted), is string if it was emitted using same d.ts.map option as what compilerOptions indicate, otherwise tuple of string */
+/**
+ * Signature (Hash of d.ts emitted), is string if it was emitted using same d.ts.map option as what compilerOptions indicate, otherwise tuple of string
+ *
+ * @internal
+ */
 export type EmitSignature = string | [signature: string];
 
 /** @internal */
@@ -105,9 +108,10 @@ export const enum BuilderFileEmit {
     All                 = AllJs | AllDts,
 }
 
-/** @internal */
 /**
  * State to store the changed files, affected files and cache semantic diagnostics
+ *
+ * @internal
  */
 // TODO: GH#18217 Properties of this interface are frequently asserted to be defined.
 export interface BuilderProgramState extends BuilderState, ReusableBuilderProgramState {
@@ -174,8 +178,11 @@ export type SavedBuildProgramEmitState = Pick<BuilderProgramState,
     "hasChangedEmitSignature"
 > & { changedFilesSet: BuilderProgramState["changedFilesSet"] | undefined };
 
-/** @internal */
-/** Get flags determining what all needs to be emitted */
+/**
+ * Get flags determining what all needs to be emitted
+ *
+ * @internal
+ */
 export function getBuilderFileEmit(options: CompilerOptions) {
     let result = BuilderFileEmit.Js;
     if (options.sourceMap) result = result | BuilderFileEmit.JsMap;
@@ -186,8 +193,11 @@ export function getBuilderFileEmit(options: CompilerOptions) {
     return result;
 }
 
-/** @internal */
-/** Determing what all is pending to be emitted based on previous options or previous file emit flags */
+/**
+ * Determing what all is pending to be emitted based on previous options or previous file emit flags
+ *
+ * @internal
+ */
 export function getPendingEmitKind(optionsOrEmitKind: CompilerOptions | BuilderFileEmit, oldOptionsOrEmitKind: CompilerOptions | BuilderFileEmit | undefined): BuilderFileEmit {
     const oldEmitKind = oldOptionsOrEmitKind && (isNumber(oldOptionsOrEmitKind) ? oldOptionsOrEmitKind : getBuilderFileEmit(oldOptionsOrEmitKind));
     const emitKind = isNumber(optionsOrEmitKind) ? optionsOrEmitKind : getBuilderFileEmit(optionsOrEmitKind);
@@ -821,11 +831,12 @@ export type ProgramBuildInfoFileId = number & { __programBuildInfoFileIdBrand: a
 export type ProgramBuildInfoFileIdListId = number & { __programBuildInfoFileIdListIdBrand: any };
 /** @internal */
 export type ProgramBuildInfoDiagnostic = ProgramBuildInfoFileId | [fileId: ProgramBuildInfoFileId, diagnostics: readonly ReusableDiagnostic[]];
-/** @internal */
 /**
  * fileId if pending emit is same as what compilerOptions suggest
  * [fileId] if pending emit is only dts file emit
  * [fileId, emitKind] if any other type emit is pending
+ *
+ * @internal
  */
 export type ProgramBuilderInfoFilePendingEmit = ProgramBuildInfoFileId | [fileId: ProgramBuildInfoFileId] | [fileId: ProgramBuildInfoFileId, emitKind: BuilderFileEmit];
 /** @internal */
@@ -840,15 +851,17 @@ export type ProgramMultiFileEmitBuildInfoBuilderStateFileInfo = Omit<BuilderStat
      */
     signature: string | false | undefined;
 };
-/** @internal */
 /**
  * [fileId, signature] if different from file's signature
  * fileId if file wasnt emitted
+ *
+ * @internal
  */
 export type ProgramBuildInfoEmitSignature = ProgramBuildInfoFileId | [fileId: ProgramBuildInfoFileId, signature: EmitSignature | []];
-/** @internal */
 /**
  * ProgramMultiFileEmitBuildInfoFileInfo is string if FileInfo.version === FileInfo.signature && !FileInfo.affectsGlobalScope otherwise encoded FileInfo
+ *
+ * @internal
  */
 export type ProgramMultiFileEmitBuildInfoFileInfo = string | ProgramMultiFileEmitBuildInfoBuilderStateFileInfo;
 /** @internal */
@@ -866,15 +879,17 @@ export interface ProgramMultiFileEmitBuildInfo {
     // Because this is only output file in the program, we dont need fileId to deduplicate name
     latestChangedDtsFile?: string | undefined;
 }
-/** @internal */
 /**
  * ProgramBundleEmitBuildInfoFileInfo is string if !FileInfo.impliedFormat otherwise encoded FileInfo
+ *
+ * @internal
  */
 export type ProgramBundleEmitBuildInfoFileInfo = string | BuilderState.FileInfo;
-/** @internal */
 /**
  * false if it is the emit corresponding to compilerOptions
  * value otherwise
+ *
+ * @internal
  */
 export type ProgramBuildInfoBundlePendingEmit = BuilderFileEmit | false;
 /** @internal */

Diff for: src/compiler/builderPublic.ts

@@ -23,46 +23,51 @@ export interface BuilderProgramHost {
     writeFile?: WriteFileCallback;
     /**
      * disable using source file version as signature for testing
+     *
+     * @internal
      */
-    /*@internal*/
     disableUseFileVersionAsSignature?: boolean;
     /**
      * Store the list of files that update signature during the emit
+     *
+     * @internal
      */
-    /*@internal*/
     storeFilesChangingSignatureDuringEmit?: boolean;
     /**
      * Gets the current time
+     *
+     * @internal
      */
-    /*@internal*/
     now?(): Date;
 }
 
 /**
  * Builder to manage the program state changes
  */
 export interface BuilderProgram {
-    /*@internal*/
+    /** @internal */
     getState(): ReusableBuilderProgramState;
-    /*@internal*/
+    /** @internal */
     saveEmitState(): SavedBuildProgramEmitState;
-    /*@internal*/
+    /** @internal */
     restoreEmitState(saved: SavedBuildProgramEmitState): void;
-    /*@internal*/
+    /** @internal */
     hasChangedEmitSignature?(): boolean;
     /**
      * Returns current program
      */
     getProgram(): Program;
     /**
      * Returns current program that could be undefined if the program was released
+     *
+     * @internal
      */
-    /*@internal*/
     getProgramOrUndefined(): Program | undefined;
     /**
      * Releases reference to the program, making all the other operations that need program to fail.
+     *
+     * @internal
      */
-    /*@internal*/
     releaseProgram(): void;
     /**
      * Get compiler options of the program
@@ -122,13 +127,13 @@ export interface BuilderProgram {
      * in that order would be used to write the files
      */
     emit(targetSourceFile?: SourceFile, writeFile?: WriteFileCallback, cancellationToken?: CancellationToken, emitOnlyDtsFiles?: boolean, customTransformers?: CustomTransformers): EmitResult;
-    /*@internal*/
+    /** @internal */
     emitBuildInfo(writeFile?: WriteFileCallback, cancellationToken?: CancellationToken): EmitResult;
     /**
      * Get the current directory of the program
      */
     getCurrentDirectory(): string;
-    /*@internal*/
+    /** @internal */
     close(): void;
 }
 

Diff for: src/compiler/builderStatePublic.ts

@@ -3,12 +3,12 @@ import { Diagnostic, WriteFileCallbackData } from "./_namespaces/ts";
 export interface EmitOutput {
     outputFiles: OutputFile[];
     emitSkipped: boolean;
-    /* @internal */ diagnostics: readonly Diagnostic[];
+    /** @internal */ diagnostics: readonly Diagnostic[];
 }
 
 export interface OutputFile {
     name: string;
     writeByteOrderMark: boolean;
     text: string;
-    /* @internal */ data?: WriteFileCallbackData;
+    /** @internal */ data?: WriteFileCallbackData;
 }