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

package/src/core/markdown/__test__/test-helpers.ts

@@ -0,0 +1,23 @@
+import { UnparsedSourceFile } from '../../shared/types';
+import { generateDocs as gen, MarkdownGeneratorConfig } from '../generate-docs';
+import { referenceGuideTemplate } from '../templates/reference-guide';
+
+export function apexBundleFromRawString(raw: string, rawMetadata?: string): UnparsedSourceFile {
+  return {
+    filePath: 'test.cls',
+    content: raw,
+    metadataContent: rawMetadata ?? null,
+  };
+}
+
+export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial<MarkdownGeneratorConfig>) {
+  return gen(apexBundles, {
+    targetDir: 'target',
+    scope: ['global', 'public'],
+    defaultGroupName: 'Miscellaneous',
+    sortMembersAlphabetically: true,
+    referenceGuideTemplate: referenceGuideTemplate,
+    ...config,
+    documentationRootDir: '',
+  });
+}

package/src/core/markdown/adapters/__tests__/documentables.spec.ts

@@ -0,0 +1,109 @@
+import { adaptDescribable } from '../documentables';
+
+function linkGenerator(typeName: string) {
+  return typeName;
+}
+
+describe('describable', () => {
+  it('returns undefined if describable is undefined', () => {
+    const result = adaptDescribable(undefined, linkGenerator);
+
+    expect(result).toEqual({
+      description: undefined,
+    });
+  });
+
+  it('returns an empty array if describable is an empty array', () => {
+    const result = adaptDescribable([], linkGenerator);
+
+    expect(result).toEqual({
+      description: [],
+    });
+  });
+
+  it('returns a string if describable contains a string', () => {
+    const describable = ['This is a test'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: ['This is a test'],
+    });
+  });
+
+  it('separates strings with an empty line', () => {
+    const describable = ['This is a test', 'This is another test'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: ['This is a test', { __type: 'empty-line' }, 'This is another test'],
+    });
+  });
+
+  it('returns a code block if describable contains code', () => {
+    const describable = ['```typescript', 'const a = 1;', '```'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'typescript',
+          content: ['const a = 1;'],
+        },
+      ],
+    });
+  });
+
+  it('sets the code blocks language to apex if one is not provided', () => {
+    const describable = ['```', 'const a = 1;', '```'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'apex',
+          content: ['const a = 1;'],
+        },
+      ],
+    });
+  });
+
+  it('returns a code block followed by an empty line and then whatever content is in the describable', () => {
+    const describable = ['```typescript', 'const a = 1;', '```', 'This is a test'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'typescript',
+          content: ['const a = 1;'],
+        },
+        { __type: 'empty-line' },
+        'This is a test',
+      ],
+    });
+  });
+
+  it('returns a code block even when there is no closing tag', () => {
+    const describable = ['```typescript', 'const a = 1;'];
+
+    const result = adaptDescribable(describable, linkGenerator);
+
+    expect(result).toEqual({
+      description: [
+        {
+          __type: 'code-block',
+          language: 'typescript',
+          content: ['const a = 1;'],
+        },
+      ],
+    });
+  });
+});

package/src/core/markdown/adapters/__tests__/interface-adapter.spec.ts

