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

package/src/core/markdown/__test__/inheritance-chain.test.ts

@@ -0,0 +1,54 @@
+import { ClassMirrorBuilder } from '../../../test-helpers/ClassMirrorBuilder';
+import { createInheritanceChain } from '../reflection/inheritance-chain';
+
+describe('inheritance chain for classes', () => {
+  test('returns an empty list of the class does not extend any other class', () => {
+    const classMirror = new ClassMirrorBuilder().build();
+    const repository = [classMirror];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual([]);
+  });
+
+  test('returns the name of the extended class if it is not found in the repository', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const repository = [classMirror];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass']);
+  });
+
+  test('returns the extended class when it is present in the repository', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').build();
+    const repository = [classMirror, extendedClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass']);
+  });
+
+  test('returns the full inheritance chain when the extended class is also extended', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').withExtendedClass('SuperClass').build();
+    const superClass = new ClassMirrorBuilder().withName('SuperClass').build();
+    const repository = [classMirror, extendedClass, superClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass', 'SuperClass']);
+  });
+
+  test('returns the inheritance for a class that extends an inner class', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('OuterClass.InnerClass').build();
+    const innerClass = new ClassMirrorBuilder().withName('InnerClass').build();
+    const outerClass = new ClassMirrorBuilder().withName('OuterClass').addInnerClass(innerClass).build();
+    const repository = [classMirror, outerClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['OuterClass.InnerClass']);
+  });
+});

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 '../../core/renderable/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/{adapters → core/markdown/adapters}/apex-types.ts

@@ -4,15 +4,48 @@ import {
   RenderableClass,
   RenderableEnum,
   RenderableInterface,
-  Renderable,
   RenderableSection,
   GroupedMember,
-} from '../core/renderable/types';
+  ClassMirrorWithInheritanceChain,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  GetRenderableContentByTypeName,
+} from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
-import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
 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,
@@ -40,29 +73,7 @@ function baseTypeAdapter(
   };
 }
 
-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(
+function enumTypeToEnumSource(
   enumType: EnumMirror,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,
@@ -81,7 +92,7 @@ export function enumTypeToEnumSource(
   };
 }
 
-export function interfaceTypeToInterfaceSource(
+function interfaceTypeToInterfaceSource(
   interfaceType: InterfaceMirror,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,
@@ -89,7 +100,7 @@ export function interfaceTypeToInterfaceSource(
   return {
     type: 'interface',
     ...baseTypeAdapter(interfaceType, linkGenerator, baseHeadingLevel),
-    extends: interfaceType.extended_interfaces.map(linkFromTypeNameGenerator),
+    extends: interfaceType.extended_interfaces.map(linkGenerator),
     methods: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Methods',
@@ -98,8 +109,8 @@ export function interfaceTypeToInterfaceSource(
   };
 }
 
-export function classTypeToClassSource(
-  classType: ClassMirror,
+function classTypeToClassSource(
+  classType: ClassMirrorWithInheritanceChain,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,
 ): RenderableClass {
@@ -108,36 +119,36 @@ export function classTypeToClassSource(
     ...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: adaptMembers('Methods', classType.methods, adaptMethod, linkFromTypeNameGenerator, baseHeadingLevel + 1),
+    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),
-      linkFromTypeNameGenerator,
+      linkGenerator,
       baseHeadingLevel + 1,
     ),
     fields: adaptMembers(
       'Fields',
       classType.fields as FieldMirrorWithInheritance[],
       adaptFieldOrProperty,
-      linkFromTypeNameGenerator,
+      linkGenerator,
       baseHeadingLevel + 1,
     ),
     properties: adaptMembers(
       'Properties',
       classType.properties as PropertyMirrorWithInheritance[],
       adaptFieldOrProperty,
-      linkFromTypeNameGenerator,
+      linkGenerator,
       baseHeadingLevel + 1,
     ),
     innerClasses: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Classes',
       value: classType.classes.map((innerClass) =>
-        classTypeToClassSource(innerClass, linkGenerator, baseHeadingLevel + 2),
+        classTypeToClassSource({ ...innerClass, inheritanceChain: [] }, linkGenerator, baseHeadingLevel + 2),
       ),
     },
     innerEnums: {
@@ -200,12 +211,15 @@ function toGroupedMembers<T extends Groupable, K>(
 }
 
 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[]>);
+  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>(