Merge pull request #259 from TobyAndToby/ts/fix-website-signatures

tobybessant · web-flow · commit c343f1d2bb50 · 2023-12-12T20:33:31.000Z
Fix v3 signatures in documentation
diff --git a/src/packages/generate-license-file/src/lib/generateLicenseFile.ts b/src/packages/generate-license-file/src/lib/generateLicenseFile.ts
@@ -14,7 +14,7 @@ export type GenerateLicenseFileOptions = IntersectionExpander<
  * Scans the project found at the given path and creates a license file at the given output location
  * @param pathToPackageJson A path to the package.json for the project
  * @param outputPath A file path for the resulting license file
- * @optional @param lineEnding "crlf" or "lf". Will use the system default if omitted
+ * @param options Additional options for the license file generation
  */
 export async function generateLicenseFile(
   pathToPackageJson: string,
@@ -26,7 +26,7 @@ export async function generateLicenseFile(
  * Scans the projects found at the given paths and creates a license file at the given output location
  * @param pathsToPackageJsons Paths to the package.jsons for the projects
  * @param outputPath A file path for the resulting license file
- * @optional @param lineEnding "crlf" or "lf". Will use the system default if omitted
+ * @param options Additional options for the license file generation
  */
 export async function generateLicenseFile(
   pathsToPackageJsons: string[],
diff --git a/src/packages/generate-license-file/src/lib/getLicenseFileText.ts b/src/packages/generate-license-file/src/lib/getLicenseFileText.ts
@@ -20,7 +20,7 @@ export type GetLicenseFileTextOptions = IntersectionExpander<
 /**
  * Scans the project found at the given path and returns a string containing the licenses for all of the dependencies
  * @param pathToPackageJson A path to the package.json for the project
- * @optional @param lineEnding "crlf" or "lf". Will use the system default if omitted
+ * @param options Additional options for the license text generation
  * @returns A promise that resolves to the license file text
  */
 export async function getLicenseFileText(
@@ -31,7 +31,7 @@ export async function getLicenseFileText(
 /**
  * Scans the projects found at the given paths and returns a string containing the licenses for all the dependencies across all the projects
  * @param pathsToPackageJsons Paths to the package.jsons for the projects
- * @optional @param lineEnding "crlf" or "lf". Will use the system default if omitted
+ * @param options Additional options for the license text generation
  * @returns A promise that resolves to the license file text
  */
 export async function getLicenseFileText(
diff --git a/src/packages/generate-license-file/src/lib/getProjectLicenses.ts b/src/packages/generate-license-file/src/lib/getProjectLicenses.ts
@@ -10,6 +10,7 @@ export type GetProjectLicensesOptions = IntersectionExpander<ReplaceOption & Exc
  * Scans the project found at the given path and returns an array of objects each
  * containing the details of an identified license and the dependencies it pertains to.
  * @param pathToPackageJson A path to the package.json for the project
+ * @param options Additional options for the license discovery
  * @returns Array of `ILicense`s each containing the license content and respective dependencies
  */
 export async function getProjectLicenses(
diff --git a/src/packages/generate-license-file/src/lib/options/lineEnding.ts b/src/packages/generate-license-file/src/lib/options/lineEnding.ts
@@ -2,7 +2,7 @@ import { LineEnding } from "../lineEndings";
 
 export type LineEndingOption = {
   /**
-   * Specify the line ending to use in the generated license file
+   * Specify the line ending to use in the generated license file: either "lf" or "crlf"
    *
    * If you don't specify a line ending then line ending of the operating
    * system will be used
diff --git a/website/docs/library/api.mdx b/website/docs/library/api.mdx
@@ -6,7 +6,6 @@ description: API reference documentation for the generate license file library A
 import TypeScriptToggle from "@site/src/components/TypeScriptToggle";
 import LibraryMethod from "@site/src/components/docs/library/api/LibraryMethod";
 import LibraryModel from "@site/src/components/docs/library/api/LibraryModel";
-import MethodSignature from "@site/src/components/docs/library/api/MethodSignature";
 import MethodTags from "@site/src/components/docs/library/api/MethodTags";
 
 <TypeScriptToggle />
@@ -32,9 +31,9 @@ import MethodTags from "@site/src/components/docs/library/api/MethodTags";
             description: "A file path for the resulting license file",
           },
           {
-            name: "lineEnding",
-            type: `"crlf" | "lf"`,
-            description: `Will use the system default if omitted`,
+            name: "options",
+            type: "GenerateLicenseFileOptions",
+            description: "Additional options for the license file generation",
             isOptional: true,
           },
         ],
@@ -58,9 +57,9 @@ import MethodTags from "@site/src/components/docs/library/api/MethodTags";
             description: "A file path for the resulting license file",
           },
           {
-            name: "lineEnding",
-            type: `"crlf" | "lf"`,
-            description: `Will use the system default if omitted`,
+            name: "options",
+            type: "GenerateLicenseFileOptions",
+            description: "Additional options for the license file generation",
             isOptional: true,
           },
         ],
@@ -91,9 +90,9 @@ import MethodTags from "@site/src/components/docs/library/api/MethodTags";
             description: "A path to the package.json for the project",
           },
           {
-            name: "lineEnding",
-            type: `"crlf" | "lf"`,
-            description: `Will use the system default if omitted`,
+            name: "options",
+            type: "GetLicenseFileTextOptions",
+            description: "Additional options for the license text generation",
             isOptional: true,
           },
         ],
@@ -112,9 +111,9 @@ import MethodTags from "@site/src/components/docs/library/api/MethodTags";
             description: "Paths to the package.jsons for the projects",
           },
           {
-            name: "lineEnding",
-            type: `"crlf" | "lf"`,
-            description: `Will use the system default if omitted`,
+            name: "options",
+            type: "GetLicenseFileTextOptions",
+            description: "Additional options for the license text generation",
             isOptional: true,
           },
         ],
@@ -144,6 +143,12 @@ import MethodTags from "@site/src/components/docs/library/api/MethodTags";
             type: "string",
             description: "A path to the package.json for the project",
           },
+          {
+            name: "options",
+            type: "GetProjectLicensesOptions",
+            description: "Additional options for the license discovery",
+            isOptional: true,
+          },
         ],
         returnType: {
           type: "Promise<ILicense[]>",
@@ -174,9 +179,113 @@ import MethodTags from "@site/src/components/docs/library/api/MethodTags";
     <>
       Contains the content of a given license and the list of dependencies it pertains to. It is
       returned from{" "}
-      <a href="#getProjectLicenses">
+      <a href="#getprojectlicenses-">
+        <code>getProjectLicenses</code>
+      </a>
+      {""}.
+    </>
+  }
+/>
+
+### GenerateLicenseFileOptions
+
+<LibraryModel
+  properties={[
+    {
+      name: "lineEnding",
+      type: '"lf" | "crlf"',
+      description:
+        'Specify the line ending to use in the generated license file: either "lf" or "crlf". Leave undefined to use the system default',
+    },
+    {
+      name: "replace",
+      type: "Record<string, string>",
+      description:
+        "A map of packages-to-file-paths containing content that should be used instead of the package's license content",
+    },
+    {
+      name: "exclude",
+      type: "string[]",
+      description: "Packages to exclude from the generated license file",
+    },
+    {
+      name: "append",
+      type: "string[]",
+      description: "File paths to read in and append to the bottom of the generated license file",
+    },
+  ]}
+  description={
+    <>
+      Additional options for the license file generation. Can be optionally passed into{" "}
+      <a href="#generatelicensefile-">
+        <code>generateLicenseFile</code>
+      </a>
+      {""}.
+    </>
+  }
+/>
+
+### GetLicenseFileTextOptions
+
+<LibraryModel
+  properties={[
+    {
+      name: "lineEnding",
+      type: '"lf" | "crlf"',
+      description:
+        'Specify the line ending to use in the generated license file: either   "lf" or "crlf". Leave undefined to use the system default',
+    },
+    {
+      name: "replace",
+      type: "Record<string, string>",
+      description:
+        "A map of packages-to-file-paths containing content that should be used instead of the package's license content",
+    },
+    {
+      name: "exclude",
+      type: "string[]",
+      description: "Packages to exclude from the generated license file",
+    },
+    {
+      name: "append",
+      type: "string[]",
+      description: "File paths to read in and append to the bottom of the generated license file",
+    },
+  ]}
+  description={
+    <>
+      Additional options for the license text generation. Can be optionally passed into{" "}
+      <a href="#getlicensefiletext-">
+        <code>getLicenseFileText</code>
+      </a>
+      {""}.
+    </>
+  }
+/>
+
+### GetProjectLicensesOptions
+
+<LibraryModel
+  properties={[
+    {
+      name: "replace",
+      type: "Record<string, string>",
+      description:
+        "A map of packages-to-file-paths containing content that should be used instead of the package's license content",
+    },
+    {
+      name: "exclude",
+      type: "string[]",
+      description: "Packages to exclude from the generated license file",
+    },
+  ]}
+  description={
+    <>
+      Additional options for the license discovery. Can be optionally passed into{" "}
+      <a href="#getprojectlicenses-">
         <code>getProjectLicenses</code>
       </a>
+      {""}.
     </>
   }
 />
diff --git a/website/src/components/docs/library/api/MethodSignature.tsx b/website/src/components/docs/library/api/MethodSignature.tsx
@@ -52,7 +52,9 @@ const MethodSignature = ({ methodName, signature }: Props) => {
             <p>
               <code>
                 {parameter.name}
-                {useTypeScript && ": " + parameter.type}
+                {useTypeScript && parameter.isOptional && "?"}
+                {useTypeScript && ": "}
+                {useTypeScript && parameter.type}
               </code>
               {parameter.description && ` - ${parameter.description}`}
             </p>
diff --git a/website/versioned_docs/version-3.0.0/library/api.mdx b/website/versioned_docs/version-3.0.0/library/api.mdx

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@ import { LineEnding } from "../lineEndings";`
`2`	`2`
`3`	`3`	`export type LineEndingOption = {`
`4`	`4`	`/**`
`5`		`- * Specify the line ending to use in the generated license file`
	`5`	`+ * Specify the line ending to use in the generated license file: either "lf" or "crlf"`
`6`	`6`	`*`
`7`	`7`	`* If you don't specify a line ending then line ending of the operating`
`8`	`8`	`* system will be used`