fix(core): correctly wrap array of unions in parenthesis

.changeset/shy-ways-visit.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Correctly wrap array of unions in parenthesis (#719).

package.json

@@ -29,7 +29,7 @@
     "@types/eslint__js": "^8.42.3",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^29.5.14",
-    "@types/node": "^22.10.0",
+    "@types/node": "^22.10.1",
     "consola": "^3.2.3",
     "copyfiles": "^2.4.1",
     "eslint": "^9.15.0",
@@ -52,7 +52,7 @@
     "ts-morph": "^24.0.0",
     "tsc-alias": "^1.8.10",
     "tsx": "^4.19.2",
-    "typedoc": "^0.27.0",
+    "typedoc": "^0.27.1",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.16.0"
   }

packages/typedoc-plugin-markdown/.scripts/prebuild-resources.ts

@@ -136,6 +136,7 @@ async function writeResourcesFile() {
     'IntrinsicType',
     'LiteralType',
     'NamedTupleMember',
+    'OptionalType',
     'ParameterReflection',
     'ProjectReflection',
     'QueryType',

packages/typedoc-plugin-markdown/package.json

@@ -17,8 +17,9 @@
     "build-and-run": "npm run build && npm run fixtures",
     "fixtures": "node test/__scripts__/build-fixtures.mjs -c test/fixtures/config.mjs",
     "validate": "node test/__scripts__/lint/lint.md.mjs && tsx test/__scripts__/lint/lint.mdx.mjs",
-    "test": "npm run fixtures -- -isCI && npm run validate && jest",
-    "test:update": "npm run build-and-run && npm run test -- -u",
+    "pretest": "npm run fixtures -- -isCI",
+    "test": "npm run validate && jest",
+    "test:update": "npm run build-and-run && npm run validate && jest -u",
     "playground": "npm run build && typedoc --options ./playground/typedoc.json",
     "schema": "tsx ./.scripts/schema/generate-schema.ts",
     "docs": "npm run build && typedoc --options ./typedoc.public.json"

packages/typedoc-plugin-markdown/src/theme/context/partials/index.ts

@@ -48,6 +48,7 @@ export * from './type.intersection.js';
 export * from './type.intrinsic.js';
 export * from './type.literal.js';
 export * from './type.named-tuple.js';
+export * from './type.optional.js';
 export * from './type.query.js';
 export * from './type.reference.js';
 export * from './type.reflection.declaration.js';

packages/typedoc-plugin-markdown/src/theme/context/partials/type.optional.ts

@@ -0,0 +1,10 @@
+import { MarkdownThemeContext } from '@plugin/theme/index.js';
+import { OptionalType } from 'typedoc';
+
+export function optionalType(
+  this: MarkdownThemeContext,
+  model: OptionalType,
+): string {
+  const result = this.partials.someType(model.elementType);
+  return model.elementType.type === 'union' ? `(${result})?` : `${result}?`;
+}

packages/typedoc-plugin-markdown/src/theme/context/partials/type.some.ts

@@ -87,7 +87,7 @@ export function someType(
   }
 
   if (model instanceof OptionalType) {
-    return this.partials.someType(model.elementType) + '?';
+    return this.partials.optionalType(model);
   }
 
   if (model.toString() == 'null') {

packages/typedoc-plugin-markdown/src/theme/context/resources.ts

@@ -16,6 +16,7 @@ import {
   IntrinsicType,
   LiteralType,
   NamedTupleMember,
+  OptionalType,
   ParameterReflection,
   ProjectReflection,
   QueryType,
@@ -254,6 +255,8 @@ There is no association list partial for properties as these are handled as a st
       partials.literalType.apply(context, [model]) as string,
     namedTupleType: (model: NamedTupleMember) =>
       partials.namedTupleType.apply(context, [model]) as string,
+    optionalType: (model: OptionalType) =>
+      partials.optionalType.apply(context, [model]) as string,
     queryType: (model: QueryType) =>
       partials.queryType.apply(context, [model]) as string,
     referenceType: (model: ReferenceType) =>

packages/typedoc-plugin-markdown/test/__scripts__/build-fixtures.mjs

@@ -117,10 +117,7 @@ function writeMarkdown(
 }
 
 export function writeHtml(key, entryPoints) {
-  const fixturesRoot = path.join(
-    __dirname,
-    '../../../packages/typedoc-plugin-markdown/test/fixtures',
-  );
+  const fixturesRoot = path.join(__dirname, '..', 'fixtures');
   const fullPath = path.join(
     process.cwd(),
     'test',
@@ -134,9 +131,9 @@ export function writeHtml(key, entryPoints) {
     [
       ...[
         '-options',
-        path.join(__dirname, 'typedoc.cjs'),
+        path.join(__dirname, '..', 'fixtures', 'typedoc.cjs'),
         '-logLevel',
-        'None',
+        'Warn',
         '-out',
         fullPath,
         '-readme',

packages/typedoc-plugin-markdown/test/fixtures/src/reflections/functions.ts

@@ -245,11 +245,19 @@ export let curriedFunction: {
 };
 
 export type Stuff = { a: string; b: string };
+
 /**
  * Comments for array of stuff
  */
 export const functionWithArrayOfStuff = (a: [Stuff]) => {};
 
+/**
+ * Comments for array of union stuff
+ */
+export const functionWithArrayOfUnionStuff = (
+  a: [(null | undefined | Stuff)?],
+) => {};
+
 /**
  * Comments for array of stuff?
  */

packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap

@@ -4611,6 +4611,11 @@ exports[`Navigation should gets Navigation Json for single entry point: (Output
         "kind": 64,
         "path": "functions/functionWithArrayOfStuff.md"
       },
+      {
+        "title": "functionWithArrayOfUnionStuff",
+        "kind": 64,
+        "path": "functions/functionWithArrayOfUnionStuff.md"
+      },
       {
         "title": "functionWithComplexParams",
         "kind": 64,

packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap

@@ -446,7 +446,7 @@ http://abc.com
 "
 `;
 
-exports[`Function Reflection should compile function with array of stuff optional: (Output File Strategy "members") (Option Group "1") 1`] = `
+exports[`Function Reflection should compile function with array of optional stuff: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Function: functionWithArrayOfOptionalStuff()
 
 > **functionWithArrayOfOptionalStuff**(\`a\`): \`void\`
@@ -469,7 +469,7 @@ Comments for array of stuff?
 "
 `;
 
-exports[`Function Reflection should compile function with array of stuff optional: (Output File Strategy "members") (Option Group "2") 1`] = `
+exports[`Function Reflection should compile function with array of optional stuff: (Output File Strategy "members") (Option Group "2") 1`] = `
 "# Function: functionWithArrayOfOptionalStuff()
 
 \`\`\`ts
@@ -542,6 +542,54 @@ Comments for array of stuff
 "
 `;
 
+exports[`Function Reflection should compile function with array of union stuff: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Function: functionWithArrayOfUnionStuff()
+
+> **functionWithArrayOfUnionStuff**(\`a\`): \`void\`
+
+Comments for array of union stuff
+
+## Parameters
+
+### a
+
+[(\`null\` \\| [\`Stuff\`](../type-aliases/Stuff.md))?]
+
+## Returns
+
+\`void\`
+
+## Source
+
+[functions.ts:1](http://source-url)
+"
+`;
+
+exports[`Function Reflection should compile function with array of union stuff: (Output File Strategy "members") (Option Group "2") 1`] = `
+"# Function: functionWithArrayOfUnionStuff()
+
+\`\`\`ts
+function functionWithArrayOfUnionStuff(a: [(null | Stuff)?]): void
+\`\`\`
+
+Comments for array of union stuff
+
+## Parameters
+
+| Parameter | Type |
+| :------ | :------ |
+| \`a\` | [(\`null\` \\| [\`Stuff\`](../type-aliases/Stuff.md))?] |
+
+## Returns
+
+\`void\`
+
+## Source
+
+[functions.ts:1](http://source-url)
+"
+`;
+
 exports[`Function Reflection should compile function with complex params: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Function: functionWithComplexParams()
 

packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.index.spec.ts.snap

@@ -120,6 +120,7 @@ Module comments
 | [functionReturningAUnionType](functions/functionReturningAUnionType.md) | Comments for function |
 | [functionWithArrayOfOptionalStuff](functions/functionWithArrayOfOptionalStuff.md) | Comments for array of stuff? |
 | [functionWithArrayOfStuff](functions/functionWithArrayOfStuff.md) | Comments for array of stuff |
+| [functionWithArrayOfUnionStuff](functions/functionWithArrayOfUnionStuff.md) | Comments for array of union stuff |
 | [functionWithComplexParams](functions/functionWithComplexParams.md) | Function with function parmas |
 | [functionWithDefaultParameters](functions/functionWithDefaultParameters.md) | This is a function with a parameter that has a default value. |
 | [functionWithMultipleSignatures](functions/functionWithMultipleSignatures.md) | Main function comment. |

packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap

@@ -809,6 +809,7 @@ exports[`Urls should gets Urls for single entry points: outputFileStrategy: memb
   "functions/functionReturningAnObject.md",
   "functions/functionWithArrayOfOptionalStuff.md",
   "functions/functionWithArrayOfStuff.md",
+  "functions/functionWithArrayOfUnionStuff.md",
   "functions/functionWithComplexParams.md",
   "functions/functionWithDefaultParameters.md",
   "functions/functionWithMultipleSignatures.md",
@@ -898,6 +899,7 @@ exports[`Urls should gets Urls for single entry points: outputFileStrategy: memb
   "functions/functionReturningAnObject.md",
   "functions/functionWithArrayOfOptionalStuff.md",
   "functions/functionWithArrayOfStuff.md",
+  "functions/functionWithArrayOfUnionStuff.md",
   "functions/functionWithComplexParams.md",
   "functions/functionWithDefaultParameters.md",
   "functions/functionWithMultipleSignatures.md",

packages/typedoc-plugin-markdown/test/specs/reflection.function.spec.ts

@@ -129,14 +129,22 @@ describe(`Function Reflection`, () => {
     );
   });
 
-  test(`should compile function with array of stuff optional`, () => {
+  test(`should compile function with array of optional stuff`, () => {
     expectFileToEqual(
       'reflections',
       'members',
       'functions/functionWithArrayOfOptionalStuff.md',
     );
   });
 
+  test(`should compile function with array of union stuff`, () => {
+    expectFileToEqual(
+      'reflections',
+      'members',
+      'functions/functionWithArrayOfUnionStuff.md',
+    );
+  });
+
   test(`should compile function with union params`, () => {
     expectFileToEqual(
       'reflections',