From 21ae10af2377b6912f79fd3e8b81ebf6b75bcd98 Mon Sep 17 00:00:00 2001
From: Natalie Weizenbaum <nweiz@google.com>
Date: Thu, 11 Jul 2024 16:12:18 -0700
Subject: [PATCH] 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            |  2 +-
 js-api-doc/logger/index.d.ts     | 46 +++++++++++++++++++++-----------
 spec/js-api/index.d.ts.md        |  2 +-
 spec/js-api/logger/index.d.ts.md | 30 ++++++++++++++-------
 4 files changed, 52 insertions(+), 28 deletions(-)

diff --git a/js-api-doc/index.d.ts b/js-api-doc/index.d.ts
index f0df6809..a81b135b 100644
--- a/js-api-doc/index.d.ts
+++ b/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,
diff --git a/js-api-doc/logger/index.d.ts b/js-api-doc/logger/index.d.ts
index 937051e7..cda54bad 100644
--- a/js-api-doc/logger/index.d.ts
+++ b/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?(
-    message: string,
-    options: (
-      | {
-          deprecation: true;
-          deprecationType: Deprecation;
-        }
-      | {deprecation: false}
-    ) & {span?: SourceSpan; stack?: string}
-  ): void;
+  warn?(message: string, options: LoggerWarnOptions): void;
 
   /**
    * This method is called when Sass emits a debug message due to a [`@debug`
diff --git a/spec/js-api/index.d.ts.md b/spec/js-api/index.d.ts.md
index 9bb63adb..f10ca6d4 100644
--- a/spec/js-api/index.d.ts.md
+++ b/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,
diff --git a/spec/js-api/logger/index.d.ts.md b/spec/js-api/logger/index.d.ts.md
index 0b47b77e..1053cf1e 100644
--- a/spec/js-api/logger/index.d.ts.md
+++ b/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?(
-  message: string,
-  options: (
-    | {
-        deprecation: true;
-        deprecationType: Deprecation;
-      }
-    | {deprecation: false}
-  ) & {span?: SourceSpan; stack?: string}
-): void;
+warn?(message: string, options: LoggerWarnOptions): void;
 ```
 
 #### `debug`