@cparra/apexdocs 2.25.0-alpha.0 → 2.25.0-alpha.1

package/src/adapters/apex-types.ts

@@ -1,67 +1,224 @@
 import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
-import { BaseTypeSource, ClassSource, EnumSource, InterfaceSource } from '../templating/types';
+import {
+  RenderableType,
+  RenderableClass,
+  RenderableEnum,
+  RenderableInterface,
+  Renderable,
+  RenderableSection,
+  GroupedMember,
+} from '../core/renderable/types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { linkFromTypeNameGenerator } from './references';
-import { FieldMirrorWithInheritance } from '../model/inheritance';
+import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
+import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
 import { adaptConstructor, adaptMethod } from './methods-and-constructors';
-import { adaptField } from './fields-and-properties';
+import { adaptFieldOrProperty } from './fields-and-properties';
 
-function baseTypeAdapter(type: EnumMirror | InterfaceMirror | ClassMirror): BaseTypeSource {
-  function extractAnnotationBody(type: Type, annotationName: string): string | undefined {
-    return type.docComment?.annotations.find(
-      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
-    )?.body;
-  }
+function baseTypeAdapter(
+  type: EnumMirror | InterfaceMirror | ClassMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableType {
+  function getHeading(type: Type): string {
+    const suffixMap = {
+      class: 'Class',
+      interface: 'Interface',
+      enum: 'Enum',
+    };
 
-  function extractSeeAnnotations(type: Type): string[] {
-    return (
-      type.docComment?.annotations
-        .filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === 'see')
-        .map((currentAnnotation) => currentAnnotation.body) ?? []
-    );
+    return `${type.name} ${suffixMap[type.type_name]}`;
   }
 
   return {
-    ...adaptDocumentable(type),
-    accessModifier: type.access_modifier,
+    headingLevel: baseHeadingLevel,
+    heading: getHeading(type),
+    doc: adaptDocumentable(type, linkGenerator, baseHeadingLevel + 1),
     name: type.name,
-    group: extractAnnotationBody(type, 'group'),
-    author: extractAnnotationBody(type, 'author'),
-    date: extractAnnotationBody(type, 'date'),
-    sees: extractSeeAnnotations(type).map(linkFromTypeNameGenerator),
+    meta: {
+      accessModifier: type.access_modifier,
+    },
+  };
+}
+
+export function typeToRenderableType(
+  type: Type,
+  linkGenerator: GetRenderableContentByTypeName,
+  namespace?: string,
+): Renderable {
+  function getRenderable() {
+    switch (type.type_name) {
+      case 'enum':
+        return enumTypeToEnumSource(type as EnumMirror, linkGenerator);
+      case 'interface':
+        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator);
+      case 'class':
+        return classTypeToClassSource(type as ClassMirror, linkGenerator);
+    }
+  }
+
+  return {
+    ...getRenderable(),
+    namespace,
   };
 }
 
-export function enumTypeToEnumSource(enumType: EnumMirror): EnumSource {
+export function enumTypeToEnumSource(
+  enumType: EnumMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableEnum {
   return {
-    __type: 'enum',
-    ...baseTypeAdapter(enumType),
-    values: enumType.values.map((value) => ({
-      ...adaptDescribable(value.docComment?.descriptionLines),
-      value: value.name,
-    })),
+    type: 'enum',
+    ...baseTypeAdapter(enumType, linkGenerator, baseHeadingLevel),
+    values: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Values',
+      value: enumType.values.map((value) => ({
+        ...adaptDescribable(value.docComment?.descriptionLines, linkGenerator),
+        value: value.name,
+      })),
+    },
   };
 }
 
-export function interfaceTypeToInterfaceSource(interfaceType: InterfaceMirror): InterfaceSource {
+export function interfaceTypeToInterfaceSource(
+  interfaceType: InterfaceMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableInterface {
   return {
-    __type: 'interface',
-    ...baseTypeAdapter(interfaceType),
+    type: 'interface',
+    ...baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel),
     extends: interfaceType.extended_interfaces.map(linkFromTypeNameGenerator),
-    methods: interfaceType.methods.map(adaptMethod),
+    methods: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Methods',
+      value: interfaceType.methods.map((method) => adaptMethod(method, linkGenerator, baseHeadingLevel + 2)),
+    },
   };
 }
 
-export function classTypeToClassSource(classType: ClassMirror): ClassSource {
+export function classTypeToClassSource(
+  classType: ClassMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableClass {
   return {
-    __type: 'class',
-    ...baseTypeAdapter(classType),
+    type: 'class',
+    ...baseTypeAdapter(classType, linkGenerator, baseHeadingLevel),
     classModifier: classType.classModifier,
     sharingModifier: classType.sharingModifier,
     implements: classType.implemented_interfaces.map(linkFromTypeNameGenerator),
     extends: classType.extended_class ? linkFromTypeNameGenerator(classType.extended_class) : undefined,
-    methods: classType.methods.map(adaptMethod),
-    constructors: classType.constructors.map((constructor) => adaptConstructor(classType.name, constructor)),
-    fields: classType.fields.map((field) => adaptField(field as FieldMirrorWithInheritance)),
+    methods: adaptMembers('Methods', classType.methods, adaptMethod, linkFromTypeNameGenerator, baseHeadingLevel + 1),
+    constructors: adaptMembers(
+      'Constructors',
+      classType.constructors,
+      (constructor, linkGenerator, baseHeadingLevel) =>
+        adaptConstructor(classType.name, constructor, linkGenerator, baseHeadingLevel),
+      linkFromTypeNameGenerator,
+      baseHeadingLevel + 1,
+    ),
+    fields: adaptMembers(
+      'Fields',
+      classType.fields as FieldMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkFromTypeNameGenerator,
+      baseHeadingLevel + 1,
+    ),
+    properties: adaptMembers(
+      'Properties',
+      classType.properties as PropertyMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkFromTypeNameGenerator,
+      baseHeadingLevel + 1,
+    ),
+    innerClasses: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Classes',
+      value: classType.classes.map((innerClass) =>
+        classTypeToClassSource(innerClass, linkGenerator, baseHeadingLevel + 2),
+      ),
+    },
+    innerEnums: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Enums',
+      value: classType.enums.map((innerEnum) => enumTypeToEnumSource(innerEnum, linkGenerator, baseHeadingLevel + 2)),
+    },
+    innerInterfaces: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Interfaces',
+      value: classType.interfaces.map((innerInterface) =>
+        interfaceTypeToInterfaceSource(innerInterface, linkGenerator, baseHeadingLevel + 2),
+      ),
+    },
+  };
+}
+
+type Groupable = { group?: string; groupDescription?: string };
+
+function adaptMembers<T extends Groupable, K>(
+  heading: string,
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkFromTypeNameGenerator: GetRenderableContentByTypeName,
+  headingLevel: number,
+): RenderableSection<K[] | GroupedMember<K>[]> & { isGrouped: boolean } {
+  return {
+    headingLevel,
+    heading,
+    isGrouped: hasGroup(members),
+    value: hasGroup(members)
+      ? toGroupedMembers(members, adapter, linkFromTypeNameGenerator, headingLevel + 1)
+      : toFlat(members, adapter, linkFromTypeNameGenerator, headingLevel + 1),
+  };
+}
+
+function hasGroup(members: Groupable[]): boolean {
+  return members.some((member) => member.group);
+}
+
+function toFlat<T extends Groupable, K>(
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): K[] {
+  return members.map((member) => adapter(member, linkGenerator, baseHeadingLevel));
+}
+
+function toGroupedMembers<T extends Groupable, K>(
+  members: T[],
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): GroupedMember<K>[] {
+  const groupedMembers = groupByGroupName(members);
+  return Object.entries(groupedMembers).map(([groupName, members]) =>
+    singleGroup(baseHeadingLevel, groupName, adapter, members, linkGenerator),
+  );
+}
+
+function groupByGroupName<T extends Groupable>(members: T[]): Record<string, T[]> {
+  return members.reduce((acc, member) => {
+    const groupName = member.group ?? 'Other';
+    acc[groupName] = acc[groupName] ?? [];
+    acc[groupName].push(member);
+    return acc;
+  }, {} as Record<string, T[]>);
+}
+
+function singleGroup<T extends Groupable, K>(
+  headingLevel: number,
+  groupName: string,
+  adapter: (member: T, linkGenerator: GetRenderableContentByTypeName, baseHeadingLevel: number) => K,
+  members: T[],
+  linkGenerator: GetRenderableContentByTypeName,
+): GroupedMember<K> {
+  return {
+    headingLevel: headingLevel,
+    heading: groupName,
+    groupDescription: members[0].groupDescription, // All fields in the group have the same description
+    value: toFlat(members, adapter, linkGenerator, headingLevel + 1),
   };
 }

package/src/adapters/documentables.ts

@@ -1,9 +1,14 @@
-import { CustomTag, DocumentableSource, RenderableContent } from '../templating/types';
+import { CustomTag, RenderableDocumentation, RenderableContent } from '../core/renderable/types';
 import { Describable, Documentable } from './types';
-import { replaceInlineReferences } from './references';
+import { GetRenderableContentByTypeName, replaceInlineReferences } from './references';
 import { isEmptyLine } from './type-utils';
 
-export function adaptDescribable(describable: Describable): { description?: RenderableContent[] } {
+export function adaptDescribable(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): {
+  description?: RenderableContent[];
+} {
   function describableToRenderableContent(describable: Describable): RenderableContent[] | undefined {
     if (!describable) {
       return;
@@ -12,7 +17,7 @@ export function adaptDescribable(describable: Describable): { description?: Rend
     return (
       describable
         .map<RenderableContent[]>((line) => [
-          ...replaceInlineReferences(line),
+          ...replaceInlineReferences(line, linkGenerator),
           {
             type: 'empty-line',
           },
@@ -28,7 +33,11 @@ export function adaptDescribable(describable: Describable): { description?: Rend
   };
 }
 
-export function adaptDocumentable(documentable: Documentable): DocumentableSource {
+export function adaptDocumentable(
+  documentable: Documentable,
+  linkGenerator: GetRenderableContentByTypeName,
+  subHeadingLevel: number,
+): RenderableDocumentation {
   function extractCustomTags(type: Documentable): CustomTag[] {
     const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'mermaid', 'throws', 'exception'];
 
@@ -36,7 +45,7 @@ export function adaptDocumentable(documentable: Documentable): DocumentableSourc
       type.docComment?.annotations
         .filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase()))
         .map<CustomTag>((currentAnnotation) => ({
-          ...adaptDescribable(currentAnnotation.bodyLines),
+          ...adaptDescribable(currentAnnotation.bodyLines, linkGenerator),
           name: currentAnnotation.name,
         })) ?? []
     );
@@ -48,11 +57,37 @@ export function adaptDocumentable(documentable: Documentable): DocumentableSourc
     )?.bodyLines;
   }
 
+  function extractAnnotationBody(type: Documentable, annotationName: string): string | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.body;
+  }
+
+  function extractSeeAnnotations(type: Documentable): string[] {
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === 'see')
+        .map((currentAnnotation) => currentAnnotation.body) ?? []
+    );
+  }
+
   return {
-    ...adaptDescribable(documentable.docComment?.descriptionLines),
+    ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
     customTags: extractCustomTags(documentable),
-    mermaid: extractAnnotationBodyLines(documentable, 'mermaid'),
-    example: documentable.docComment?.exampleAnnotation?.bodyLines,
+    mermaid: {
+      headingLevel: subHeadingLevel,
+      heading: 'Diagram',
+      value: extractAnnotationBodyLines(documentable, 'mermaid'),
+    },
+    example: {
+      headingLevel: subHeadingLevel,
+      heading: 'Example',
+      value: documentable.docComment?.exampleAnnotation?.bodyLines,
+    },
+    group: extractAnnotationBody(documentable, 'group'),
+    author: extractAnnotationBody(documentable, 'author'),
+    date: extractAnnotationBody(documentable, 'date'),
+    sees: extractSeeAnnotations(documentable).map(linkGenerator),
   };
 }

package/src/adapters/fields-and-properties.ts

@@ -1,14 +1,38 @@
-import { FieldMirrorWithInheritance } from '../model/inheritance';
-import { FieldSource } from '../templating/types';
+import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
+import { RenderableField } from '../core/renderable/types';
 import { adaptDocumentable } from './documentables';
-import { linkFromTypeNameGenerator } from './references';
+import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
+
+export function adaptFieldOrProperty(
+  field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableField {
+  function buildSignature() {
+    const { access_modifier, name } = field;
+    const memberModifiers = field.memberModifiers.join(' ');
+    return (
+      `${access_modifier} ${memberModifiers} ${name}`
+        // remove double spaces
+        .replace(/ {2}/g, ' ')
+    );
+  }
 
-export function adaptField(field: FieldMirrorWithInheritance): FieldSource {
   return {
-    ...adaptDocumentable(field),
-    name: field.name,
-    type: linkFromTypeNameGenerator(field.typeReference.rawDeclaration),
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(field, linkGenerator, baseHeadingLevel + 1),
+    heading: field.name,
+    type: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Type',
+      value: linkFromTypeNameGenerator(field.typeReference.rawDeclaration),
+    },
     inherited: field.inherited,
     accessModifier: field.access_modifier,
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: [buildSignature()],
+    },
   };
 }

package/src/adapters/methods-and-constructors.ts

@@ -1,11 +1,15 @@
 import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
-import { ConstructorSource, MethodSource } from '../templating/types';
+import { RenderableConstructor, RenderableMethod } from '../core/renderable/types';
 import { MethodMirrorWithInheritance } from '../model/inheritance';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { linkFromTypeNameGenerator } from './references';
+import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
 import { Documentable } from './types';
 
-export function adaptMethod(method: MethodMirror): MethodSource {
+export function adaptMethod(
+  method: MethodMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableMethod {
   function buildTitle(method: MethodMirrorWithInheritance): string {
     const { name, parameters } = method;
     const parametersString = parameters.map((param) => param.name).join(', ');
@@ -22,20 +26,42 @@ export function adaptMethod(method: MethodMirror): MethodSource {
   }
 
   return {
-    ...adaptDocumentable(method),
-    title: buildTitle(method as MethodMirrorWithInheritance),
-    signature: buildSignature(method as MethodMirrorWithInheritance),
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(method, linkGenerator, baseHeadingLevel + 1),
+    heading: buildTitle(method as MethodMirrorWithInheritance),
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: [buildSignature(method as MethodMirrorWithInheritance)],
+    },
     returnType: {
-      ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines),
-      type: linkFromTypeNameGenerator(method.typeReference.rawDeclaration),
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Return Type',
+      value: {
+        ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines, linkGenerator),
+        type: linkFromTypeNameGenerator(method.typeReference.rawDeclaration),
+      },
+    },
+    throws: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Throws',
+      value: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    },
+    parameters: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Parameters',
+      value: method.parameters.map((param) => mapParameters(method, param)),
     },
-    throws: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
-    parameters: method.parameters.map((param) => mapParameters(method, param)),
     inherited: (method as MethodMirrorWithInheritance).inherited,
   };
 }
 
