Mark APIs at internal and include JSDoc in types

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");
 }