Mark APIs at internal and include JSDoc in types

js/assets.ts

@@ -46,7 +46,7 @@ import textEncodingDts from "/third_party/node_modules/@types/text-encoding/inde
 import typescriptDts from "/third_party/node_modules/typescript/lib/typescript.d.ts!string";
 // tslint:enable:max-line-length
 
-// prettier-ignore
+// @internal
 export const assetSourceCode: { [key: string]: string } = {
   // Generated library
   "globals.d.ts": globalsDts,
@@ -85,5 +85,5 @@ export const assetSourceCode: { [key: string]: string } = {
   "fetch-types.d.ts": fetchTypesDts,
   "flatbuffers.d.ts": flatbuffersDts,
   "text-encoding.d.ts": textEncodingDts,
-  "typescript.d.ts": typescriptDts,
+  "typescript.d.ts": typescriptDts
 };

js/compiler.ts

@@ -50,6 +50,7 @@ type OutputCode = string;
 /**
  * Abstraction of the APIs required from the `os` module so they can be
  * easily mocked.
+ * @internal
  */
 export interface Os {
   codeCache: typeof os.codeCache;
@@ -60,6 +61,7 @@ export interface Os {
 /**
  * Abstraction of the APIs required from the `typescript` module so they can
  * be easily mocked.
+ * @internal
  */
 export interface Ts {
   createLanguageService: typeof ts.createLanguageService;

js/compiler_test.ts

@@ -177,7 +177,7 @@ function globalEvalMock(x: string): void {
 function logMock(...args: any[]): void {
   logStack.push(args);
 }
-const osMock: compiler.Os = {
+const osMock = {
   codeCache(fileName: string, sourceCode: string, outputCode: string): void {
     codeCacheStack.push({ fileName, sourceCode, outputCode });
     if (fileName in moduleCache) {
@@ -205,7 +205,7 @@ const osMock: compiler.Os = {
     throw new Error(`os.exit(${code})`);
   }
 };
-const tsMock: compiler.Ts = {
+const tsMock = {
   createLanguageService(host: ts.LanguageServiceHost): ts.LanguageService {
     return {} as ts.LanguageService;
   },

js/errors.ts

@@ -1,5 +1,6 @@
 import { deno as fbs } from "gen/msg_generated";
 
+// @internal
 export class DenoError<T extends fbs.ErrorKind> extends Error {
   constructor(readonly kind: T, msg: string) {
     super(msg);
@@ -7,6 +8,7 @@ export class DenoError<T extends fbs.ErrorKind> extends Error {
   }
 }
 
+// @internal
 export function maybeThrowError(base: fbs.Base): void {
   const kind = base.errorKind();
   if (kind !== fbs.ErrorKind.NoError) {

js/fbs_util.ts

@@ -4,6 +4,7 @@ import { flatbuffers } from "flatbuffers";
 import { maybeThrowError } from "./errors";
 import { deno as fbs } from "gen/msg_generated";
 
+// @internal
 export function send(
   builder: flatbuffers.Builder,
   msgType: fbs.Any,

js/global-eval.ts

@@ -1,6 +1,10 @@
-// If you use the eval function indirectly, by invoking it via a reference
-// other than eval, as of ECMAScript 5 it works in the global scope rather than
-// the local scope. This means, for instance, that function declarations create
-// global functions, and that the code being evaluated doesn't have access to
-// local variables within the scope where it's being called.
+/**
+ * If you use the eval function indirectly, by invoking it via a reference
+ * other than eval, as of ECMAScript 5 it works in the global scope rather than
+ * the local scope. This means, for instance, that function declarations create
+ * global functions, and that the code being evaluated doesn't have access to
+ * local variables within the scope where it's being called.
+ *
+ * @internal
+ */
 export const globalEval = eval;

js/tsconfig.generated.json

@@ -8,6 +8,7 @@
     "declaration": true,
     "emitDeclarationOnly": true,
     "module": "amd",
+    "removeComments": false,
     "stripInternal": true
   },
   "files": [

js/util.ts

@@ -3,11 +3,15 @@ import { TypedArray } from "./types";
 
 let logDebug = false;
 
+// @internal
 export function setLogDebug(debug: boolean): void {
   logDebug = debug;
 }
 
-// Debug logging for deno. Enable with the --DEBUG command line flag.
+/**
+ * Debug logging for deno. Enable with the `--DEBUG` command line flag.
+ * @internal
+ */
 // tslint:disable-next-line:no-any
 export function log(...args: any[]): void {
   if (logDebug) {
@@ -15,41 +19,51 @@ export function log(...args: any[]): void {
   }
 }
 
+// @internal
 export function assert(cond: boolean, msg = "assert") {
   if (!cond) {
     throw Error(msg);
   }
 }
 
+// @internal
 export function typedArrayToArrayBuffer(ta: TypedArray): ArrayBuffer {
   const ab = ta.buffer.slice(ta.byteOffset, ta.byteOffset + ta.byteLength);
   return ab as ArrayBuffer;
 }
 
+// @internal
 export function arrayToStr(ui8: Uint8Array): string {
   return String.fromCharCode(...ui8);
 }
 
-// A `Resolvable` is a Promise with the `reject` and `resolve` functions
-// placed as methods on the promise object itself. It allows you to do:
-//
-//   const p = createResolvable<number>();
-//   ...
-//   p.resolve(42);
-//
-// It'd be prettier to make Resolvable a class that inherits from Promise,
-// rather than an interface. This is possible in ES2016, however typescript
-// produces broken code when targeting ES5 code.
-// See https://github.com/Microsoft/TypeScript/issues/15202
-// At the time of writing, the github issue is closed but the problem remains.
+/**
+ * A `Resolvable` is a Promise with the `reject` and `resolve` functions
+ * placed as methods on the promise object itself. It allows you to do:
+ *
+ *     const p = createResolvable<number>();
+ *     ...
+ *     p.resolve(42);
+ *
+ * It'd be prettier to make Resolvable a class that inherits from Promise,
+ * rather than an interface. This is possible in ES2016, however typescript
+ * produces broken code when targeting ES5 code.
+ * See https://github.com/Microsoft/TypeScript/issues/15202
+ * At the time of writing, the github issue is closed but the problem remains.
+ *
+ * @internal
+ */
+
 export interface ResolvableMethods<T> {
   resolve: (value?: T | PromiseLike<T>) => void;
   // tslint:disable-next-line:no-any
   reject: (reason?: any) => void;
 }
 
+// @internal
 export type Resolvable<T> = Promise<T> & ResolvableMethods<T>;
 
+// @internal
 export function createResolvable<T>(): Resolvable<T> {
   let methods: ResolvableMethods<T>;
   const promise = new Promise<T>((resolve, reject) => {
@@ -60,10 +74,12 @@ export function createResolvable<T>(): Resolvable<T> {
   return Object.assign(promise, methods!) as Resolvable<T>;
 }
 
+// @internal
 export function notImplemented(): never {
   throw new Error("Not implemented");
 }
 
+// @internal
 export function unreachable(): never {
   throw new Error("Code not reachable");
 }

js/v8_source_maps.ts

@@ -26,6 +26,7 @@ type GetGeneratedContentsCallback = (fileName: string) => string | RawSourceMap;
 
 let getGeneratedContents: GetGeneratedContentsCallback;
 
+// @internal
 export function install(options: Options) {
   getGeneratedContents = options.getGeneratedContents;
   if (options.installPrepareStackTrace) {
@@ -33,6 +34,7 @@ export function install(options: Options) {
   }
 }
 
+// @internal
 export function prepareStackTraceWrapper(
   error: Error,
   stack: CallSite[]
@@ -48,6 +50,7 @@ export function prepareStackTraceWrapper(
   }
 }
 
+// @internal
 export function prepareStackTrace(error: Error, stack: CallSite[]): string {
   const frames = stack.map(
     (frame: CallSite) => `\n    at ${wrapCallSite(frame).toString()}`
@@ -55,6 +58,7 @@ export function prepareStackTrace(error: Error, stack: CallSite[]): string {
   return error.toString() + frames.join("");
 }
 
+// @internal
 export function wrapCallSite(frame: CallSite): CallSite {
   if (frame.isNative()) {
     return frame;

tests/error_003_typescript.ts.out

@@ -4,7 +4,7 @@
   ~~~~~~
 
   $asset$/globals.d.tsILDCARD]
-    [WILDCARD][0m         const console: Console;
-                      ~~~~~~~
-    'console' is declared here.
+[WILDCARD]const console: Console;
+[WILDCARD]~~~~~~~
+[WILDCARD]'console' is declared here.