Merge branch 'next' into chore/image-deprecation-docs

docs/.vitepress/components/api-docs/method.ts

@@ -8,6 +8,7 @@ export interface Method {
   readonly since: string;
   readonly sourcePath: string; // URL-Suffix
   readonly seeAlsos: string[];
+  readonly throws?: string; // HTML
 }
 
 export interface MethodParameter {

docs/.vitepress/components/api-docs/method.vue

@@ -36,6 +36,10 @@ function seeAlsoToUrl(see: string): string {
 
     <p><strong>Returns:</strong> {{ props.method.returns }}</p>
 
+    <p v-if="props.method.throws">
+      <strong>Throws:</strong> <span v-html="props.method.throws" />
+    </p>
+
     <div v-html="props.method.examples" />
 
     <div v-if="props.method.seeAlsos.length > 0">

docs/api/ApiIndex.vue

@@ -60,7 +60,7 @@ function apiSearchFocusHandler(event: KeyboardEvent): void {
     if (!item) return;
     const header = item.headers[0];
     if (!header) return;
-    window.location.href = item.link + '.html#' + slugify(header.anchor);
+    window.location.href = item.link + '#' + slugify(header.anchor);
   } else if (
     /^[a-z]$/.test(event.key) &&
     !event.altKey &&

package.json

@@ -124,7 +124,6 @@
     "standard-version": "~9.5.0",
     "tsx": "~3.12.6",
     "typedoc": "~0.24.1",
-    "typedoc-plugin-missing-exports": "~1.0.0",
     "typescript": "~4.9.5",
     "validator": "~13.9.0",
     "vite": "~4.2.1",

scripts/apidoc/signature.ts

@@ -25,6 +25,7 @@ import {
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
+  extractThrows,
   joinTagParts,
 } from './typedoc';
 import { pathOutputDir } from './utils';
@@ -160,12 +161,16 @@ export function analyzeSignature(
   const deprecated = deprecatedMessage
     ? mdToHtml(deprecatedMessage)
     : undefined;
+  const throwsMessage = extractThrows(signature);
+  const throws = throwsMessage ? mdToHtml(throwsMessage, true) : undefined;
+
   return {
     name: methodName,
     description: mdToHtml(toBlock(signature.comment)),
     parameters: parameters,
     since: extractSince(signature),
     sourcePath: extractSourcePath(signature),
+    throws,
     returns: typeToText(signature.type),
     examples: mdToHtml(`${code}ts\n${examples}${code}`),
     deprecated,

scripts/apidoc/typedoc.ts

@@ -286,6 +286,18 @@ export function extractDeprecated(
   return deprecated.length === 0 ? undefined : deprecated;
 }
 
+/**
+ * Extracts the "throws" tag from the provided signature.
+ *
+ * @param reflection The reflection to check.
+ *
+ * @returns The message explaining the conditions when this method throws. Or `undefined` if it does not throw.
+ */
+export function extractThrows(reflection?: CommentHolder): string | undefined {
+  const throws = extractTagContent('@throws', reflection).join().trim();
+  return throws.length === 0 ? undefined : throws;
+}
+
 /**
  * Extracts the "since" tag from the provided signature.
  *

scripts/generateLocales.ts

@@ -126,7 +126,7 @@ function generateLocaleFile(locale: string): void {
     }
   }
 
-  // TODO christopher 2023-03-07: Remove 'en' fallback in a separate PR
+  // TODO @Shinigami92 2023-03-07: Remove 'en' fallback in a separate PR
   if (locales[locales.length - 1] !== 'en' && locale !== 'base') {
     locales.push('en');
   }

src/modules/helpers/index.ts

@@ -554,7 +554,7 @@ export class HelpersModule {
   /**
    * Takes an array and randomizes it in place then returns it.
    *
-   * @template T The type of the entries to shuffle.
+   * @template T The type of the elements to shuffle.
    * @param list The array to shuffle.
    * @param options The options to use when shuffling.
    * @param options.inplace Whether to shuffle the array in place or return a new array. Defaults to `false`.
@@ -578,7 +578,7 @@ export class HelpersModule {
   /**
    * Returns a randomized version of the array.
    *
-   * @template T The type of the entries to shuffle.
+   * @template T The type of the elements to shuffle.
    * @param list The array to shuffle.
    * @param options The options to use when shuffling.
    * @param options.inplace Whether to shuffle the array in place or return a new array. Defaults to `false`.
@@ -603,7 +603,7 @@ export class HelpersModule {
   /**
    * Returns a randomized version of the array.
    *
-   * @template T The type of the entries to shuffle.
+   * @template T The type of the elements to shuffle.
    * @param list The array to shuffle.
    * @param options The options to use when shuffling.
    * @param options.inplace Whether to shuffle the array in place or return a new array. Defaults to `false`.
@@ -646,7 +646,7 @@ export class HelpersModule {
    * and outputs a unique array of strings based on that source.
    * This method does not store the unique state between invocations.
    *
-   * @template T The type of the entries.
+   * @template T The type of the elements.
    * @param source The strings to choose from or a function that generates a string.
    * @param length The number of elements to generate.
    *
@@ -785,7 +785,7 @@ export class HelpersModule {
   /**
    * Returns random element from the given array.
    *
-   * @template T The type of the entries to pick from.
+   * @template T The type of the elements to pick from.
    * @param array Array to pick the value from.
    *
    * @example
@@ -812,7 +812,7 @@ export class HelpersModule {
    *
    * For example, if there are two values A and B, with weights 1 and 2 respectively, then the probability of picking A is 1/3 and the probability of picking B is 2/3.
    *
-   * @template T The type of the entries to pick from.
+   * @template T The type of the elements to pick from.
    * @param array Array to pick the value from.
    * @param array[].weight The weight of the value.
    * @param array[].value The value to pick.
@@ -867,7 +867,7 @@ export class HelpersModule {
   /**
    * Returns a subset with random elements of the given array in random order.
    *
-   * @template T The type of the entries to pick from.
+   * @template T The type of the elements to pick from.
    * @param array Array to pick the value from.
    * @param count Number or range of elements to pick.
    *    When not provided, random number of elements will be picked.
@@ -1251,7 +1251,7 @@ export class HelpersModule {
    */
   unique<
     Method extends (
-      // TODO christopher 2023-02-14: This `any` type can be fixed by anyone if they want to.
+      // TODO @Shinigami92 2023-02-14: This `any` type can be fixed by anyone if they want to.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       ...parameters: any[]
     ) => RecordKey

src/modules/helpers/unique.ts

@@ -83,7 +83,7 @@ Try adjusting maxTime or maxRetries parameters for faker.helpers.unique().`
  */
 export function exec<
   Method extends (
-    // TODO christopher 2023-02-14: This `any` type can be fixed by anyone if they want to.
+    // TODO @Shinigami92 2023-02-14: This `any` type can be fixed by anyone if they want to.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ...parameters: any[]
   ) => RecordKey

src/modules/image/providers/lorempicsum.ts

@@ -101,7 +101,7 @@ export class LoremPicsum {
       since: '8.0',
       until: '9.0',
     });
-    // TODO ST-DDT 2022-03-11: This method does the same as image url, maybe generate a seed, if it is missig?
+    // TODO @ST-DDT 2022-03-11: This method does the same as image url, maybe generate a seed, if it is missing?
     return this.imageUrl(width, height, grayscale, blur, seed);
   }
 

src/utils/types.ts

@@ -14,7 +14,7 @@ export type LiteralUnion<T extends U, U = string> =
  * These would fail when invoked since they are invoked without the `new` keyword.
  */
 export type Callable = (
-  // TODO christopher 2023-02-14: This `any` type can be fixed by anyone if they want to.
+  // TODO @Shinigami92 2023-02-14: This `any` type can be fixed by anyone if they want to.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ...args: any[]
 ) => unknown;

test/all_functional.spec.ts

@@ -22,7 +22,7 @@ type SkipConfig<Module> = Partial<
 >;
 
 const BROKEN_LOCALE_METHODS = {
-  // TODO ST-DDT 2022-03-28: these are TODOs (usually broken locale files)
+  // TODO @ST-DDT 2022-03-28: these are TODOs (usually broken locale files)
   company: {
     suffixes: ['az'],
     companySuffix: ['az'],
@@ -118,7 +118,7 @@ describe('functional tests', () => {
         describe(module, () => {
           modules[module].forEach((meth) => {
             const testAssertion = () => {
-              // TODO ST-DDT 2022-03-28: Use random seed once there are no more failures
+              // TODO @ST-DDT 2022-03-28: Use random seed once there are no more failures
               faker.seed(1);
               const result = faker[module][meth]();
 
@@ -133,7 +133,7 @@ describe('functional tests', () => {
             if (isWorkingLocaleForMethod(module, meth, locale)) {
               it(`${meth}()`, testAssertion);
             } else {
-              // TODO ST-DDT 2022-03-28: Remove once there are no more failures
+              // TODO @ST-DDT 2022-03-28: Remove once there are no more failures
               // We expect a failure here to ensure we remove the exclusions when fixed
               it.fails(`${meth}()`, testAssertion);
             }
@@ -156,7 +156,7 @@ describe('faker.helpers.fake functional tests', () => {
         describe(module, () => {
           modules[module].forEach((meth) => {
             const testAssertion = () => {
-              // TODO ST-DDT 2022-03-28: Use random seed once there are no more failures
+              // TODO @ST-DDT 2022-03-28: Use random seed once there are no more failures
               faker.seed(1);
               const result = faker.helpers.fake(`{{${module}.${meth}}}`);
 
@@ -169,7 +169,7 @@ describe('faker.helpers.fake functional tests', () => {
             if (isWorkingLocaleForMethod(module, meth, locale)) {
               it(`${meth}()`, testAssertion);
             } else {
-              // TODO ST-DDT 2022-03-28: Remove once there are no more failures
+              // TODO @ST-DDT 2022-03-28: Remove once there are no more failures
               // We expect a failure here to ensure we remove the exclusions when fixed
               it.fails(`${meth}()`, testAssertion);
             }