feat: Expose expandParameters option.

typedoc2md · Feb 6, 2024 · af69f66 · af69f66
1 parent 4324183
commit af69f66
Show file tree

Hide file tree

Showing 37 changed files with 1,587 additions and 296 deletions.
diff --git a/.changeset/warm-colts-deny.md b/.changeset/warm-colts-deny.md
@@ -0,0 +1,5 @@
+---
+"typedoc-plugin-markdown": patch
+---
+
+- Expose `expandParameters` option.
diff --git a/devtools/packages/fixtures/cli.ts b/devtools/packages/fixtures/cli.ts
@@ -28,7 +28,8 @@ async function main() {
 
   const fixtureCount = fixturesToBuild.reduce(
     (prev, curr) =>
-      prev + curr[1].options.length * (curr[1].outputFileStragies?.length || 2),
+      prev +
+      curr[1].options.length * (curr[1].outputFileStrategies?.length || 2),
     0,
   );
 
@@ -39,6 +40,7 @@ async function main() {
   fixturesToBuild.forEach(([key, config]) => {
     const outputFileStrategies: ('members' | 'modules')[] =
       config.outputFileStrategies || ['members', 'modules'];
+
     writeHtml(key, config.entryPoints);
     outputFileStrategies.forEach((outputFileStrategy) => {
       config.options.forEach((optionGroup, index: number) => {

diff --git a/devtools/packages/fixtures/models.ts b/devtools/packages/fixtures/models.ts
@@ -1,7 +1,7 @@
 export interface Fixture {
   only?: boolean;
   entryPoints: string;
-  outputFileStragies?: ('members' | 'modules')[];
+  outputFileStrategies?: ('members' | 'modules')[];
   commonOptions: Record<string, any>;
   options: Record<string, any>[];
 }
diff --git a/docs/pages/options.mdx b/docs/pages/options.mdx
@@ -275,6 +275,36 @@ This option should be set when a full object representation is preferred.
 
 ___
 
+### expandParameters
+
+<Callout>Expand parameters to display type information.</Callout>
+
+> Accepts a boolean value. Defaults to `false`.
+
+By default parameters in signature definitions only display the parameter name.
+
+This option should be set when a full type representation is preferred.
+
+This is the oppisite of TypeDoc's [hideParameterTypesInTitle](https://typedoc.org/options/output/#hideparametertypesintitle) output option.
+
+**Default**
+
+`someFunction(param1, param2)`
+
+**Expanded**
+
+`someFunction(param1: string, param2: boolean)`
+
+
+```json filename="typedoc.json"
+{
+  "expandParameters": false
+}
+
+```
+
+___
+
 ### parametersFormat
 
 <Callout>Specify the render style of parameter and type parameter groups.</Callout>

diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/declarations.ts b/packages/typedoc-plugin-markdown/src/plugin/options/declarations.ts
@@ -191,6 +191,29 @@ export const expandObjects: Partial<DeclarationOption> = {
   defaultValue: false,
 };
 
+/**
+ * By default parameters in signature definitions only display the parameter name so the output is more concise.
+ *
+ * This option should be set when a full type representation is preferred.
+ *
+ * This is the oppisite of TypeDoc's [hideParameterTypesInTitle](https://typedoc.org/options/output/#hideparametertypesintitle) output option.
+ *
+ * @Default
+ *
+ * `someFunction(param1, param2)`
+ *
+ * @Expanded
+ *
+ * `someFunction(param1: string, param2: boolean)`
+ *
+ * @category UI
+ */
+export const expandParameters: Partial<DeclarationOption> = {
+  help: 'Expand parameters to display type information.',
+  type: ParameterType.Boolean,
+  defaultValue: false,
+};
+
 /**
  * This option either renders parameters for functions and class methods as a list or in tabular format.
  *

diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/option-types.ts b/packages/typedoc-plugin-markdown/src/plugin/options/option-types.ts
@@ -17,6 +17,7 @@ declare module 'typedoc' {
     excludeGroups: boolean;
     useCodeBlocks: boolean;
     expandObjects: boolean;
+    expandParameters: boolean;
     parametersFormat: 'list' | 'table';
     propertiesFormat: 'list' | 'table';
     enumMembersFormat: 'list' | 'table';
@@ -44,6 +45,7 @@ export interface PluginOptions {
   excludeGroups: boolean;
   useCodeBlocks: boolean;
   expandObjects: boolean;
+  expandParameters: boolean;
   parametersFormat: 'list' | 'table';
   propertiesFormat: 'list' | 'table';
   enumMembersFormat: 'list' | 'table';

diff --git a/...ges/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.identifier.ts b/...ges/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.identifier.ts
@@ -1,7 +1,7 @@
 import { DeclarationReflection } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
 import { backTicks, bold, codeBlock } from '../markdown';
-import { escapeChars, stripComments, stripLineBreaks } from '../utils';
+import { escapeChars, stripComments } from '../utils';
 
 export function declarationMemberIdentifier(
   context: MarkdownThemeRenderContext,
@@ -73,10 +73,12 @@ export function declarationMemberIdentifier(
     md.push(context.partials.someType(declarationType));
   }
 
-  if (reflection.defaultValue && reflection.defaultValue !== '...') {
-    md.push(
-      ` = \`${stripLineBreaks(stripComments(reflection.defaultValue))}\``,
-    );
+  if (
+    reflection.defaultValue &&
+    reflection.defaultValue !== '...' &&
+    reflection.name !== reflection.defaultValue?.slice(1, -1)
+  ) {
+    md.push(` = \`${stripComments(reflection.defaultValue)}\``);
   }
 
   if (useCodeBlocks) {

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.identifier.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.identifier.ts
@@ -54,12 +54,7 @@ export function signatureMemberIdentifier(
     );
   }
 
-  md.push(
-    context.partials.signatureParameters(
-      signature.parameters || [],
-      useCodeBlocks,
-    ),
-  );
+  md.push(context.partials.signatureParameters(signature.parameters || []));
 
   if (signature.type) {
     md.push(`: ${context.partials.someType(signature.type)}`);

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.parameters.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.parameters.ts
@@ -1,15 +1,12 @@
-import { ParameterReflection } from 'typedoc';
+import { ParameterReflection, ReflectionType, SomeType } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
-import { backTicks } from '../markdown';
+import { backTicks, indentBlock } from '../markdown';
 
-/**
- * @category Partials
- */
 export function signatureParameters(
   context: MarkdownThemeRenderContext,
   parameters: ParameterReflection[],
-  format = false,
 ) {
+  const format = context.options.getValue('useCodeBlocks');
   const firstOptionalParamIndex = parameters.findIndex(
     (parameter) => parameter.flags.isOptional,
   );
@@ -21,14 +18,25 @@ export function signatureParameters(
         if (param.flags.isRest) {
           paramsmd.push('...');
         }
-        const paramItem = `${backTicks(param.name)}${
-          param.flags.isOptional ||
-          (firstOptionalParamIndex !== -1 && i > firstOptionalParamIndex)
-            ? '?'
-            : ''
-        }`;
+        const paramType = context.partials.someType(param.type as SomeType);
+        const showParamType = context.options.getValue('expandParameters');
+        const paramItem = [
+          `${backTicks(param.name)}${
+            param.flags.isOptional ||
+            (firstOptionalParamIndex !== -1 && i > firstOptionalParamIndex)
+              ? '?'
+              : ''
+          }`,
+        ];
+        if (showParamType) {
+          paramItem.push(
+            param.type instanceof ReflectionType
+              ? indentBlock(paramType)
+              : paramType,
+          );
+        }
         paramsmd.push(
-          `${format && parameters.length > 2 ? `\n   ` : ''}${paramItem}`,
+          `${format && parameters.length > 2 ? `\n   ` : ''}${paramItem.join(': ')}`,
         );
         return paramsmd.join('');
       })

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.returns.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.returns.ts
@@ -6,7 +6,7 @@ import {
   SomeType,
 } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
-import { backTicks, blockQuoteBlock, heading } from '../markdown';
+import { backTicks, blockQuoteBlock, codeBlock, heading } from '../markdown';
 
 export function signatureMemberReturns(
   context: MarkdownThemeRenderContext,
@@ -57,9 +57,7 @@ export function signatureMemberReturns(
 
   if (typeDeclaration?.children) {
     md.push(
-      blockQuoteBlock(
-        context.partials.typeDeclarationMember(typeDeclaration, headingLevel),
-      ),
+      context.partials.typeDeclarationMember(typeDeclaration, headingLevel),
     );
   }
 
@@ -71,11 +69,19 @@ function getReturnType(
   typeDeclaration?: DeclarationReflection,
   type?: SomeType,
 ) {
-  if (typeDeclaration?.children) {
-    return backTicks('Object');
-  }
   if (typeDeclaration?.signatures) {
     return backTicks('Function');
   }
-  return type ? context.partials.someType(type, true).replace(/\n/g, ' ') : '';
+  if (type) {
+    const returnType = context.partials.someType(type);
+    if (
+      type instanceof ReflectionType &&
+      context.options.getValue('expandObjects') &&
+      context.options.getValue('useCodeBlocks')
+    ) {
+      return codeBlock(returnType);
+    }
+    return returnType;
+  }
+  return '';
 }
diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/table.enum-members.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/table.enum-members.ts
@@ -1,7 +1,7 @@
 import { DeclarationReflection, ReflectionType } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
 import { backTicks } from '../markdown';
-import { stripLineBreaks } from '../utils';
+import { formatTableDescriptionCol, formatTableTypeCol } from '../utils';
 
 export function enumMembersTable(
   context: MarkdownThemeRenderContext,
@@ -34,17 +34,12 @@ export function enumMembersTable(
 
     row.push(nameColumn.join(' '));
     if (propertyType) {
-      row.push(stripLineBreaks(context.partials.someType(propertyType)));
+      row.push(formatTableTypeCol(context.partials.someType(propertyType)));
     }
     if (hasComments) {
       const comments = getComments(property);
       if (comments) {
-        row.push(
-          stripLineBreaks(context.partials.comment(comments)).replace(
-            /\|/g,
-            '\\|',
-          ),
-        );
+        row.push(formatTableDescriptionCol(context.partials.comment(comments)));
       } else {
         row.push('-');
       }

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/table.parameters.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/table.parameters.ts
@@ -1,7 +1,7 @@
 import { ParameterReflection, ReflectionKind } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
 import { backTicks, table } from '../markdown';
-import { formatTableDescriptionCol, stripLineBreaks } from '../utils';
+import { formatTableDescriptionCol, formatTableTypeCol } from '../utils';
 
 export function parametersTable(
   context: MarkdownThemeRenderContext,
@@ -72,7 +72,7 @@ export function parametersTable(
 
     if (parameter.type) {
       row.push(
-        stripLineBreaks(context.partials.someType(parameter.type), false),
+        formatTableTypeCol(context.partials.someType(parameter.type), false),
       );
     }
 
@@ -83,10 +83,8 @@ export function parametersTable(
     if (hasComments) {
       if (parameter.comment) {
         row.push(
-          stripLineBreaks(
-            formatTableDescriptionCol(
-              context.partials.comment(parameter.comment),
-            ),
+          formatTableDescriptionCol(
+            context.partials.comment(parameter.comment),
           ),
         );
       } else {

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/table.properties.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/table.properties.ts
@@ -1,7 +1,7 @@
 import { DeclarationReflection } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
 import { backTicks, strikeThrough, table } from '../markdown';
-import { formatTableDescriptionCol, stripLineBreaks } from '../utils';
+import { formatTableDescriptionCol, formatTableTypeCol } from '../utils';
 
 export function propertiesTable(
   context: MarkdownThemeRenderContext,
@@ -91,7 +91,7 @@ export function propertiesTable(
             true,
           )
         : context.partials.someType(propertyType);
-      row.push(stripLineBreaks(type, false));
+      row.push(formatTableTypeCol(type, false));
     }
 
     if (hasComments) {
@@ -100,11 +100,7 @@ export function propertiesTable(
         property?.comment?.summary?.length;
       const comments = property?.comment;
       if (hasComment && comments) {
-        row.push(
-          stripLineBreaks(
-            formatTableDescriptionCol(context.partials.comment(comments)),
-          ),
-        );
+        row.push(formatTableDescriptionCol(context.partials.comment(comments)));
       } else {
         row.push('-');
       }