doc: complete unstable documentation and make consistent (#6074)

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<void>;
 
-  /** **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<void>;
 
-  /** **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<PermissionStatus>;
   }
 
-  /** **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());