refactor: rename ConsoleOptions to InspectOptions (denoland#4493)

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

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 {

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;