@@ -0,0 +1,148 @@
+import { typeToRenderable } from '../apex-types';
+import { InterfaceMirrorBuilder } from '../../../../test-helpers/InterfaceMirrorBuilder';
+import { AnnotationBuilder } from '../../../../test-helpers/AnnotationBuilder';
+import { MethodMirrorBuilder, ParameterBuilder } from '../../../../test-helpers/MethodMirrorBuilder';
+import { MarkdownGeneratorConfig } from '../../generate-docs';
+
+function linkGenerator(type: string): string {
+  return type;
+}
+
+const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
+  targetDir: '',
+  scope: ['global', 'public'],
+  namespace: '',
+  defaultGroupName: 'Miscellaneous',
+  referenceGuideTemplate: '',
+  sortMembersAlphabetically: false,
+  documentationRootDir: '',
+};
+
+describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {
+  it('converts the name', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
+    const interfaceSource = typeToRenderable(
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
+
+    expect(interfaceSource.name).toBe('SampleInterface');
+  });
+
+  it('converts the access modifier', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder().build();
+    const interfaceSource = typeToRenderable(
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
+
+    expect(interfaceSource.meta.accessModifier).toBe('public');
+  });
+
+  it('converts annotations', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder()
+      .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
+      .build();
+    const interfaceSource = typeToRenderable(
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
+
+    expect(interfaceSource.doc.annotations).toEqual(['MYANNOTATION']);
+  });
+
+  it('converts method declarations. Method with no parameters', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder()
+      .addMethod(
+        new MethodMirrorBuilder()
+          .withName('sampleMethod')
+          .withTypeReference({
+            type: 'String',
+            rawDeclaration: 'String',
+          })
+          .build(),
+      )
+      .build();
+
+    const interfaceSource = typeToRenderable(
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
+
+    expect(interfaceSource.methods.value).toHaveLength(1);
+    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe('public String sampleMethod()');
+  });
+
+  it('converts method declarations. Method with parameters', () => {
+    const interfaceMirror = new InterfaceMirrorBuilder()
+      .addMethod(
+        new MethodMirrorBuilder()
+          .withName('sampleMethod')
+          .withTypeReference({
+            type: 'String',
+            rawDeclaration: 'String',
+          })
+          .addParameter(
+            new ParameterBuilder()
+              .withName('param1')
+              .withTypeReference({
+                type: 'String',
+                rawDeclaration: 'String',
+              })
+              .build(),
+          )
+          .build(),
+      )
+      .build();
+
+    const interfaceSource = typeToRenderable(
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
+      linkGenerator,
+      defaultMarkdownGeneratorConfig,
+    );
+
+    expect(interfaceSource.methods.value).toHaveLength(1);
+    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe(
+      'public String sampleMethod(String param1)',
+    );
+  });
+});

package/src/{adapters → core/markdown/adapters}/__tests__/references.spec.ts

