Merge pull request #363 from capraynor/master

Add objectLiteralTypeDeclarationStyle option.

packages/typedoc-plugin-markdown/src/index.ts

@@ -80,6 +80,19 @@ export function load(app: Application) {
     type: ParameterType.Boolean,
     defaultValue: false,
   });
-}
 
+
+  app.options.addDeclaration({
+    help: '[Markdown Plugin] Specify the Type Declaration Render Style',
+    name: 'objectLiteralTypeDeclarationStyle',
+    type: ParameterType.String,
+    defaultValue: "table",
+    validate: (x) => {
+      const availableValues = ["table", "list"];
+      if (!availableValues.includes(x)){
+        throw new Error(`Wrong value for objectLiteralTypeDeclarationStyle, the expected value is one of ${availableValues}`)
+      }
+    }
+  });
+}
 export { MarkdownTheme };

packages/typedoc-plugin-markdown/src/render-utils.ts

@@ -16,7 +16,7 @@ import ifShowReturnsHelper from './resources/helpers/if-show-returns';
 import ifShowTypeHierarchyHelper from './resources/helpers/if-show-type-hierarchy';
 import indexSignatureTitleHelper from './resources/helpers/index-signature-title';
 import parameterTableHelper from './resources/helpers/parameter-table';
-import propertyTableHelper from './resources/helpers/property-table';
+import objectLiteralMemberHelper from './resources/helpers/type-declaration-object-literal';
 import referenceMember from './resources/helpers/reference-member';
 import reflectionPathHelper from './resources/helpers/reflection-path';
 import reflectionTitleHelper from './resources/helpers/reflection-title';
