docs: explain more discovery() behaviours

Author: panva

docs/functions/discovery.md

@@ -12,12 +12,19 @@ Performs Authorization Server Metadata discovery and returns a
 [Configuration](../classes/Configuration.md) with the discovered
 [Authorization Server](../interfaces/ServerMetadata.md) metadata.
 
-This is the RECOMMENDED method of client configuration.
+Passing the Authorization Server's Issuer Identifier to this method is the
+RECOMMENDED method of client configuration.
 
 This has the same effect as calling the [Configuration](../classes/Configuration.md) constructor
 except that the server metadata is discovered from its own Authorization
 Server Metadata discovery document.
 
+Note: This method also accepts a URL pointing directly to the Authorization
+Server's discovery document, doing so is merely a shorthand for using
+[fetch](https://developer.mozilla.org/docs/Web/API/Window/fetch) and passing the discovered JSON metadata (as
+[ServerMetadata](../interfaces/ServerMetadata.md)) into the [Configuration](../classes/Configuration.md) constructor. Doing so is
+NOT RECOMMENDED as it disables the [ServerMetadata.issuer](../interfaces/ServerMetadata.md#issuer) validation.
+
 ## Parameters
 
 | Parameter | Type | Description |

src/index.ts

@@ -1050,12 +1050,19 @@ function handleB2Clogin(server: URL, options?: DiscoveryRequestOptions) {
  * {@link Configuration} with the discovered
  * {@link ServerMetadata Authorization Server} metadata.
  *
- * This is the RECOMMENDED method of client configuration.
+ * Passing the Authorization Server's Issuer Identifier to this method is the
+ * RECOMMENDED method of client configuration.
  *
  * This has the same effect as calling the {@link Configuration} constructor
  * except that the server metadata is discovered from its own Authorization
  * Server Metadata discovery document.
  *
+ * Note: This method also accepts a URL pointing directly to the Authorization
+ * Server's discovery document, doing so is merely a shorthand for using
+ * {@link !fetch} and passing the discovered JSON metadata (as
+ * {@link ServerMetadata}) into the {@link Configuration} constructor. Doing so is
+ * NOT RECOMMENDED as it disables the {@link ServerMetadata.issuer} validation.
+ *
  * @param server URL representation of the Authorization Server's Issuer
  *   Identifier
  * @param clientId Client Identifier at the Authorization Server