@@ -1,8 +1,9 @@
-import { replaceInlineReferences } from '../references';
-import { Link } from '../../templating/types';
+import { replaceInlineReferences } from '../inline';
+import { Link } from '../types';
 
 function getFileLink(typeName: string): Link {
   return {
+    __type: 'link' as const,
     title: typeName,
     url: `/api/${typeName}.html`,
   };
@@ -10,6 +11,7 @@ function getFileLink(typeName: string): Link {
 
 function getEmailLink(typeName: string) {
   return {
+    __type: 'link' as const,
     title: typeName,
     url: `mailto:${typeName}`,
   };
@@ -25,6 +27,17 @@ describe('reference utilities', () => {
     expect(result).toEqual(expected);
   });
 
+  describe('replace inline code', () => {
+    it('replaces inline code with InlineCode', () => {
+      const text = 'This is a test `ClassName`.';
+      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+      const expected = ['This is a test ', { __type: 'inline-code', content: 'ClassName' }, '.'];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
   describe('replace inline links', () => {
     it('replaces links in the format of <<ClassName>>', () => {
       const text = 'This is a test <<ClassName>>.';
@@ -33,6 +46,7 @@ describe('reference utilities', () => {
       const expected = [
         'This is a test ',
         {
+          __type: 'link',
           title: 'ClassName',
           url: '/api/ClassName.html',
         },
@@ -44,6 +58,7 @@ describe('reference utilities', () => {
     it('replaces links in the format of {@link ClassName}', () => {
       function getFileLinkByTypeName(typeName: string): Link {
         return {
+          __type: 'link' as const,
           title: typeName,
           url: `/api/${typeName}.html`,
         };
@@ -55,6 +70,7 @@ describe('reference utilities', () => {
       const expected = [
         'This is a test ',
         {
+          __type: 'link',
           title: 'ClassName',
           url: '/api/ClassName.html',
         },
@@ -68,6 +84,7 @@ describe('reference utilities', () => {
     it('replaces emails in the format of {@email email-address}', () => {
       function getLinkByTypeName(typeName: string) {
         return {
+          __type: 'link' as const,
           title: typeName,
           url: `mailto:${typeName}`,
         };
@@ -79,6 +96,7 @@ describe('reference utilities', () => {
       const expected = [
         'This is an email ',
         {
+          __type: 'link',
           title: 'example@example.com',
           url: 'mailto:example@example.com',
         },
@@ -95,16 +113,19 @@ describe('reference utilities', () => {
     const expected = [
       'This is a test ',
       {
+        __type: 'link',
         title: 'ClassName',
         url: '/api/ClassName.html',
       },
       ', and ',
       {
+        __type: 'link',
         title: 'AnotherClass',
         url: '/api/AnotherClass.html',
       },
       ', and an email ',
       {
+        __type: 'link',
         title: 'testerson',
         url: 'mailto:testerson',
       },

package/src/core/markdown/adapters/apex-types.ts

@@ -0,0 +1,238 @@
+import { ClassMirror, EnumMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import {
+  RenderableType,
+  RenderableClass,
+  RenderableEnum,
+  RenderableInterface,
+  RenderableSection,
+  GroupedMember,
+  ClassMirrorWithInheritanceChain,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  GetRenderableContentByTypeName,
+} from './types';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { adaptConstructor, adaptMethod } from './methods-and-constructors';
+import { adaptFieldOrProperty } from './fields-and-properties';
+import { MarkdownGeneratorConfig } from '../generate-docs';
+import { SourceFileMetadata } from '../../shared/types';
+
+type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
+  ? RenderableInterface
+  : T extends ClassMirror
+    ? RenderableClass
+    : RenderableEnum;
+
+export function typeToRenderable<T extends Type>(
+  parsedFile: { source: SourceFileMetadata; type: T },
+  linkGenerator: GetRenderableContentByTypeName,
+  config: MarkdownGeneratorConfig,
+): GetReturnRenderable<T> & { filePath: string; namespace?: string } {
+  function getRenderable(): RenderableInterface | RenderableClass | RenderableEnum {
+    const { type } = parsedFile;
+    switch (type.type_name) {
+      case 'enum':
+        return enumTypeToEnumSource(type as EnumMirror, linkGenerator) as RenderableEnum;
+      case 'interface':
+        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator) as RenderableInterface;
+      case 'class':
+        return classTypeToClassSource(type as ClassMirrorWithInheritanceChain, linkGenerator) as RenderableClass;
+    }
+  }
+
+  return {
+    ...(getRenderable() as GetReturnRenderable<T>),
+    filePath: parsedFile.source.filePath,
+    namespace: config.namespace,
+  };
+}
+
+function baseTypeAdapter(
+  type: EnumMirror | InterfaceMirror | ClassMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableType {
+  function getHeading(type: Type): string {
+    const suffixMap = {
+      class: 'Class',
+      interface: 'Interface',
+      enum: 'Enum',
+    };
+
+    return `${type.name} ${suffixMap[type.type_name]}`;
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    heading: getHeading(type),
+    doc: adaptDocumentable(type, linkGenerator, baseHeadingLevel + 1),
+    name: type.name,
+    meta: {
+      accessModifier: type.access_modifier,
+    },
+  };
+}
+
+function enumTypeToEnumSource(
+  enumType: EnumMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableEnum {
+  return {
+    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,
+      })),
+    },
+  };
+}
+
+function interfaceTypeToInterfaceSource(
+  interfaceType: InterfaceMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableInterface {
+  return {
+    type: 'interface',
+    ...baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel),
+    extends: interfaceType.extended_interfaces.map(linkGenerator),
+    methods: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Methods',
+      value: interfaceType.methods.map((method) => adaptMethod(method, linkGenerator, baseHeadingLevel + 2)),
+    },
+  };
+}
+
+function classTypeToClassSource(
+  classType: ClassMirrorWithInheritanceChain,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number = 1,
+): RenderableClass {
+  return {
+    type: 'class',
+    ...baseTypeAdapter(classType, linkGenerator, baseHeadingLevel),
+    classModifier: classType.classModifier,
+    sharingModifier: classType.sharingModifier,
+    implements: classType.implemented_interfaces.map(linkGenerator),
+    extends: classType.inheritanceChain.map(linkGenerator),
+    methods: adaptMembers('Methods', classType.methods, adaptMethod, linkGenerator, baseHeadingLevel + 1),
+    constructors: adaptMembers(
+      'Constructors',
+      classType.constructors,
+      (constructor, linkGenerator, baseHeadingLevel) =>
+        adaptConstructor(classType.name, constructor, linkGenerator, baseHeadingLevel),
+      linkGenerator,
+      baseHeadingLevel + 1,
+    ),
+    fields: adaptMembers(
+      'Fields',
+      classType.fields as FieldMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkGenerator,
+      baseHeadingLevel + 1,
+    ),
+    properties: adaptMembers(
+      'Properties',
+      classType.properties as PropertyMirrorWithInheritance[],
+      adaptFieldOrProperty,
+      linkGenerator,
+      baseHeadingLevel + 1,
+    ),
+    innerClasses: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Classes',
+      value: classType.classes.map((innerClass) =>
+        classTypeToClassSource({ ...innerClass, inheritanceChain: [] }, 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),
+  };
+}