@@ -71,7 +71,7 @@ export function registerHelpers(theme: MarkdownTheme) {
   ifShowTypeHierarchyHelper();
   indexSignatureTitleHelper();
   parameterTableHelper();
-  propertyTableHelper();
+  objectLiteralMemberHelper(theme);
   referenceMember();
   reflectionPathHelper();
   reflectionTitleHelper(theme);

packages/typedoc-plugin-markdown/src/resources/helpers/type-declaration-object-literal.ts

@@ -0,0 +1,198 @@
+import * as Handlebars from 'handlebars';
+import { DeclarationReflection, ReflectionType } from 'typedoc';
+import { escapeChars, stripLineBreaks } from '../../utils';
+import { MarkdownTheme } from "../../theme";
+
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper(
+    'typeDeclarationMembers',
+    function (this: DeclarationReflection[]) {
+      const comments = this.map(
+        (param) => !!param.comment?.hasVisibleComponent(),
+      );
+      const hasComments = !comments.every((value) => !value);
+
+      const flattenParams = (current: any) => {
+        return current.type?.declaration?.children?.reduce(
+          (acc: any, child: any) => {
+            const childObj = {
+              ...child,
+              name: `${current.name}.${child.name}`,
+            };
+            return parseParams(childObj, acc);
+          },
+          [],
+        );
+      };
+
+      const parseParams = (current: any, acc: any) => {
+        const shouldFlatten = current.type?.declaration?.children;
+
+        return shouldFlatten
+          ? [...acc, current, ...flattenParams(current)]
+          : [...acc, current];
+      };
+
+      const properties = this.reduce(
+        (acc: any, current: any) => parseParams(current, acc),
+        [],
+      );
+
+      let result = "";
+      switch (theme.objectLiteralTypeDeclarationStyle){
+        case "list": {
+          result = getListMarkdownContent(properties);
+          break;
+        }
+          case "table": {
+            result = getTableMarkdownContent(properties, hasComments);
+            break;
+          }
+        }
+      return result;
+    },
+  );
+}
+
+function getListMarkdownContent(properties: DeclarationReflection[]) {
+  const propertyTable = getTableMarkdownContentWithoutComment(properties);
+  const propertyDescriptions = properties.map((property) => {
+    const name = property.name.match(/[\\`\\|]/g) !== null
+      ? escapeChars(getName(property))
+      : `${getName(property)}`;
+
+    const propertyType = getPropertyType(property);
+    const propertyTypeStr = Handlebars.helpers.type
+      .call(propertyType);
+
+    const comments = getComments(property);
+    const commentsStr = comments ? Handlebars.helpers.comments(comments) : "\\-";
+
+    const md = (
+`**${name}**: ${propertyTypeStr}
+
+${commentsStr}
+
+-----
+
+
+`)
+
+    return md;
+  });
+
+  const propertyComments = propertyDescriptions.join("\n\n");
+
+  const result = 
+`
+${propertyTable}
+
+${propertyComments}
+
+`
+
+  return result;
+}
+
+function getTableMarkdownContent(properties: DeclarationReflection[], hasComments: boolean,) {
+
+  const headers = ['Name', 'Type'];
+
+  if (hasComments) {
+    headers.push('Description');
+  }
+  const rows = properties.map((property) => {
+    const propertyType = getPropertyType(property);
+    const row: string[] = [];
+    const nameCol: string[] = [];
+    const name =
+      property.name.match(/[\\`\\|]/g) !== null
+        ? escapeChars(getName(property))
+        : `\`${getName(property)}\``;
+    nameCol.push(name);
+    row.push(nameCol.join(' '));
+    row.push(
+      Handlebars.helpers.type
+        .call(propertyType)
+        .replace(/(?<!\\)\|/g, '\\|'),
+    );
+
+    if (hasComments) {
+      const comments = getComments(property);
+      if (comments) {
+        row.push(
+          stripLineBreaks(Handlebars.helpers.comments(comments)).replace(
+            /\|/g,
+            '\\|',
+          ),
+        );
+      } else {
+        row.push('-');
+      }
+    }
+    return `| ${row.join(' | ')} |\n`;
+  });
+
+  const output = `\n| ${headers.join(' | ')} |\n| ${headers
+    .map(() => ':------')
+    .join(' | ')} |\n${rows.join('')}`;
+  return output;
+}
+
+
+function getTableMarkdownContentWithoutComment(properties: DeclarationReflection[]){
+
+  const result = getTableMarkdownContent(properties, false);
+  return result;
+}
+
+function getPropertyType(property: any) {
+  if (property.getSignature) {
+    return property.getSignature.type;
+  }
+  if (property.setSignature) {
+    return property.setSignature.type;
+  }
+  return property.type ? property.type : property;
+}
+
+function getName(property: DeclarationReflection) {
+  const md: string[] = [];
+  if (property.flags.isRest) {
+    md.push('...');
+  }
+  if (property.getSignature) {
+    md.push(`get ${property.getSignature.name}()`);
+  } else if (property.setSignature) {
+    md.push(
+      `set ${
+        property.setSignature.name
+      }(${property.setSignature.parameters?.map((parameter) => {
+        return `${parameter.name}:${Handlebars.helpers.type.call(
+          parameter.type,
+          'all',
+          false,
+        )}`;
+      })})`,
+    );
+  } else {
+    md.push(property.name);
+  }
+  if (property.flags.isOptional) {
+    md.push('?');
+  }
+  return md.join('');
+}
+
+function getComments(property: DeclarationReflection) {
+  if (property.type instanceof ReflectionType) {
+    if (property.type?.declaration?.signatures) {
+      return property.type?.declaration.signatures[0].comment;
+    }
+  }
+  if (property.signatures) {
+    return property.signatures[0].comment;
+  }
+  return property.comment;
+}

packages/typedoc-plugin-markdown/src/resources/partials/member.declaration.hbs

@@ -60,7 +60,7 @@
 
 {{#with type.declaration.children}}
 
-{{{propertyTable}}}
+{{{typeDeclarationMembers}}}
 
 {{/with}}
 

packages/typedoc-plugin-markdown/src/resources/partials/member.signature.hbs

@@ -84,7 +84,7 @@
 
 {{#with declaration.children}}
 
-{{{propertyTable}}}
+{{{typeDeclarationMembers}}}
 
 {{/with}}