diff --git a/.changeset/typedoc-multi-example-double-comma.md b/.changeset/typedoc-multi-example-double-comma.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/typedoc-multi-example-double-comma.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.typedoc/__tests__/catch-all-replacements.test.ts b/.typedoc/__tests__/catch-all-replacements.test.ts new file mode 100644 index 00000000000..c987188d124 --- /dev/null +++ b/.typedoc/__tests__/catch-all-replacements.test.ts @@ -0,0 +1,27 @@ +import { describe, expect, it } from 'vitest'; + +// @ts-expect-error — .mjs plugin has no type declarations +import { applyCatchAllMdReplacements } from '../custom-plugin.mjs'; + +/** + * Unit coverage for the `getCatchAllReplacements()` rules exercised through the + * exported `applyCatchAllMdReplacements()` entry point. + */ +describe('applyCatchAllMdReplacements', () => { + it('renders a single `@example` as "Example: `value`."', () => { + expect(applyCatchAllMdReplacements('**Example** `foo`')).toBe('Example: `foo`.'); + }); + + it('joins multiple `@example` blocks with ", "', () => { + expect(applyCatchAllMdReplacements('**Examples** `a` `b` `c`')).toBe('Examples: `a`, `b`, `c`.'); + }); + + it('does not corrupt examples that contain internal spaces', () => { + // Regression: splitting the captured group on ' ' rejoined each example's + // internal spaces with ", ", producing a spurious `,,` inside array literals. + const input = '**Examples** `["/orgs/:slug", "/orgs/:slug/(.*)"]` `["/orgs/:id", "/orgs/:id/(.*)"]`'; + expect(applyCatchAllMdReplacements(input)).toBe( + 'Examples: `["/orgs/:slug", "/orgs/:slug/(.*)"]`, `["/orgs/:id", "/orgs/:id/(.*)"]`.', + ); + }); +}); diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index c0e49d5ceb4..3b56bb739de 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -395,7 +395,9 @@ function getCatchAllReplacements() { */ pattern: /\*\*Examples\*\* ((?:`[^`]+`)(?: `[^`]+`)*)/g, replace: (/** @type {string} */ _match, /** @type {string} */ capturedGroup) => { - return `Examples: ${capturedGroup.split(' ').join(', ')}.`; + // Match backtick-delimited examples individually; splitting on ' ' breaks examples with internal spaces. + const examples = capturedGroup.match(/`[^`]+`/g) ?? []; + return `Examples: ${examples.join(', ')}.`; }, }, ];