-export function adaptConstructor(typeName: string, constructor: ConstructorMirror): ConstructorSource {
+export function adaptConstructor(
+  typeName: string,
+  constructor: ConstructorMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableConstructor {
   function buildTitle(name: string, constructor: ConstructorMirror): string {
     const { parameters } = constructor;
     const parametersString = parameters.map((param) => param.name).join(', ');
@@ -51,11 +77,24 @@ export function adaptConstructor(typeName: string, constructor: ConstructorMirro
   }
 
   return {
-    ...adaptDocumentable(constructor),
-    title: buildTitle(typeName, constructor),
-    signature: buildSignature(typeName, constructor),
-    parameters: constructor.parameters.map((param) => mapParameters(constructor, param)),
-    throws: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    doc: adaptDocumentable(constructor, linkGenerator, baseHeadingLevel + 1),
+    headingLevel: baseHeadingLevel,
+    heading: buildTitle(typeName, constructor),
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: [buildSignature(typeName, constructor)],
+    },
+    parameters: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Parameters',
+      value: constructor.parameters.map((param) => mapParameters(constructor, param)),
+    },
+    throws: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Throws',
+      value: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    },
   };
 }
 
@@ -64,7 +103,7 @@ function mapParameters(documentable: Documentable, param: ParameterMirror) {
     (pa) => pa.paramName.toLowerCase() === param.name.toLowerCase(),
   );
   return {
-    ...adaptDescribable(paramAnnotation?.bodyLines),
+    ...adaptDescribable(paramAnnotation?.bodyLines, linkFromTypeNameGenerator),
     name: param.name,
     type: linkFromTypeNameGenerator(param.typeReference.rawDeclaration),
   };
@@ -72,7 +111,7 @@ function mapParameters(documentable: Documentable, param: ParameterMirror) {
 
 function mapThrows(thrown: ThrowsAnnotation) {
   return {
-    ...adaptDescribable(thrown.bodyLines),
+    ...adaptDescribable(thrown.bodyLines, linkFromTypeNameGenerator),
     type: linkFromTypeNameGenerator(thrown.exceptionName),
   };
 }

package/src/adapters/references.ts

@@ -1,5 +1,5 @@
 import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
-import { Link, RenderableContent, StringOrLink } from '../templating/types';
+import { Link, RenderableContent, StringOrLink } from '../core/renderable/types';
 
 export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
 

package/src/adapters/type-utils.ts

@@ -1,4 +1,4 @@
-import { EmptyLine, RenderableContent } from '../templating/types';
+import { EmptyLine, RenderableContent } from '../core/renderable/types';
 
 export function isEmptyLine(content: RenderableContent): content is EmptyLine {
   return Object.keys(content).includes('type') && (content as { type: string }).type === 'empty-line';