Improve the JS API documentation for Logger.warn() (#3894)

This is not a functional change. The old type for this was too
complicated for TypeDoc to parse, so the documentation was being
hidden.

js-api-doc/index.d.ts

@@ -29,7 +29,7 @@ export {
   ImporterResult,
   NodePackageImporter,
 } from './importer';
-export {Logger, SourceSpan, SourceLocation} from './logger';
+export {Logger, LoggerWarnOptions, SourceSpan, SourceLocation} from './logger';
 export {
   CustomFunction,
   Options,

js-api-doc/logger/index.d.ts

@@ -4,6 +4,33 @@ import {SourceSpan} from './source_span';
 export {SourceLocation} from './source_location';
 export {SourceSpan} from './source_span';
 
+/**
+ * The options passed to {@link Logger.warn}.
+ *
+ * * `deprecation`: Whether this is a deprecation warning.
+ *
+ * * `deprecationType`: The type of deprecation. Only set if `deprecation` is
+ *   true.
+ *
+ * * `span`: The location in the Sass source code that generated this warning.
+ *   This may be unset if the warning didn't come from Sass source, for
+ *   example if it's from a deprecated JavaScript option.
+ *
+ * * `stack`: The Sass stack trace at the point the warning was issued. This may
+ *   be unset if the warning didn't come from Sass source, for example if it's
+ *   from a deprecated JavaScript option.
+ */
+export type LoggerWarnOptions = (
+  | {
+      deprecation: true;
+      deprecationType: Deprecation;
+    }
+  | {deprecation: false}
+) & {
+  span?: SourceSpan;
+  stack?: string;
+};
+
 /**
  * An object that can be passed to {@link LegacySharedOptions.logger} to control
  * how Sass emits warnings and debug messages.
@@ -42,24 +69,11 @@ export interface Logger {
    *
    * If this is `undefined`, Sass will print warnings to standard error.
    *
+   * `options` may contain the following fields:
+   *
    * @param message - The warning message.
-   * @param options.deprecation - Whether this is a deprecation warning.
-   * @param options.deprecationType - The type of deprecation this warning is
-   * for, if any.
-   * @param options.span - The location in the Sass source code that generated this
-   * warning.
-   * @param options.stack - The Sass stack trace at the point the warning was issued.
    */
-  warn?(
+  warn?(message: string, options: LoggerWarnOptions): void;
-    message: string,
-    options: (
-      | {
-          deprecation: true;
-          deprecationType: Deprecation;
-        }
-      | {deprecation: false}
-    ) & {span?: SourceSpan; stack?: string}
-  ): void;
 
   /**
    * This method is called when Sass emits a debug message due to a [`@debug`

spec/js-api/index.d.ts.md

@@ -66,7 +66,7 @@ export {
   ImporterResult,
   NodePackageImporter,
 } from './importer';
-export {Logger, SourceSpan, SourceLocation} from './logger';
+export {Logger, LoggerWarnOptions, SourceSpan, SourceLocation} from './logger';
 export {
   CustomFunction,
   Options,

spec/js-api/logger/index.d.ts.md

@@ -11,6 +11,7 @@ export {SourceSpan} from './source_span';
 ## Table of Contents
 
 * [Types](#types)
+  * [`LoggerWarnOptions`](#loggerwarnoptions)
   * [`Logger`](#logger)
     * [`warn`](#warn)
     * [`debug`](#debug)
@@ -20,6 +21,24 @@ export {SourceSpan} from './source_span';
 
 ## Types
 
+### `LoggerWarnOptions`
+
+The options passed to `Logger.warn`. These are split out for documentation
+purposes.
+
+```ts
+export type LoggerWarnOptions = (
+  | {
+      deprecation: true;
+      deprecationType: Deprecation;
+    }
+  | {deprecation: false}
+) & {
+  span?: SourceSpan;
+  stack?: string;
+};
+```
+
 ### `Logger`
 
 An object that provides callbacks for handling messages from the compiler.
@@ -67,16 +86,7 @@ If this field is defined, the compiler must not surface warnings in any way
 other than inkoving `warn`.
 
 ```ts
-warn?(
+warn?(message: string, options: LoggerWarnOptions): void;
-  message: string,
-  options: (
-    | {
-        deprecation: true;
-        deprecationType: Deprecation;
-      }
-    | {deprecation: false}
-  ) & {span?: SourceSpan; stack?: string}
-): void;
 ```
 
 #### `debug`