Remove doc strings from cli/js TS files (#4329)

Co-authored-by: Ryan Dahl <ry@tinyclouds.org>

cli/js/ops/compiler.ts

@@ -4,7 +4,6 @@ import { sendAsync, sendSync } from "./dispatch_json.ts";
 import { TextDecoder, TextEncoder } from "../web/text_encoding.ts";
 import { core } from "../core.ts";
 
-/** Ops to Rust to resolve modules' URLs. */
 export function resolveModules(
   specifiers: string[],
   referrer?: string
@@ -12,7 +11,6 @@ export function resolveModules(
   return sendSync("op_resolve_modules", { specifiers, referrer });
 }
 
-/** Ops to Rust to fetch modules meta data. */
 export function fetchSourceFiles(
   specifiers: string[],
   referrer?: string
@@ -33,7 +31,6 @@ export function fetchSourceFiles(
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
-/** This op is also used during snapshotting */
 export function getAsset(name: string): string {
   const opId = core.ops()["op_fetch_asset"];
   // We really don't want to depend on JSON dispatch during snapshotting, so

cli/js/ops/errors.ts

@@ -2,48 +2,18 @@
 import { DiagnosticItem } from "../diagnostics.ts";
 import { sendSync } from "./dispatch_json.ts";
 
-/**
- * Format an array of diagnostic items and return them as a single string.
- * @param items An array of diagnostic items to format
- */
 export function formatDiagnostics(items: DiagnosticItem[]): string {
   return sendSync("op_format_diagnostic", { items });
 }
 
 export interface Location {
-  /** The full url for the module, e.g. `file://some/file.ts` or
-   * `https://some/file.ts`. */
   filename: string;
 
-  /** The line number in the file.  It is assumed to be 1-indexed. */
   line: number;
 
-  /** The column number in the file.  It is assumed to be 1-indexed. */
   column: number;
 }
 
-/** Given a current location in a module, lookup the source location and
- * return it.
- *
- * When Deno transpiles code, it keep source maps of the transpiled code.  This
- * function can be used to lookup the original location.  This is automatically
- * done when accessing the `.stack` of an error, or when an uncaught error is
- * logged.  This function can be used to perform the lookup for creating better
- * error handling.
- *
- * **Note:** `line` and `column` are 1 indexed, which matches display
- * expectations, but is not typical of most index numbers in Deno.
- *
- * An example:
- *
- *       const orig = Deno.applySourceMap({
- *         location: "file://my/module.ts",
- *         line: 5,
- *         column: 15
- *       });
- *       console.log(`${orig.filename}:${orig.line}:${orig.column}`);
- *
- */
 export function applySourceMap(location: Location): Location {
   const { filename, line, column } = location;
   // On this side, line/column are 1 based, but in the source maps, they are

cli/js/ops/fs/chmod.ts

@@ -1,22 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Synchronously changes the permission of a specific file/directory of
- * specified path.  Ignores the process's umask.
- *
- *       Deno.chmodSync("/path/to/file", 0o666);
- *
- * Requires `allow-write` permission. */
 export function chmodSync(path: string, mode: number): void {
   sendSync("op_chmod", { path, mode });
 }
 
-/** Changes the permission of a specific file/directory of specified path.
- * Ignores the process's umask.
- *
- *       await Deno.chmod("/path/to/file", 0o666);
- *
- * Requires `allow-write` permission. */
 export async function chmod(path: string, mode: number): Promise<void> {
   await sendAsync("op_chmod", { path, mode });
 }

cli/js/ops/fs/chown.ts

@@ -1,28 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Synchronously change owner of a regular file or directory. Linux/Mac OS
- * only at the moment.
- *
- * Requires `allow-write` permission.
- *
- * @param path path to the file
- * @param uid user id of the new owner
- * @param gid group id of the new owner
- */
 export function chownSync(path: string, uid: number, gid: number): void {
   sendSync("op_chown", { path, uid, gid });
 }
 
-/** Change owner of a regular file or directory. Linux/Mac OS only at the
- * moment.
- *
- * Requires `allow-write` permission.
- *
- * @param path path to the file
- * @param uid user id of the new owner
- * @param gid group id of the new owner
- */
 export async function chown(
   path: string,
   uid: number,

cli/js/ops/fs/copy_file.ts

@@ -1,26 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Synchronously copies the contents and permissions of one file to another
- * specified path, by default creating a new file if needed, else overwriting.
- * Fails if target path is a directory or is unwritable.
- *
- *       Deno.copyFileSync("from.txt", "to.txt");
- *
- * Requires `allow-read` permission on fromPath.
- * Requires `allow-write` permission on toPath. */
 export function copyFileSync(fromPath: string, toPath: string): void {
   sendSync("op_copy_file", { from: fromPath, to: toPath });
 }
 
-/** Copies the contents and permissions of one file to another specified path,
- * by default creating a new file if needed, else overwriting. Fails if target
- * path is a directory or is unwritable.
- *
- *       await Deno.copyFile("from.txt", "to.txt");
- *
- * Requires `allow-read` permission on fromPath.
- * Requires `allow-write` permission on toPath. */
 export async function copyFile(
   fromPath: string,
   toPath: string

cli/js/ops/fs/dir.ts

@@ -1,27 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync } from "../dispatch_json.ts";
 
-/**
- * **UNSTABLE**: maybe needs permissions.
- *
- * Return a string representing the current working directory.
- *
- * If the current directory can be reached via multiple paths (due to symbolic
- * links), `cwd()` may return any one of them.
- *
- * Throws `Deno.errors.NotFound` if directory not available.
- */
 export function cwd(): string {
   return sendSync("op_cwd");
 }
 
-/**
- * **UNSTABLE**: maybe needs permissions.
- *
- * Change the current working directory to the specified path.
- *
- * Throws `Deno.errors.NotFound` if directory not available.
- */
 export function chdir(directory: string): void {
   sendSync("op_chdir", { directory });
 }

cli/js/ops/fs/link.ts

@@ -1,20 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Creates `newname` as a hard link to `oldname`.
- *
- *       Deno.linkSync("old/name", "new/name");
- *
- * Requires `allow-read` and `allow-write` permissions. */
 export function linkSync(oldname: string, newname: string): void {
   sendSync("op_link", { oldname, newname });
 }
 
-/** Creates `newname` as a hard link to `oldname`.
- *
- *       await Deno.link("old/name", "new/name");
- *
- * Requires `allow-read` and `allow-write` permissions. */
 export async function link(oldname: string, newname: string): Promise<void> {
   await sendAsync("op_link", { oldname, newname });
 }

cli/js/ops/fs/make_temp.ts

@@ -2,87 +2,25 @@
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
 export interface MakeTempOptions {
-  /** Directory where the temporary directory should be created (defaults to
-   * the env variable TMPDIR, or the system's default, usually /tmp). */
   dir?: string;
-  /** String that should precede the random portion of the temporary
-   * directory's name. */
   prefix?: string;
-  /** String that should follow the random portion of the temporary
-   * directory's name. */
   suffix?: string;
 }
 
-/** Synchronously creates a new temporary directory in the directory `dir`,
- * its name beginning with `prefix` and ending with `suffix`.
- *
- * It returns the full path to the newly created directory.
- *
- * If `dir` is unspecified, uses the default directory for temporary files.
- * Multiple programs calling this function simultaneously will create different
- * directories. It is the caller's responsibility to remove the directory when
- * no longer needed.
- *
- *       const tempDirName0 = Deno.makeTempDirSync();
- *       const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' });
- *
- * Requires `allow-write` permission. */
 export function makeTempDirSync(options: MakeTempOptions = {}): string {
   return sendSync("op_make_temp_dir", options);
 }
 
-/** Creates a new temporary directory in the directory `dir`, its name
- * beginning with `prefix` and ending with `suffix`.
- *
- * It resolves to the full path to the newly created directory.
- *
- * If `dir` is unspecified, uses the default directory for temporary files.
- * Multiple programs calling this function simultaneously will create different
- * directories. It is the caller's responsibility to remove the directory when
- * no longer needed.
- *
- *       const tempDirName0 = await Deno.makeTempDir();
- *       const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' });
- *
- * Requires `allow-write` permission. */
 export async function makeTempDir(
   options: MakeTempOptions = {}
 ): Promise<string> {
   return await sendAsync("op_make_temp_dir", options);
 }
 
-/** Synchronously creates a new temporary file in the directory `dir`, its name
- * beginning with `prefix` and ending with `suffix`.
- *
- * It returns the full path to the newly created file.
- *
- * If `dir` is unspecified, uses the default directory for temporary files.
- * Multiple programs calling this function simultaneously will create different
- * files. It is the caller's responsibility to remove the file when
- * no longer needed.
- *
- *       const tempFileName0 = Deno.makeTempFileSync();
- *       const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' });
- *
- * Requires `allow-write` permission. */
 export function makeTempFileSync(options: MakeTempOptions = {}): string {
   return sendSync("op_make_temp_file", options);
 }
 
-/** Creates a new temporary file in the directory `dir`, its name
- * beginning with `prefix` and ending with `suffix`.
- *
- * It resolves to the full path to the newly created file.
- *
- * If `dir` is unspecified, uses the default directory for temporary files.
- * Multiple programs calling this function simultaneously will create different
- * files. It is the caller's responsibility to remove the file when
- * no longer needed.
- *
- *       const tempFileName0 = await Deno.makeTempFile();
- *       const tempFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' });
- *
- * Requires `allow-write` permission. */
 export async function makeTempFile(
   options: MakeTempOptions = {}
 ): Promise<string> {

cli/js/ops/fs/mkdir.ts

@@ -28,24 +28,10 @@ function mkdirArgs(
 }
 
 export interface MkdirOptions {
-  /** Defaults to `false`. If set to `true`, means that any intermediate
-   * directories will also be created (as with the shell command `mkdir -p`).
-   * Intermediate directories are created with the same permissions.
-   * When recursive is set to `true`, succeeds silently (without changing any
-   * permissions) if a directory already exists at the path. */
   recursive?: boolean;
-  /** Permissions to use when creating the directory (defaults to `0o777`,
-   * before the process's umask).
-   * Ignored on Windows. */
   mode?: number;
 }
 
-/** Synchronously creates a new directory with the specified path.
- *
- *       Deno.mkdirSync("new_dir");
- *       Deno.mkdirSync("nested/directories", { recursive: true });
- *
- * Requires `allow-write` permission. */
 export function mkdirSync(
   path: string,
   optionsOrRecursive?: MkdirOptions | boolean,
@@ -54,12 +40,6 @@ export function mkdirSync(
   sendSync("op_mkdir", mkdirArgs(path, optionsOrRecursive, mode));
 }
 
-/** Creates a new directory with the specified path.
- *
- *       await Deno.mkdir("new_dir");
- *       await Deno.mkdir("nested/directories", { recursive: true });
- *
- * Requires `allow-write` permission. */
 export async function mkdir(
   path: string,
   optionsOrRecursive?: MkdirOptions | boolean,

cli/js/ops/fs/open.ts

@@ -2,48 +2,14 @@
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
 export interface OpenOptions {
-  /** Sets the option for read access. This option, when `true`, means that the
-   * file should be read-able if opened. */
   read?: boolean;
-  /** Sets the option for write access. This option, when `true`, means that
-   * the file should be write-able if opened. If the file already exists,
-   * any write calls on it will overwrite its contents, by default without
-   * truncating it. */
   write?: boolean;
-  /**Sets the option for the append mode. This option, when `true`, means that
-   * writes will append to a file instead of overwriting previous contents.
-   * Note that setting `{ write: true, append: true }` has the same effect as
-   * setting only `{ append: true }`. */
   append?: boolean;
-  /** Sets the option for truncating a previous file. If a file is
-   * successfully opened with this option set it will truncate the file to `0`
-   * length if it already exists. The file must be opened with write access
-   * for truncate to work. */
   truncate?: boolean;
-  /** Sets the option to allow creating a new file, if one doesn't already
-   * exist at the specified path. Requires write or append access to be
-   * used. */
   create?: boolean;
-  /** Defaults to `false`. If set to `true`, no file, directory, or symlink is
-   * allowed to exist at the target location. Requires write or append
-   * access to be used. When createNew is set to `true`, create and truncate
-   * are ignored. */
   createNew?: boolean;
 }
 
-/** A set of string literals which specify the open mode of a file.
- *
- * |Value |Description                                                                                       |
- * |------|--------------------------------------------------------------------------------------------------|
- * |`"r"` |Read-only. Default. Starts at beginning of file.                                                  |
- * |`"r+"`|Read-write. Start at beginning of file.                                                           |
- * |`"w"` |Write-only. Opens and truncates existing file or creates new one for writing only.                |
- * |`"w+"`|Read-write. Opens and truncates existing file or creates new one for writing and reading.         |
- * |`"a"` |Write-only. Opens existing file or creates new one. Each write appends content to the end of file.|
- * |`"a+"`|Read-write. Behaves like `"a"` and allows to read from file.                                      |
- * |`"x"` |Write-only. Exclusive create - creates new file only if one doesn't exist already.                |
- * |`"x+"`|Read-write. Behaves like `x` and allows reading from file.                                        |
- */
 export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+";
 
 export function openSync(

cli/js/ops/fs/read_dir.ts

@@ -15,23 +15,10 @@ function res(response: ReadDirResponse): FileInfo[] {
   );
 }
 
-/** Synchronously reads the directory given by `path` and returns an array of
- * `Deno.FileInfo`.
- *
- *       const files = Deno.readdirSync("/");
- *
- * Requires `allow-read` permission. */
 export function readdirSync(path: string): FileInfo[] {
   return res(sendSync("op_read_dir", { path }));
 }
 
-/** UNSTABLE: Maybe need to return an `AsyncIterable`.
- *
- * Reads the directory given by `path` and resolves to an array of `Deno.FileInfo`.
- *
- *       const files = await Deno.readdir("/");
- *
- * Requires `allow-read` permission. */
 export async function readdir(path: string): Promise<FileInfo[]> {
   return res(await sendAsync("op_read_dir", { path }));
 }

cli/js/ops/fs/read_link.ts

@@ -1,20 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Returns the destination of the named symbolic link.
- *
- *       const targetPath = Deno.readlinkSync("symlink/path");
- *
- * Requires `allow-read` permission. */
 export function readlinkSync(path: string): string {
   return sendSync("op_read_link", { path });
 }
 
-/** Resolves to the destination of the named symbolic link.
- *
- *       const targetPath = await Deno.readlink("symlink/path");
- *
- * Requires `allow-read` permission. */
 export async function readlink(path: string): Promise<string> {
   return await sendAsync("op_read_link", { path });
 }

cli/js/ops/fs/realpath.ts

@@ -1,18 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Returns absolute normalized path with symbolic links resolved synchronously.
- *
- *       const realPath = Deno.realpathSync("./some/path");
- */
 export function realpathSync(path: string): string {
   return sendSync("op_realpath", { path });
 }
 
-/** Returns absolute normalized path with symbolic links resolved.
- *
- *       const realPath = await Deno.realpath("./some/path");
- */
 export async function realpath(path: string): Promise<string> {
   return await sendAsync("op_realpath", { path });
 }

cli/js/ops/fs/remove.ts

@@ -2,29 +2,13 @@
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
 export interface RemoveOptions {
-  /** Defaults to `false`. If set to `true`, path will be removed even if
-   * it's a non-empty directory. */
   recursive?: boolean;
 }
 
-/** Synchronously removes the named file or directory. Throws error if
- * permission denied, path not found, or path is a non-empty directory and
- * the `recursive` option isn't set to `true`.
- *
- *       Deno.removeSync("/path/to/dir/or/file", { recursive: false });
- *
- * Requires `allow-write` permission. */
 export function removeSync(path: string, options: RemoveOptions = {}): void {
   sendSync("op_remove", { path, recursive: !!options.recursive });
 }
 
-/** Removes the named file or directory. Throws error if permission denied,
- * path not found, or path is a non-empty directory and the `recursive`
- * option isn't set to `true`.
- *
- *       await Deno.remove("/path/to/dir/or/file", { recursive: false });
- *
- * Requires `allow-write` permission. */
 export async function remove(
   path: string,
   options: RemoveOptions = {}

cli/js/ops/fs/rename.ts

@@ -1,25 +1,10 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 
-/** Synchronously renames (moves) `oldpath` to `newpath`. If `newpath` already
- * exists and is not a directory, `renameSync()` replaces it. OS-specific
- * restrictions may apply when `oldpath` and `newpath` are in different
- * directories.
- *
- *       Deno.renameSync("old/path", "new/path");
- *
- * Requires `allow-read` and `allow-write` permissions. */
 export function renameSync(oldpath: string, newpath: string): void {
   sendSync("op_rename", { oldpath, newpath });
 }
 
-/** Renames (moves) `oldpath` to `newpath`. If `newpath` already exists and is
- * not a directory, `rename()` replaces it. OS-specific restrictions may apply
- * when `oldpath` and `newpath` are in different directories.
- *
- *       await Deno.rename("old/path", "new/path");
- *
- * Requires `allow-read` and `allow-write`. */
 export async function rename(oldpath: string, newpath: string): Promise<void> {
   await sendAsync("op_rename", { oldpath, newpath });
 }

cli/js/ops/fs/seek.ts

@@ -2,13 +2,6 @@
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 import { SeekMode } from "../../io.ts";
 
-/** Synchronously seek a file ID to the given offset under mode given by `whence`.
- *
- * Returns the number of cursor position.
- *
- *       const file = Deno.openSync("/foo/bar.txt");
- *       const position = Deno.seekSync(file.rid, 0, 0);
- */
 export function seekSync(
   rid: number,
   offset: number,
@@ -17,13 +10,6 @@ export function seekSync(
   return sendSync("op_seek", { rid, offset, whence });
 }
 
-/** Seek a file ID to the given offset under mode given by `whence`.
- *
- * Resolves with the number of cursor position.
- *
- *      const file = await Deno.open("/foo/bar.txt");
- *      const position = await Deno.seek(file.rid, 0, 0);
- */
 export async function seek(
   rid: number,
   offset: number,

cli/js/ops/fs/stat.ts

@@ -2,7 +2,6 @@
 import { sendSync, sendAsync } from "../dispatch_json.ts";
 import { FileInfo, FileInfoImpl } from "../../file_info.ts";
 
-/** @internal */
 export interface StatResponse {
   isFile: boolean;
   isSymlink: boolean;
@@ -23,13 +22,6 @@ export interface StatResponse {
   blocks: number;
 }
 
-/** Resolves to a `Deno.FileInfo` for the specified `path`. If `path` is a
- * symlink, information for the symlink will be returned.
- *
- *       const fileInfo = await Deno.lstat("hello.txt");
- *       assert(fileInfo.isFile());
- *
- * Requires `allow-read` permission. */
 export async function lstat(path: string): Promise<FileInfo> {
   const res = (await sendAsync("op_stat", {
     path,
@@ -38,13 +30,6 @@ export async function lstat(path: string): Promise<FileInfo> {
   return new FileInfoImpl(res);
 }
 
-/** Synchronously returns a `Deno.FileInfo` for the specified `path`. If
- * `path` is a symlink, information for the symlink will be returned.
- *
- *       const fileInfo = Deno.lstatSync("hello.txt");
- *       assert(fileInfo.isFile());
- *
- * Requires `allow-read` permission. */
 export function lstatSync(path: string): FileInfo {
   const res = sendSync("op_stat", {
     path,
@@ -53,13 +38,6 @@ export function lstatSync(path: string): FileInfo {
   return new FileInfoImpl(res);
 }
 
-/** Resolves to a `Deno.FileInfo` for the specified `path`. Will always
- * follow symlinks.
- *
- *       const fileInfo = await Deno.stat("hello.txt");
- *       assert(fileInfo.isFile());
- *
- * Requires `allow-read` permission. */
 export async function stat(path: string): Promise<FileInfo> {
   const res = (await sendAsync("op_stat", {
     path,
@@ -68,13 +46,6 @@ export async function stat(path: string): Promise<FileInfo> {
   return new FileInfoImpl(res);
 }
 
-/** Synchronously returns a `Deno.FileInfo` for the specified `path`. Will
- * always follow symlinks.
- *
- *       const fileInfo = Deno.statSync("hello.txt");
- *       assert(fileInfo.isFile());
- *
- * Requires `allow-read` permission. */
 export function statSync(path: string): FileInfo {
   const res = sendSync("op_stat", {
     path,

cli/js/ops/fs/symlink.ts

@@ -3,15 +3,6 @@ import { sendSync, sendAsync } from "../dispatch_json.ts";
 import * as util from "../../util.ts";
 import { build } from "../../build.ts";
 
-/** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`.
- *
- * Creates `newname` as a symbolic link to `oldname`. The type argument can be
- * set to `dir` or `file`. Is only available on Windows and ignored on other
- * platforms.
- *
- *       Deno.symlinkSync("old/name", "new/name");
- *
- * Requires `allow-read` and `allow-write` permissions. */
 export function symlinkSync(
   oldname: string,
   newname: string,
@@ -23,15 +14,6 @@ export function symlinkSync(
   sendSync("op_symlink", { oldname, newname });
 }
 
-/** **UNSTABLE**: `type` argument may be changed to "dir" | "file"
- *
- * Creates `newname` as a symbolic link to `oldname`. The type argument can be
- * set to `dir` or `file`. Is only available on Windows and ignored on other
- * platforms.
- *
- *       await Deno.symlink("old/name", "new/name");
- *
- * Requires `allow-read` and `allow-write` permissions. */
 export async function symlink(
   oldname: string,
   newname: string,

cli/js/ops/fs/truncate.ts

@@ -13,21 +13,10 @@ function coerceLen(len?: number): number {
   return len;
 }
 
-/** Synchronously truncates or extends the specified file, to reach the
- * specified `len`.
- *
- *       Deno.truncateSync("hello.txt", 10);
- *
- * Requires `allow-write` permission. */
 export function truncateSync(path: string, len?: number): void {
   sendSync("op_truncate", { path, len: coerceLen(len) });
 }
 
-/** Truncates or extends the specified file, to reach the specified `len`.
- *
- *       await Deno.truncate("hello.txt", 10);
- *
- * Requires `allow-write` permission. */
 export async function truncate(path: string, len?: number): Promise<void> {
   await sendAsync("op_truncate", { path, len: coerceLen(len) });
 }

cli/js/ops/fs/umask.ts

@@ -1,12 +1,6 @@
 // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license.
 import { sendSync } from "../dispatch_json.ts";
 
-/**
- * **UNSTABLE**: maybe needs `allow-env` permissions.
- *
- * If `mask` is provided, sets the process umask. Always returns what the umask
- * was before the call.
- */
 export function umask(mask?: number): number {
   return sendSync("op_umask", { mask });
 }

cli/js/ops/fs/utime.ts

@@ -5,15 +5,6 @@ function toSecondsFromEpoch(v: number | Date): number {
   return v instanceof Date ? v.valueOf() / 1000 : v;
 }
 
-/** **UNSTABLE**: needs investigation into high precision time.
- *
- * Synchronously changes the access and modification times of a file system
- * object referenced by `path`. Given times are either in seconds (UNIX epoch
- * time) or as `Date` objects.
- *
- *       Deno.utimeSync("myfile.txt", 1556495550, new Date());
- *
- * Requires `allow-write` permission. */
 export function utimeSync(
   path: string,
   atime: number | Date,
@@ -27,15 +18,6 @@ export function utimeSync(
   });
 }
 
-/** **UNSTABLE**: needs investigation into high precision time.
- *
- * Changes the access and modification times of a file system object
- * referenced by `path`. Given times are either in seconds (UNIX epoch time)
- * or as `Date` objects.
- *
- *       await Deno.utime("myfile.txt", 1556495550, new Date());
- *
- * Requires `allow-write` permission. */
 export async function utime(
   path: string,
   atime: number | Date,

cli/js/ops/get_random_values.ts

@@ -2,12 +2,6 @@
 import { sendSync } from "./dispatch_json.ts";
 import { assert } from "../util.ts";
 
-/** Synchronously collects cryptographically secure random values. The
- * underlying CSPRNG in use is Rust's `rand::rngs::ThreadRng`.
- *
- *       const arr = new Uint8Array(32);
- *       crypto.getRandomValues(arr);
- */
 export function getRandomValues<
   T extends
     | Int8Array

cli/js/ops/io.ts

@@ -10,15 +10,6 @@ import { OPS_CACHE } from "../runtime.ts";
 let OP_READ = -1;
 let OP_WRITE = -1;
 
-/** Synchronously read from a file ID into an array buffer.
- *
- * Returns `number | EOF` for the operation.
- *
- *      const file = Deno.openSync("/foo/bar.txt");
- *      const buf = new Uint8Array(100);
- *      const nread = Deno.readSync(file.rid, buf);
- *      const text = new TextDecoder().decode(buf);
- */
 export function readSync(rid: number, p: Uint8Array): number | EOF {
   if (p.length == 0) {
     return 0;
@@ -36,15 +27,6 @@ export function readSync(rid: number, p: Uint8Array): number | EOF {
   }
 }
 
-/** Read from a resource ID into an array buffer.
- *
- * Resolves to the `number | EOF` for the operation.
- *
- *       const file = await Deno.open("/foo/bar.txt");
- *       const buf = new Uint8Array(100);
- *       const nread = await Deno.read(file.rid, buf);
- *       const text = new TextDecoder().decode(buf);
- */
 export async function read(rid: number, p: Uint8Array): Promise<number | EOF> {
   if (p.length == 0) {
     return 0;
@@ -62,15 +44,6 @@ export async function read(rid: number, p: Uint8Array): Promise<number | EOF> {
   }
 }
 
-/** Synchronously write to the resource ID the contents of the array buffer.
- *
- * Resolves to the number of bytes written.
- *
- *       const encoder = new TextEncoder();
- *       const data = encoder.encode("Hello world\n");
- *       const file = Deno.openSync("/foo/bar.txt", {create: true, write: true});
- *       Deno.writeSync(file.rid, data);
- */
 export function writeSync(rid: number, p: Uint8Array): number {
   if (OP_WRITE < 0) {
     OP_WRITE = OPS_CACHE["op_write"];
@@ -83,15 +56,6 @@ export function writeSync(rid: number, p: Uint8Array): number {
   }
 }
 
-/** Write to the resource ID the contents of the array buffer.
- *
- * Resolves to the number of bytes written.
- *
- *      const encoder = new TextEncoder();
- *      const data = encoder.encode("Hello world\n");
- *      const file = await Deno.open("/foo/bar.txt", {create: true, write: true});
- *      await Deno.write(file.rid, data);
- */
 export async function write(rid: number, p: Uint8Array): Promise<number> {
   if (OP_WRITE < 0) {
     OP_WRITE = OPS_CACHE["op_write"];

cli/js/ops/net.ts

@@ -13,14 +13,6 @@ export enum ShutdownMode {
   ReadWrite // unused
 }
 
-/** Shut down socket send and receive operations.
- *
- * Matches behavior of POSIX shutdown(3).
- *
- *       const listener = Deno.listen({ port: 80 });
- *       const conn = await listener.accept();
- *       Deno.shutdown(conn.rid, Deno.ShutdownMode.Write);
- */
 export function shutdown(rid: number, how: ShutdownMode): void {
   sendSync("op_shutdown", { rid, how });
 }

cli/js/ops/os.ts

@@ -2,34 +2,18 @@
 import { sendSync } from "./dispatch_json.ts";
 import { errors } from "../errors.ts";
 
-/** Get the loadavg.
- * Requires the `--allow-env` flag.
- *
- *       console.log(Deno.loadavg());
- */
 export function loadavg(): number[] {
   return sendSync("op_loadavg");
 }
 
-/** Get the hostname.
- * Requires the `--allow-env` flag.
- *
- *       console.log(Deno.hostname());
- */
 export function hostname(): string {
   return sendSync("op_hostname");
 }
 
-/** Get OS release.
- * Requires the `--allow-env` flag.
- *
- *       console.log(Deno.osRelease());
- */
 export function osRelease(): string {
   return sendSync("op_os_release");
 }
 
-/** Exit the Deno process with optional exit code. */
 export function exit(code = 0): never {
   sendSync("op_exit", { code });
   throw new Error("Code not reachable");
@@ -43,18 +27,6 @@ function getEnv(key: string): string | undefined {
   return sendSync("op_get_env", { key })[0];
 }
 
-/** Returns a snapshot of the environment variables at invocation. Mutating a
- * property in the object will set that variable in the environment for
- * the process. The environment object will only accept `string`s
- * as values.
- *
- *       console.log(Deno.env("SHELL"));
- *       const myEnv = Deno.env();
- *       console.log(myEnv.SHELL);
- *       myEnv.TEST_VAR = "HELLO";
- *       const newEnv = Deno.env();
- *       console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
- */
 export function env(): { [index: string]: string };
 export function env(key: string): string | undefined;
 export function env(
@@ -90,122 +62,6 @@ type DirKind =
   | "tmp"
   | "video";
 
-/**
- * Returns the user and platform specific directories.
- * Requires the `--allow-env` flag.
- * Returns null if there is no applicable directory or if any other error
- * occurs.
- *
- * Argument values: "home", "cache", "config", "executable", "data",
- * "data_local", "audio", "desktop", "document", "download", "font", "picture",
- * "public", "template", "video"
- *
- * "cache"
- * |Platform | Value                               | Example                      |
- * | ------- | ----------------------------------- | ---------------------------- |
- * | Linux   | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache           |
- * | macOS   | `$HOME`/Library/Caches              | /Users/Alice/Library/Caches  |
- * | Windows | `{FOLDERID_LocalAppData}`           | C:\Users\Alice\AppData\Local |
- *
- * "config"
- * |Platform | Value                                 | Example                          |
- * | ------- | ------------------------------------- | -------------------------------- |
- * | Linux   | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config              |
- * | macOS   | `$HOME`/Library/Preferences           | /Users/Alice/Library/Preferences |
- * | Windows | `{FOLDERID_RoamingAppData}`           | C:\Users\Alice\AppData\Roaming   |
- *
- * "executable"
- * |Platform | Value                                                           | Example                |
- * | ------- | --------------------------------------------------------------- | -----------------------|
- * | Linux   | `XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin |
- * | macOS   | -                                                               | -                      |
- * | Windows | -                                                               | -                      |
- *
- * "data"
- * |Platform | Value                                    | Example                                  |
- * | ------- | ---------------------------------------- | ---------------------------------------- |
- * | Linux   | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share                 |
- * | macOS   | `$HOME`/Library/Application Support      | /Users/Alice/Library/Application Support |
- * | Windows | `{FOLDERID_RoamingAppData}`              | C:\Users\Alice\AppData\Roaming           |
- *
- * "data_local"
- * |Platform | Value                                    | Example                                  |
- * | ------- | ---------------------------------------- | ---------------------------------------- |
- * | Linux   | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share                 |
- * | macOS   | `$HOME`/Library/Application Support      | /Users/Alice/Library/Application Support |
- * | Windows | `{FOLDERID_LocalAppData}`                | C:\Users\Alice\AppData\Local             |
- *
- * "audio"
- * |Platform | Value              | Example              |
- * | ------- | ------------------ | -------------------- |
- * | Linux   | `XDG_MUSIC_DIR`    | /home/alice/Music    |
- * | macOS   | `$HOME`/Music      | /Users/Alice/Music   |
- * | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music |
- *
- * "desktop"
- * |Platform | Value                | Example                |
- * | ------- | -------------------- | ---------------------- |
- * | Linux   | `XDG_DESKTOP_DIR`    | /home/alice/Desktop    |
- * | macOS   | `$HOME`/Desktop      | /Users/Alice/Desktop   |
- * | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop |
- *
- * "document"
- * |Platform | Value                  | Example                  |
- * | ------- | ---------------------- | ------------------------ |
- * | Linux   | `XDG_DOCUMENTS_DIR`    | /home/alice/Documents    |
- * | macOS   | `$HOME`/Documents      | /Users/Alice/Documents   |
- * | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents |
- *
- * "download"
- * |Platform | Value                  | Example                  |
- * | ------- | ---------------------- | ------------------------ |
- * | Linux   | `XDG_DOWNLOAD_DIR`     | /home/alice/Downloads    |
- * | macOS   | `$HOME`/Downloads      | /Users/Alice/Downloads   |
- * | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads |
- *
- * "font"
- * |Platform | Value                                                | Example                        |
- * | ------- | ---------------------------------------------------- | ------------------------------ |
- * | Linux   | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts |
- * | macOS   | `$HOME/Library/Fonts`                                | /Users/Alice/Library/Fonts     |
- * | Windows | –                                                    | –                              |
- *
- * "picture"
- * |Platform | Value                 | Example                 |
- * | ------- | --------------------- | ----------------------- |
- * | Linux   | `XDG_PICTURES_DIR`    | /home/alice/Pictures    |
- * | macOS   | `$HOME`/Pictures      | /Users/Alice/Pictures   |
- * | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures |
- *
- * "public"
- * |Platform | Value                 | Example             |
- * | ------- | --------------------- | ------------------- |
- * | Linux   | `XDG_PUBLICSHARE_DIR` | /home/alice/Public  |
- * | macOS   | `$HOME`/Public        | /Users/Alice/Public |
- * | Windows | `{FOLDERID_Public}`   | C:\Users\Public     |
- *
- * "template"
- * |Platform | Value                  | Example                                                    |
- * | ------- | ---------------------- | ---------------------------------------------------------- |
- * | Linux   | `XDG_TEMPLATES_DIR`    | /home/alice/Templates                                      |
- * | macOS   | –                      | –                                                          |
- * | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
- *
- * "tmp"
- *
- * |Platform | Value                  | Example                                                    |
- * | ------- | ---------------------- | ---------------------------------------------------------- |
- * | Linux   | `TMPDIR`               | /tmp                                                       |
- * | macOS   | `TMPDIR`               | /tmp                                                       |
- * | Windows | `{TMP}`                | C:\Users\Alice\AppData\Local\Temp                          |
- *
- * "video"
- * |Platform | Value               | Example               |
- * | ------- | ------------------- | --------------------- |
- * | Linux   | `XDG_VIDEOS_DIR`    | /home/alice/Videos    |
- * | macOS   | `$HOME`/Movies      | /Users/Alice/Movies   |
- * | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos |
- */
 export function dir(kind: DirKind): string | null {
   try {
     return sendSync("op_get_dir", { kind });
@@ -217,10 +73,6 @@ export function dir(kind: DirKind): string | null {
   }
 }
 
-/**
- * Returns the path to the current deno executable.
- * Requires the `--allow-env` flag.
- */
 export function execPath(): string {
   return sendSync("op_exec_path");
 }

cli/js/ops/process.ts

@@ -2,11 +2,6 @@
 import { sendSync, sendAsync } from "./dispatch_json.ts";
 import { assert } from "../util.ts";
 
-/** Send a signal to process under given PID. Unix only at this moment.
- * If pid is negative, the signal will be sent to the process group identified
- * by -pid.
- * Requires the `--allow-run` flag.
- */
 export function kill(pid: number, signo: number): void {
   sendSync("op_kill", { pid, signo });
 }

cli/js/ops/resources.ts

@@ -5,9 +5,6 @@ export interface ResourceMap {
   [rid: number]: string;
 }
 
-/** Returns a map of open _file like_ resource ids along with their string
- * representation.
- */
 export function resources(): ResourceMap {
   const res = sendSync("op_resources") as Array<[number, string]>;
   const resources: ResourceMap = {};
@@ -17,7 +14,6 @@ export function resources(): ResourceMap {
   return resources;
 }
 
-/** Close the given resource ID. */
 export function close(rid: number): void {
   sendSync("op_close", { rid });
 }

cli/js/ops/runtime.ts

@@ -43,25 +43,6 @@ export interface Metrics {
   bytesReceived: number;
 }
 
-/** Receive metrics from the privileged side of Deno.
- *
- *      > console.table(Deno.metrics())
- *      ┌─────────────────────────┬────────┐
- *      │         (index)         │ Values │
- *      ├─────────────────────────┼────────┤
- *      │      opsDispatched      │   3    │
- *      │    opsDispatchedSync    │   2    │
- *      │   opsDispatchedAsync    │   1    │
- *      │ opsDispatchedAsyncUnref │   0    │
- *      │      opsCompleted       │   3    │
- *      │    opsCompletedSync     │   2    │
- *      │    opsCompletedAsync    │   1    │
- *      │ opsCompletedAsyncUnref  │   0    │
- *      │    bytesSentControl     │   73   │
- *      │      bytesSentData      │   0    │
- *      │      bytesReceived      │  375   │
- *      └─────────────────────────┴────────┘
- */
 export function metrics(): Metrics {
   return sendSync("op_metrics");
 }

cli/js/ops/tty.ts

@@ -1,11 +1,9 @@
 import { sendSync } from "./dispatch_json.ts";
 
-/** Check if a given resource is TTY. */
 export function isatty(rid: number): boolean {
   return sendSync("op_isatty", { rid });
 }
 
-/** Set TTY to be under raw mode or not. */
 export function setRaw(rid: number, mode: boolean): void {
   sendSync("op_set_raw", {
     rid,