From 64005515913e6e3525d729aa08e4a98f9bd69fb0 Mon Sep 17 00:00:00 2001
From: Colin Casey <casey.colin@gmail.com>
Date: Sun, 17 Mar 2024 19:51:51 -0300
Subject: [PATCH] Document `permuteDomain`

---
 api/.gitignore                         |  1 +
 api/docs/tough-cookie.permutedomain.md | 33 ++++++++++++++++++
 api/tough-cookie.api.md                |  2 +-
 lib/permuteDomain.ts                   | 46 ++++++++------------------
 4 files changed, 48 insertions(+), 34 deletions(-)
 create mode 100644 api/docs/tough-cookie.permutedomain.md

diff --git a/api/.gitignore b/api/.gitignore
index bed7e484..9b0e323f 100644
--- a/api/.gitignore
+++ b/api/.gitignore
@@ -3,3 +3,4 @@ docs/*.md
 
 # subsequent PRs will un-ignore areas that are under review until
 # all docs are complete and we can drop this ignore file entirely
+!docs/tough-cookie.permutedomain.md
diff --git a/api/docs/tough-cookie.permutedomain.md b/api/docs/tough-cookie.permutedomain.md
new file mode 100644
index 00000000..f9fc5113
--- /dev/null
+++ b/api/docs/tough-cookie.permutedomain.md
@@ -0,0 +1,33 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [tough-cookie](./tough-cookie.md) &gt; [permuteDomain](./tough-cookie.permutedomain.md)
+
+## permuteDomain() function
+
+Generates the permutation of all possible values that [domainMatch()](./tough-cookie.domainmatch.md) the given `domain` parameter. The array is in shortest-to-longest order. Useful when building custom [Store](./tough-cookie.store.md) implementations.
+
+**Signature:**
+
+```typescript
+export declare function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[] | null;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  domain | string | the domain to generate permutations for |
+|  allowSpecialUseDomain | boolean | _(Optional)_ flag to control if [Special Use Domains](https://www.rfc-editor.org/rfc/rfc6761.html) such as <code>localhost</code> should be allowed |
+
+**Returns:**
+
+string\[\] \| null
+
+## Example
+
+
+```
+permuteDomain('foo.bar.example.com')
+// ['example.com', 'bar.example.com', 'foo.bar.example.com']
+```
+
diff --git a/api/tough-cookie.api.md b/api/tough-cookie.api.md
index eca22a33..1c515748 100644
--- a/api/tough-cookie.api.md
+++ b/api/tough-cookie.api.md
@@ -272,7 +272,7 @@ export function parseDate(str: string | undefined | null): Date | undefined;
 // @public (undocumented)
 export function pathMatch(reqPath: string, cookiePath: string): boolean;
 
-// @public (undocumented)
+// @public
 export function permuteDomain(domain: string, allowSpecialUseDomain?: boolean): string[] | null;
 
 // @public
diff --git a/lib/permuteDomain.ts b/lib/permuteDomain.ts
index 195d7267..1ef7b822 100644
--- a/lib/permuteDomain.ts
+++ b/lib/permuteDomain.ts
@@ -1,39 +1,19 @@
-/*!
- * Copyright (c) 2015, Salesforce.com, Inc.
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are met:
- *
- * 1. Redistributions of source code must retain the above copyright notice,
- * this list of conditions and the following disclaimer.
- *
- * 2. Redistributions in binary form must reproduce the above copyright notice,
- * this list of conditions and the following disclaimer in the documentation
- * and/or other materials provided with the distribution.
+import { getPublicSuffix } from './getPublicSuffix'
+
+/**
+ * Generates the permutation of all possible values that {@link domainMatch} the given `domain` parameter. The
+ * array is in shortest-to-longest order. Useful when building custom {@link Store} implementations.
  *
- * 3. Neither the name of Salesforce.com nor the names of its contributors may
- * be used to endorse or promote products derived from this software without
- * specific prior written permission.
+ * @example
+ * ```
+ * permuteDomain('foo.bar.example.com')
+ * // ['example.com', 'bar.example.com', 'foo.bar.example.com']
+ * ```
  *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
- * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
+ * @public
+ * @param domain - the domain to generate permutations for
+ * @param allowSpecialUseDomain - flag to control if {@link https://www.rfc-editor.org/rfc/rfc6761.html | Special Use Domains} such as `localhost` should be allowed
  */
-'use strict'
-import { getPublicSuffix } from './getPublicSuffix'
-
-// Gives the permutation of all possible domainMatch()es of a given domain. The
-// array is in shortest-to-longest order.  Handy for indexing.
-
 export function permuteDomain(
   domain: string,
   allowSpecialUseDomain?: boolean,