fix: Use backticks for generics and refernce types to improve consist…

…ency (#239)
typedoc2md · Jun 23, 2021 · 1b3395f · 1b3395f
1 parent 702a6e4
commit 1b3395f
Show file tree

Hide file tree

Showing 13 changed files with 65 additions and 35 deletions.
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/declaration-title.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/declaration-title.ts
@@ -22,7 +22,7 @@ export function declarationTitle(
   if (this instanceof DeclarationReflection && this.typeParameters) {
     md.push(
       `<${this.typeParameters
-        .map((typeParameter) => typeParameter.name)
+        .map((typeParameter) => `\`${typeParameter.name}\``)
         .join(', ')}\\>`,
     );
   }
@@ -36,7 +36,9 @@ export function declarationTitle(
     this.defaultValue &&
     this.defaultValue !== '...'
   ) {
-    md.push(` = ${stripLineBreaks(escape(stripComments(this.defaultValue)))}`);
+    md.push(
+      ` = \`${stripLineBreaks(escape(stripComments(this.defaultValue)))}\``,
+    );
   }
   return md.join('');
 }

diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/hierarchy.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/hierarchy.ts
@@ -8,7 +8,7 @@ export function hierarchy(this: DeclarationHierarchy, level: number) {
   const symbol = level > 0 ? getSymbol(level) : '-';
   this.types.forEach((hierarchyType) => {
     if (this.isTarget) {
-      md.push(`${symbol} **${hierarchyType}**`);
+      md.push(`${symbol} **\`${hierarchyType}\`**`);
     } else {
       md.push(`${symbol} ${type.call(hierarchyType)}`);
     }

diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/parameter-table.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/parameter-table.ts
@@ -1,7 +1,6 @@
 import { ParameterReflection, ReflectionKind } from 'typedoc';
 
 import { comment } from './comment';
-import { escape } from './escape';
 import { stripLineBreaks } from './strip-line-breaks';
 import { type } from './type';
 
@@ -89,7 +88,7 @@ function table(parameters: any) {
 
 function getDefaultValue(parameter: ParameterReflection) {
   return parameter.defaultValue && parameter.defaultValue !== '...'
-    ? escape(parameter.defaultValue)
+    ? `\`${parameter.defaultValue}\``
     : '`undefined`';
 }
 

diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/signature-title.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/signature-title.ts
@@ -31,7 +31,7 @@ export function signatureTitle(
   if (this.typeParameters) {
     md.push(
       `<${this.typeParameters
-        .map((typeParameter) => typeParameter.name)
+        .map((typeParameter) => `\`${typeParameter.name}\``)
         .join(', ')}\\>`,
     );
   }

diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/type.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/type.ts
@@ -188,17 +188,15 @@ function getReferenceType(model: ReferenceType, emphasis) {
     const reflection =
       model.reflection && model.reflection.url
         ? [
-            `[${escape(
-              model.reflection.name,
-            )}](${MarkdownTheme.HANDLEBARS.helpers.relativeURL(
+            `[${`\`${model.reflection.name}\``}](${MarkdownTheme.HANDLEBARS.helpers.relativeURL(
               model.reflection.url,
             )})`,
           ]
-        : [emphasis ? `\`${escape(model.name)}\`` : escape(model.name)];
+        : [`\`${model.name}\``];
     if (model.typeArguments && model.typeArguments.length > 0) {
       reflection.push(
         `<${model.typeArguments
-          .map((typeArgument) => `${type.call(typeArgument, 'all', false)}`)
+          .map((typeArgument) => type.call(typeArgument, 'all'))
           .join(', ')}\\>`,
       );
     }

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/declarations.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/declarations.spec.ts.snap
@@ -8,7 +8,7 @@ exports[`Declarations: should compile a const with default value 1`] = `
 `;
 
 exports[`Declarations: should compile a let with default value 1`] = `
-"• \`Let\` **stringLetWithDefaultValue**: \`string\` = 'hello'
+"• \`Let\` **stringLetWithDefaultValue**: \`string\` = \`'hello'\`
 
 [partial: member.sources]
 "
@@ -22,7 +22,7 @@ exports[`Declarations: should compile an undefined declaration 1`] = `
 `;
 
 exports[`Declarations: should compile any function type 1`] = `
-"Ƭ **AnyFunctionType**<A\\\\>: (...\`input\`: \`any\`[]) => \`A\`
+"Ƭ **AnyFunctionType**<\`A\`\\\\>: (...\`input\`: \`any\`[]) => \`A\`
 
 #### Type parameters
 
@@ -77,14 +77,14 @@ exports[`Declarations: should compile callable declaration 1`] = `
 `;
 
 exports[`Declarations: should compile declaration with double underscores in name and value 1`] = `
-"• \`Const\` **\\\\_\\\\_DOUBLE\\\\_UNDERSCORES\\\\_DECLARATION\\\\_\\\\_**: typeof [\\\\_\\\\_DOUBLE\\\\_UNDERSCORES\\\\_DECLARATION\\\\_\\\\_](../modules.md#__double_underscores_declaration__)
+"• \`Const\` **\\\\_\\\\_DOUBLE\\\\_UNDERSCORES\\\\_DECLARATION\\\\_\\\\_**: typeof [\`__DOUBLE_UNDERSCORES_DECLARATION__\`](../modules.md#__double_underscores_declaration__)
 
 [partial: member.sources]
 "
 `;
 
 exports[`Declarations: should compile enum delcaration 1`] = `
-"• **Down** = \\"DOWN\\"
+"• **Down** = \`\\"DOWN\\"\`
 
 [partial: member.sources]
 "

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/generics.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/generics.spec.ts.snap
@@ -21,7 +21,7 @@ exports[`Generics: should compile class with type params 1`] = `
 `;
 
 exports[`Generics: should compile function with a simple type param' 1`] = `
-"▸ \`Const\` **functionWithTypeParam**<A\\\\>(): \`boolean\`
+"▸ \`Const\` **functionWithTypeParam**<\`A\`\\\\>(): \`boolean\`
 
 [partial: comment]
 
@@ -38,15 +38,15 @@ exports[`Generics: should compile function with a simple type param' 1`] = `
 `;
 
 exports[`Generics: should compile function with complex type params' 1`] = `
-"▸ \`Const\` **functionWithTypeParams**<A, B, C\\\\>(): \`boolean\`
+"▸ \`Const\` **functionWithTypeParams**<\`A\`, \`B\`, \`C\`\\\\>(): \`boolean\`
 
 [partial: comment]
 
 ##### Type parameters
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| \`A\` | \`A\`: [ClassWithTypeParams](classwithtypeparams.md)<string, number, A\\\\> | Comment for type \`A\` |
+| \`A\` | \`A\`: [\`ClassWithTypeParams\`](classwithtypeparams.md)<\`string\`, \`number\`, \`A\`\\\\> | Comment for type \`A\` |
 | \`B\` | \`B\` = \`string\` \\\\| \`boolean\` | Comment for type \`B\` |
 | \`C\` | \`C\` = \`string\` | - |
 
@@ -55,3 +55,12 @@ exports[`Generics: should compile function with complex type params' 1`] = `
 \`boolean\`
 "
 `;
+
+exports[`Generics: should compile type with nested generics' 1`] = `
+"Ƭ **nestedGenerics**: [\`Generic1\`](../modules.md#generic1)<[\`Generic2\`](../modules.md#generic2)<[\`Generic3\`](../modules.md#generic3)<\`string\`\\\\>\\\\>\\\\>
+
+[partial: comment]
+
+[partial: member.sources]
+"
+`;
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/hierarchy.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/hierarchy.spec.ts.snap
@@ -1,19 +1,19 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Hierarchy: should compile nested type hierarchy 1`] = `
-"- [ParentClass](parentclass.md)
+"- [\`ParentClass\`](parentclass.md)
 
-  ↳ **ChildClassA**
+  ↳ **\`ChildClassA\`**
 
-  ↳↳ [GrandChildClassA](grandchildclassa.md)
+  ↳↳ [\`GrandChildClassA\`](grandchildclassa.md)
 "
 `;
 
 exports[`Hierarchy: should compile type hierarchy 1`] = `
-"- **ParentClass**
+"- **\`ParentClass\`**
 
-  ↳ [ChildClassA](childclassa.md)
+  ↳ [\`ChildClassA\`](childclassa.md)
 
-  ↳ [ChildClassB](childclassb.md)
+  ↳ [\`ChildClassB\`](childclassb.md)
 "
 `;
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflections.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflections.spec.ts.snap
@@ -53,7 +53,7 @@ exports[`Reflections: (template) should compile implemented class 1`] = `
 
 ## Implements
 
-- [ReflectionClass](../classes/reflectionclass.md)
+- [\`ReflectionClass\`](../classes/reflectionclass.md)
 
 [helper: toc]
 

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/signatures.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/signatures.spec.ts.snap
@@ -32,7 +32,7 @@ Comments for function
 
 Return comments
 
-▸ <T\\\\>(\`x\`): \`boolean\`
+▸ <\`T\`\\\\>(\`x\`): \`boolean\`
 
 ##### Type parameters
 
@@ -102,7 +102,7 @@ exports[`Signatures: should compile function with reference type' 1`] = `
 
 | Name | Type |
 | :------ | :------ |
-| \`descriptor\` | \`TypedPropertyDescriptor\`<any\\\\> |
+| \`descriptor\` | \`TypedPropertyDescriptor\`<\`any\`\\\\> |
 
 ##### Returns
 
@@ -191,12 +191,12 @@ This is a function with a parameter that has a default value.
 
 | Name | Type | Default value | Description |
 | :------ | :------ | :------ | :------ |
-| \`valueA\` | \`string\` | 'defaultValue' | A parameter with a default string value. |
-| \`valueB\` | \`number\` | 100 | A parameter with a default numeric value. |
+| \`valueA\` | \`string\` | \`'defaultValue'\` | A parameter with a default string value. |
+| \`valueB\` | \`number\` | \`100\` | A parameter with a default numeric value. |
 | \`valueC\` | \`number\` | \`undefined\` | A parameter with a default NaN value. |
-| \`valueD\` | \`boolean\` | true | A parameter with a default boolean value. |
-| \`valueE\` | \`boolean\` | null | A parameter with a default null value. |
-| \`valueF\` | \`string\` | '<foo\\\\>' | - |
+| \`valueD\` | \`boolean\` | \`true\` | A parameter with a default boolean value. |
+| \`valueE\` | \`boolean\` | \`null\` | A parameter with a default null value. |
+| \`valueF\` | \`string\` | \`'<foo>'\` | - |
 
 ##### Returns
 

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/types.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/types.spec.ts.snap
@@ -5,7 +5,7 @@ exports[`Types: should compile 'array' type' 1`] = `
 "
 `;
 
-exports[`Types: should compile 'intersection' type' 1`] = `"[IntersectionClassA](intersectionclassa.md) & [IntersectionClassB](intersectionclassb.md)"`;
+exports[`Types: should compile 'intersection' type' 1`] = `"[\`IntersectionClassA\`](intersectionclassa.md) & [\`IntersectionClassB\`](intersectionclassb.md)"`;
 
 exports[`Types: should compile 'stringLiteral' type' 1`] = `
 "\`\`\\"blue\\"\`\`

diff --git a/packages/typedoc-plugin-markdown/test/specs/generics.spec.ts b/packages/typedoc-plugin-markdown/test/specs/generics.spec.ts
@@ -6,16 +6,23 @@ import { TestApp } from '../test-app';
 describe(`Generics:`, () => {
   let testApp: TestApp;
   let partial: Handlebars.TemplateDelegate;
+  let declarationPartial: Handlebars.TemplateDelegate;
   let reflectionTemplate: Handlebars.TemplateDelegate;
 
   beforeAll(() => {
     testApp = new TestApp(['generics.ts']);
     partial = TestApp.getPartial('member.signature');
+    declarationPartial = TestApp.getPartial('member.declaration');
   });
 
   beforeEach(async () => {
     await testApp.bootstrap();
-    TestApp.stubPartials(['comment', 'member.signature', 'members']);
+    TestApp.stubPartials([
+      'comment',
+      'member.signature',
+      'members',
+      'member.sources',
+    ]);
     TestApp.stubHelpers(['toc', 'breadcrumbs', 'hierarchy', 'returns']);
     reflectionTemplate = TestApp.getTemplate('reflection');
   });
@@ -48,4 +55,13 @@ describe(`Generics:`, () => {
       ),
     ).toMatchSnapshot();
   });
+
+  test(`should compile type with nested generics'`, () => {
+    expect(
+      TestApp.compileTemplate(
+        declarationPartial,
+        testApp.findReflection('nestedGenerics'),
+      ),
+    ).toMatchSnapshot();
+  });
 });
diff --git a/packages/typedoc-plugin-markdown/test/stubs/src/generics.ts b/packages/typedoc-plugin-markdown/test/stubs/src/generics.ts
@@ -18,7 +18,7 @@ export const functionWithTypeParam = <A>() => true;
 export const functionWithTypeParams = <
   A extends ClassWithTypeParams<string, number>,
   B = boolean | string,
-  C = string
+  C = string,
 >() => true;
 
 export function functionWithGenericConstraints<Type, Key extends keyof Type>(
@@ -27,3 +27,9 @@ export function functionWithGenericConstraints<Type, Key extends keyof Type>(
 ) {
   return obj[key];
 }
+
+export type Generic1<T> = Generic2<Generic3<T>>;
+export type Generic2<T> = T;
+export type Generic3<T> = T;
+
+export type nestedGenerics = Generic1<Generic2<Generic3<string>>>;