@cparra/apexdocs 2.25.0 → 3.0.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,
+    linkingStrategy: 'relative',
+    ...config,
+  });
+}

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,
+  linkingStrategy: 'relative',
+};
+
+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/core/markdown/adapters/__tests__/link-generator.spec.ts

@@ -0,0 +1,130 @@
+import { generateLink } from '../generate-link';
+
+describe('Generates links', () => {
+  describe('relative', () => {
+    it('generates relative links from the base when found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns a relative path when linking from a file', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+        from: {
+          referencePath: 'b/fromPath',
+          displayName: 'fromName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: '../a/referencePath',
+      });
+    });
+
+    it('returns the display name when the from reference is not found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('no-link', () => {
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns the display name of the reference when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('none', () => {
+    it('returns the path as is when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+  });
+});

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

@@ -0,0 +1,136 @@
+import { replaceInlineReferences } from '../inline';
+import { Link } from '../types';
+
+function getFileLink(typeName: string): Link {
+  return {
+    __type: 'link' as const,
+    title: typeName,
+    url: `/api/${typeName}.html`,
+  };
+}
+
+function getEmailLink(typeName: string) {
+  return {
+    __type: 'link' as const,
+    title: typeName,
+    url: `mailto:${typeName}`,
+  };
+}
+
+describe('reference utilities', () => {
+  it('returns a RenderableContent array with the full string when there are no links', () => {
+    const text = 'This is a test';
+    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+    const expected = ['This is a test'];
+
+    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>>.';
+      const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+      const expected = [
+        'This is a test ',
+        {
+          __type: 'link',
+          title: 'ClassName',
+          url: '/api/ClassName.html',
+        },
+        '.',
+      ];
+
+      expect(result).toEqual(expected);
+    });
+    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`,
+        };
+      }
+
+      const text = 'This is a test {@link ClassName}';
+      const result = replaceInlineReferences(text, getFileLinkByTypeName, getEmailLink);
+
+      const expected = [
+        'This is a test ',
+        {
+          __type: 'link',
+          title: 'ClassName',
+          url: '/api/ClassName.html',
+        },
+      ];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
+  describe('replace inline emails', () => {
+    it('replaces emails in the format of {@email email-address}', () => {
+      function getLinkByTypeName(typeName: string) {
+        return {
+          __type: 'link' as const,
+          title: typeName,
+          url: `mailto:${typeName}`,
+        };
+      }
+
+      const text = 'This is an email {@email example@example.com}';
+      const result = replaceInlineReferences(text, getFileLink, getLinkByTypeName);
+
+      const expected = [
+        'This is an email ',
+        {
+          __type: 'link',
+          title: 'example@example.com',
+          url: 'mailto:example@example.com',
+        },
+      ];
+
+      expect(result).toEqual(expected);
+    });
+  });
+
+  it('replaces both links and emails in the same string', () => {
+    const text = 'This is a test <<ClassName>>, and {@link AnotherClass}, and an email {@email testerson}';
+    const result = replaceInlineReferences(text, getFileLink, getEmailLink);
+
+    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',
+      },
+    ];
+
+    expect(result).toEqual(expected);
+  });
+});