feat: UI fixes and readability enhancements (#230)

typedoc2md · May 30, 2021 · 4aa9fbd · 4aa9fbd
1 parent 283b15c
commit 4aa9fbd
Show file tree

Hide file tree

Showing 33 changed files with 836 additions and 427 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
@@ -1,9 +1,9 @@
+import { DeclarationReflection, ParameterReflection } from 'typedoc';
 import {
-  DeclarationReflection,
-  ParameterReflection,
+  LiteralType,
   ReflectionKind,
-} from 'typedoc';
-import { ReflectionType } from 'typedoc/dist/lib/models';
+  ReflectionType,
+} from 'typedoc/dist/lib/models';
 
 import { escape } from './escape';
 import { memberSymbol } from './member-symbol';
@@ -27,15 +27,26 @@ export function declarationTitle(
     );
   }
 
-  md.push(`: ${this.parent?.kindOf(ReflectionKind.Enum) ? '' : getType(this)}`);
+  if (!this.parent?.kindOf(ReflectionKind.Enum)) {
+    md.push(getType(this));
+  }
 
-  if (this.defaultValue && this.defaultValue !== '...') {
-    md.push(`= ${stripLineBreaks(escape(stripComments(this.defaultValue)))}`);
+  if (
+    !(this.type instanceof LiteralType) &&
+    this.defaultValue &&
+    this.defaultValue !== '...'
+  ) {
+    md.push(` = ${stripLineBreaks(escape(stripComments(this.defaultValue)))}`);
   }
   return md.join('');
 }
 
 function getType(reflection: ParameterReflection | DeclarationReflection) {
   const reflectionType = reflection.type as ReflectionType;
-  return type.call(reflectionType ? reflectionType : reflection, 'object');
+  if (reflectionType && reflectionType.declaration?.children) {
+    return ': `Object`';
+  }
+  return (
+    ': ' + type.call(reflectionType ? reflectionType : reflection, 'object')
+  );
 }
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/if-show-returns.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/if-show-returns.ts
@@ -0,0 +1,11 @@
+import * as Handlebars from 'handlebars';
+import { ReflectionKind, SignatureReflection } from 'typedoc';
+
+export function ifShowReturns(
+  this: SignatureReflection,
+  options: Handlebars.HelperOptions,
+) {
+  return this.type && !this.parent?.kindOf(ReflectionKind.Constructor)
+    ? options.fn(this)
+    : options.inverse(this);
+}
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/member-symbol.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/member-symbol.ts
@@ -3,9 +3,6 @@ import { DeclarationReflection, ReflectionKind } from 'typedoc';
 export function memberSymbol(this: DeclarationReflection) {
   const isStatic = this.flags && this.flags.isStatic;
 
-  if (this.kind === ReflectionKind.ConstructorSignature) {
-    return '\\+';
-  }
   if (this.kind === ReflectionKind.CallSignature) {
     return '▸';
   }

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,18 +1,11 @@
-import {
-  ParameterReflection,
-  ReflectionKind,
-  TypeParameterReflection,
-} from 'typedoc';
+import { ParameterReflection, ReflectionKind } from 'typedoc';
 
 import { comment } from './comment';
 import { escape } from './escape';
 import { stripLineBreaks } from './strip-line-breaks';
 import { type } from './type';
 
-export function parameterTable(
-  this: ParameterReflection[] & TypeParameterReflection[],
-  kind: 'typeParameters' | 'parameters',
-) {
+export function parameterTable(this: ParameterReflection[]) {
   const flattenParams = (current: any) => {
     return current.type?.declaration?.children?.reduce(
       (acc: any, child: any) => {
@@ -37,28 +30,22 @@ export function parameterTable(
 
   return table(
     this.reduce((acc: any, current: any) => parseParams(current, acc), []),
-    kind,
   );
 }
 
-function table(parameters: any, kind: 'typeParameters' | 'parameters') {
-  const showDefaults = hasDefaultValues(kind, parameters);
-  const showTypes = kind === 'parameters' ? true : hasTypes(parameters);
+function table(parameters: any) {
+  const showDefaults = hasDefaultValues(parameters);
 
   const comments = parameters.map(
     (param) =>
       !!param.comment?.text?.trim() || !!param.comment?.shortText?.trim(),
   );
   const hasComments = !comments.every((value) => !value);
 
-  const headers = ['Name'];
-
-  if (showTypes) {
-    headers.push('Type');
-  }
+  const headers = ['Name', 'Type'];
 
   if (showDefaults) {
-    headers.push(kind === 'parameters' ? 'Default value' : 'Default');
+    headers.push('Default value');
   }
 
   if (hasComments) {
@@ -74,9 +61,7 @@ function table(parameters: any, kind: 'typeParameters' | 'parameters') {
       }\``,
     );
 
-    if (showTypes) {
-      row.push(parameter.type ? type.call(parameter.type, 'object') : '-');
-    }
+    row.push(type.call(parameter.type, 'object'));
 
     if (showDefaults) {
       row.push(getDefaultValue(parameter));
@@ -102,37 +87,19 @@ function table(parameters: any, kind: 'typeParameters' | 'parameters') {
   return output;
 }
 
-function getDefaultValue(
-  parameter: ParameterReflection | TypeParameterReflection,
-) {
-  if (parameter instanceof TypeParameterReflection) {
-    return parameter.default ? type.call(parameter.default) : '-';
-  }
+function getDefaultValue(parameter: ParameterReflection) {
   return parameter.defaultValue && parameter.defaultValue !== '...'
     ? escape(parameter.defaultValue)
-    : '-';
+    : '`undefined`';
 }
 
-function hasDefaultValues(
-  kind: 'typeParameters' | 'parameters',
-  parameters: ParameterReflection[] | TypeParameterReflection[],
-) {
-  const defaultValues =
-    kind === 'parameters'
-      ? (parameters as ParameterReflection[]).map(
-          (param) => param.defaultValue !== '...' && !!param.defaultValue,
-        )
-      : (parameters as TypeParameterReflection[]).map(
-          (param) => !!param.default,
-        );
-  return !defaultValues.every((value) => !value);
-}
-
-function hasTypes(
-  parameters: TypeParameterReflection[] | ParameterReflection[],
-) {
-  const types = (parameters as TypeParameterReflection[]).map(
-    (param) => !!param.type,
+function hasDefaultValues(parameters: ParameterReflection[]) {
+  const defaultValues = (parameters as ParameterReflection[]).map(
+    (param) =>
+      param.defaultValue !== '{}' &&
+      param.defaultValue !== '...' &&
+      !!param.defaultValue,
   );
-  return !types.every((value) => !value);
+
+  return !defaultValues.every((value) => !value);
 }
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/returns.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/returns.ts
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/signature-title.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/signature-title.ts
@@ -1,4 +1,9 @@
-import { SignatureReflection } from 'typedoc';
+import {
+  ParameterReflection,
+  ReflectionKind,
+  SignatureReflection,
+} from 'typedoc';
+
 import { memberSymbol } from './member-symbol';
 import { type } from './type';
 
@@ -18,7 +23,7 @@ export function signatureTitle(
   }
 
   if (accessor) {
-    md.push(`${accessor} **${this.name}**`);
+    md.push(`\`${accessor}\` **${this.name}**`);
   } else if (this.name !== '__call' && this.name !== '__type') {
     md.push(`**${this.name}**`);
   }
@@ -30,26 +35,29 @@ export function signatureTitle(
         .join(', ')}\\>`,
     );
   }
+  md.push(`(${getParameters(this.parameters)})`);
 
-  const params = this.parameters
-    ? this.parameters
-        .map((param) => {
-          const paramsmd: string[] = [];
-          if (param.flags.isRest) {
-            paramsmd.push('...');
-          }
-          paramsmd.push(`\`${param.name}`);
-          if (param.flags.isOptional || param.defaultValue) {
-            paramsmd.push('?');
-          }
-          paramsmd.push(`\`: ${type.call(param.type, true)}`);
-          return paramsmd.join('');
-        })
-        .join(', ')
-    : '';
-  md.push(`(${params})`);
-  if (this.type) {
-    md.push(`: ${type.call(this.type, 'all')}`);
+  if (this.type && !this.parent?.kindOf(ReflectionKind.Constructor)) {
+    md.push(`: ${type.call(this.type, 'object')}`);
   }
   return md.join('') + (standalone ? '\n' : '');
 }
+
+const getParameters = (
+  parameters: ParameterReflection[] = [],
+  backticks = true,
+) => {
+  return parameters
+    .map((param) => {
+      const paramsmd: string[] = [];
+      if (param.flags.isRest) {
+        paramsmd.push('...');
+      }
+      const paramItem = `${param.name}${
+        param.flags.isOptional || param.defaultValue ? '?' : ''
+      }`;
+      paramsmd.push(backticks ? `\`${paramItem}\`` : paramItem);
+      return paramsmd.join('');
+    })
+    .join(', ');
+};
diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/type-and-parent.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/type-and-parent.ts
@@ -11,45 +11,28 @@ export function typeAndParent(this: ArrayType | ReferenceType) {
     } else {
       if (this.reflection) {
         const md: string[] = [];
-        const parentReflection = this.reflection.parent;
         if (this.reflection instanceof SignatureReflection) {
-          if (
-            parentReflection &&
-            parentReflection.parent &&
-            parentReflection.parent.url
-          ) {
+          if (this.reflection.parent?.parent?.url) {
             md.push(
-              `[${
-                parentReflection.parent.name
-              }](${MarkdownTheme.HANDLEBARS.helpers.relativeURL(
-                parentReflection.parent.url,
-              )})`,
+              getUrl(
+                this.reflection.parent.parent.name,
+                this.reflection.parent.parent.url,
+              ),
             );
-          } else if (parentReflection && parentReflection.parent) {
-            md.push(parentReflection.parent.name);
+            if (this.reflection.parent.url) {
+              md.push(
+                getUrl(this.reflection.parent.name, this.reflection.parent.url),
+              );
+            }
           }
         } else {
-          if (parentReflection && parentReflection.url) {
+          if (this.reflection.parent?.url) {
             md.push(
-              `[${
-                parentReflection.name
-              }](${MarkdownTheme.HANDLEBARS.helpers.relativeURL(
-                parentReflection.url,
-              )})`,
+              getUrl(this.reflection.parent.name, this.reflection.parent.url),
             );
-          } else if (parentReflection) {
-            md.push(parentReflection.name);
-          }
-          if (this.reflection.url) {
-            md.push(
-              `[${
-                this.reflection.name
-              }](${MarkdownTheme.HANDLEBARS.helpers.relativeURL(
-                this.reflection.url,
-              )})`,
-            );
-          } else {
-            md.push(this.reflection.name);
+            if (this.reflection.url) {
+              md.push(getUrl(this.reflection.name, this.reflection.url));
+            }
           }
         }
         return md.join('.');
@@ -60,3 +43,6 @@ export function typeAndParent(this: ArrayType | ReferenceType) {
   }
   return 'void';
 }
+
+const getUrl = (name: string, url: string) =>
+  `[${name}](${MarkdownTheme.HANDLEBARS.helpers.relativeURL(url)})`;