refactor: rename ConsoleOptions to InspectOptions (#4493)

3 files changed, 41 insertions, 14 deletions

diff --git a/cli/js/lib.deno.ns.d.ts b/cli/js/lib.deno.ns.d.ts
index 6c3e563d3..ed109b817 100644
--- a/cli/js/lib.deno.ns.d.ts
+++ b/cli/js/lib.deno.ns.d.ts
@@ -134,9 +134,11 @@ declare namespace Deno {
    */
   export function loadavg(): number[];
 
-  /** Get the `hostname`. Requires `allow-env` permission.
+  /** Get the `hostname` of the machine the Deno process is running on.
    *
    *       console.log(Deno.hostname());
+   *
+   *  Requires `allow-env` permission.
    */
   export function hostname(): string;
 
@@ -2021,20 +2023,45 @@ declare namespace Deno {
    * Signals numbers. This is platform dependent. */
   export const Signal: typeof MacOSSignal | typeof LinuxSignal;
 
-  /** **UNSTABLE**: rename to `InspectOptions`. */
-  interface ConsoleOptions {
+  interface InspectOptions {
     showHidden?: boolean;
     depth?: number;
     colors?: boolean;
     indentLevel?: number;
   }
 
-  /** **UNSTABLE**: `ConsoleOptions` rename to `InspectOptions`. Also the exact
-   * form of string output subject to change.
+  /** **UNSTABLE**: The exact form of the string output is under consideration
+   * and may change.
+   *
+   * Converts the input into a string that has the same format as printed by
+   * `console.log()`.
+   *
+   *      const obj = {};
+   *      obj.propA = 10;
+   *      obj.propB = "hello"
+   *      const objAsString = Deno.inspect(obj); //{ propA: 10, propB: "hello" }
+   *      console.log(obj);  //prints same value as objAsString, e.g. { propA: 10, propB: "hello" }
+   *
+   * You can also register custom inspect functions, via the `customInspect` Deno
+   * symbol on objects, to control and customize the output.
+   *
+   *      class A {
+   *        x = 10;
+   *        y = "hello";
+   *        [Deno.symbols.customInspect](): string {
+   *          return "x=" + this.x + ", y=" + this.y;
+   *        }
+   *      }
+   *
+   *      const inStringFormat = Deno.inspect(new A()); //"x=10, y=hello"
+   *      console.log(inStringFormat);  //prints "x=10, y=hello"
+   *
+   * Finally, a number of output options are also available.
    *
-   * Converts input into string that has the same format as printed by
-   * `console.log()`. */
-  export function inspect(value: unknown, options?: ConsoleOptions): string;
+   *      const out = Deno.inspect(obj, {showHidden: true, depth: 4, colors: true, indentLevel: 2});
+   *
+   */
+  export function inspect(value: unknown, options?: InspectOptions): string;
 
   export type OperatingSystem = "mac" | "win" | "linux";
 
diff --git a/cli/js/lib.deno.shared_globals.d.ts b/cli/js/lib.deno.shared_globals.d.ts
index 85b2bbf48..959dcbfe9 100644
--- a/cli/js/lib.deno.shared_globals.d.ts
+++ b/cli/js/lib.deno.shared_globals.d.ts
@@ -887,7 +887,7 @@ declare namespace __blob {
 }
 
 declare namespace __console {
-  type ConsoleOptions = Partial<{
+  type InspectOptions = Partial<{
     showHidden: boolean;
     depth: number;
     colors: boolean;
@@ -970,7 +970,7 @@ declare namespace __console {
    * `inspect()` converts input into string that has the same format
    * as printed by `console.log(...)`;
    */
-  export function inspect(value: unknown, options?: ConsoleOptions): string;
+  export function inspect(value: unknown, options?: InspectOptions): string;
 }
 
 declare namespace __event {
diff --git a/cli/js/web/console.ts b/cli/js/web/console.ts
index 69f1a0631..f95e50b40 100644
--- a/cli/js/web/console.ts
+++ b/cli/js/web/console.ts
@@ -6,7 +6,7 @@ import { cliTable } from "./console_table.ts";
 import { exposeForTest } from "../internals.ts";
 
 type ConsoleContext = Set<unknown>;
-type ConsoleOptions = Partial<{
+type InspectOptions = Partial<{
   showHidden: boolean;
   depth: number;
   colors: boolean;
@@ -383,7 +383,7 @@ function createObjectString(
 
 export function stringifyArgs(
   args: unknown[],
-  { depth = DEFAULT_MAX_DEPTH, indentLevel = 0 }: ConsoleOptions = {}
+  { depth = DEFAULT_MAX_DEPTH, indentLevel = 0 }: InspectOptions = {}
 ): string {
   const first = args[0];
   let a = 0;
@@ -522,7 +522,7 @@ export class Console {
   debug = this.log;
   info = this.log;
 
-  dir = (obj: unknown, options: ConsoleOptions = {}): void => {
+  dir = (obj: unknown, options: InspectOptions = {}): void => {
     this.printFunc(stringifyArgs([obj], options) + "\n", false);
   };
 
@@ -749,7 +749,7 @@ export const customInspect = Symbol.for("Deno.customInspect");
 
 export function inspect(
   value: unknown,
-  { depth = DEFAULT_MAX_DEPTH }: ConsoleOptions = {}
+  { depth = DEFAULT_MAX_DEPTH }: InspectOptions = {}
 ): string {
   if (typeof value === "string") {
     return value;