From 1ebd33092779edc630e8f809f72bcef2656b8185 Mon Sep 17 00:00:00 2001 From: Chris Knight Date: Wed, 3 Jun 2020 18:46:09 +0100 Subject: [PATCH] doc: complete unstable documentation and make consistent (#6074) --- cli/js/lib.deno.unstable.d.ts | 53 ++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 22 deletions(-) diff --git a/cli/js/lib.deno.unstable.d.ts b/cli/js/lib.deno.unstable.d.ts index 86bdd7b126..aebd7f9641 100644 --- a/cli/js/lib.deno.unstable.d.ts +++ b/cli/js/lib.deno.unstable.d.ts @@ -21,7 +21,9 @@ declare namespace Deno { */ export function umask(mask?: number): number; - /** Synchronously creates `newpath` as a hard link to `oldpath`. + /** **UNSTABLE**: This API needs a security review. + * + * Synchronously creates `newpath` as a hard link to `oldpath`. * * ```ts * Deno.linkSync("old/name", "new/name"); @@ -30,9 +32,9 @@ declare namespace Deno { * Requires `allow-read` and `allow-write` permissions. */ export function linkSync(oldpath: string, newpath: string): void; - /** Creates `newpath` as a hard link to `oldpath`. + /** **UNSTABLE**: This API needs a security review. * - * **UNSTABLE**: needs security review. + * Creates `newpath` as a hard link to `oldpath`. * * ```ts * await Deno.link("old/name", "new/name"); @@ -45,7 +47,7 @@ declare namespace Deno { type: "file" | "dir"; }; - /** **UNSTABLE**: needs security review. + /** **UNSTABLE**: This API needs a security review. * * Creates `newpath` as a symbolic link to `oldpath`. * @@ -63,7 +65,7 @@ declare namespace Deno { options?: SymlinkOptions ): void; - /** **UNSTABLE**: needs security review. + /** **UNSTABLE**: This API needs a security review. * * Creates `newpath` as a symbolic link to `oldpath`. * @@ -250,7 +252,10 @@ declare namespace Deno { */ export function dir(kind: DirKind): string | null; - /** Returns an array containing the 1, 5, and 15 minute load averages. The + /** **Unstable** There are questions around which permission this needs. And + * maybe should be renamed (loadAverage?) + * + * Returns an array containing the 1, 5, and 15 minute load averages. The * load average is a measure of CPU and IO utilization of the last one, five, * and 15 minute periods expressed as a fractional number. Zero means there * is no load. On Windows, the three values are always the same and represent @@ -261,13 +266,14 @@ declare namespace Deno { * ``` * * Requires `allow-env` permission. - * - * **Unstable** There are questions around which permission this needs. And - * maybe should be renamed (loadAverage?) */ export function loadavg(): number[]; - /** Returns the release version of the Operating System. + /** **Unstable** new API. yet to be vetted. Under consideration to possibly move to + * Deno.build or Deno.versions and if it should depend sys-info, which may not + * be desireable. + * + * Returns the release version of the Operating System. * * ```ts * console.log(Deno.osRelease()); @@ -275,8 +281,6 @@ declare namespace Deno { * * Requires `allow-env` permission. * - * **Unstable** new API maybe move to Deno.build or Deno.versions? Depends on - * sys-info, which we don't necessarally want to depend on. */ export function osRelease(): string; @@ -699,7 +703,7 @@ declare namespace Deno { columnNumber: number; } - /** UNSTABLE: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * Given a current location in a module, lookup the source location and return * it. @@ -793,7 +797,7 @@ declare namespace Deno { SIGUSR2 = 31, } - /** **UNSTABLE**: make platform independent. + /** **UNSTABLE**: Further changes required to make platform independent. * * Signals numbers. This is platform dependent. */ export const Signal: typeof MacOSSignal | typeof LinuxSignal; @@ -947,7 +951,7 @@ declare namespace Deno { mtime: number | Date ): Promise; - /** **UNSTABLE**: Maybe remove `ShutdownMode` entirely. + /** **UNSTABLE**: Under consideration to remove `ShutdownMode` entirely. * * Corresponds to `SHUT_RD`, `SHUT_WR`, `SHUT_RDWR` on POSIX-like systems. * @@ -973,7 +977,7 @@ declare namespace Deno { */ export function shutdown(rid: number, how: ShutdownMode): Promise; - /** **UNSTABLE**:: new API, yet to be vetted. + /** **UNSTABLE**: new API, yet to be vetted. * * A generic transport listener for message-oriented protocols. */ export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { @@ -1013,7 +1017,7 @@ declare namespace Deno { options: UnixListenOptions & { transport: "unix" } ): Listener; - /** **UNSTABLE**: new API + /** **UNSTABLE**: new API, yet to be vetted * * Listen announces on the local transport address. * @@ -1034,7 +1038,7 @@ declare namespace Deno { options: ListenOptions & { transport: "udp" } ): DatagramConn; - /** **UNSTABLE**: new API + /** **UNSTABLE**: new API, yet to be vetted * * Listen announces on the local transport address. * @@ -1055,7 +1059,9 @@ declare namespace Deno { path: string; } - /** + /** **UNSTABLE**: The unix socket transport is unstable as a new API yet to + * be vetted. The TCP transport is considered stable. + * * Connects to the hostname (default is "127.0.0.1") and port on the named * transport (default is "tcp"), and resolves to the connection (`Conn`). * @@ -1216,8 +1222,8 @@ declare namespace Deno { request(desc: PermissionDescriptor): Promise; } - /** **UNSTABLE**: maybe move to `navigator.permissions` to match web API. It - * could look like `navigator.permissions.query({ name: Deno.symbols.read })`. + /** **UNSTABLE**: Under consideration to move to `navigator.permissions` to + * match web API. It could look like `navigator.permissions.query({ name: Deno.symbols.read })`. */ export const permissions: Permissions; @@ -1227,7 +1233,10 @@ declare namespace Deno { constructor(state: PermissionState); } - /** Get the `hostname` of the machine the Deno process is running on. + /** **UNSTABLE**: New API, yet to be vetted. Additional consideration is still + * necessary around the permissions required. + * + * Get the `hostname` of the machine the Deno process is running on. * * ```ts * console.log(Deno.hostname());