@cparra/apexdocs 2.25.0-alpha.2 → 2.25.0-alpha.4

package/src/cli/generate.ts

@@ -1,140 +1,14 @@
 #!/usr/bin/env node
-import * as yargs from 'yargs';
-
-import { Settings } from '../settings';
 import { Apexdocs } from '../application/Apexdocs';
-import { GeneratorChoices } from '../transpiler/generator-choices';
-import { cosmiconfig } from 'cosmiconfig';
-
-const result = cosmiconfig('apexdocs').search();
-result.then((config) => {
-  yargs.config(config?.config);
-  let argv = yargs
-    .options({
-      sourceDir: {
-        type: 'string',
-        alias: 's',
-        demandOption: true,
-        describe: 'The directory location which contains your apex .cls classes.',
-      },
-      targetDir: {
-        type: 'string',
-        alias: 't',
-        default: './docs/',
-        describe: 'The directory location where documentation will be generated to.',
-      },
-      recursive: {
-        type: 'boolean',
-        alias: 'r',
-        default: true,
-        describe: 'Whether .cls classes will be searched for recursively in the directory provided.',
-      },
-      scope: {
-        type: 'string',
-        array: true,
-        alias: 'p',
-        default: ['global'],
-        describe:
-          'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
-          'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. ' +
-          'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
-      },
-      targetGenerator: {
-        type: 'string',
-        alias: 'g',
-        default: 'jekyll',
-        choices: ['jekyll', 'docsify', 'plain-markdown', 'openapi'],
-        describe:
-          'Define the static file generator for which the documents will be created. ' +
-          'Currently supports jekyll, docsify, plain markdown, and OpenAPI v3.1.0.',
-      },
-      indexOnly: {
-        type: 'boolean',
-        default: false,
-        describe: 'Defines whether only the index file should be generated.',
-      },
-      defaultGroupName: {
-        type: 'string',
-        default: 'Miscellaneous',
-        describe: 'Defines the @group name to be used when a file does not specify it.',
-      },
-      sanitizeHtml: {
-        type: 'boolean',
-        default: true,
-        describe:
-          'When on, any special character within your ApexDocs is converted into its HTML code representation. ' +
-          'This is specially useful when generic objects are described within the docs, e.g. "List< Foo>", "Map<Foo, Bar>" ' +
-          'because otherwise the content within < and > would be treated as HTML tags and not shown in the output. ' +
-          'Content in @example blocks are never sanitized.',
-      },
-      openApiTitle: {
-        type: 'string',
-        default: 'Apex REST Api',
-        describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
-      },
-      title: {
-        type: 'string',
-        describe: "If this allows you to specify the title of the generated documentation's home file.",
-        default: 'Classes',
-      },
-      namespace: {
-        type: 'string',
-        describe:
-          'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
-          "If generating an OpenApi definition, it will be added to the file's Server Url.",
-      },
-      openApiFileName: {
-        type: 'string',
-        describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-        default: 'openapi',
-      },
-      sortMembersAlphabetically: {
-        type: 'boolean',
-        describe: 'Whether to sort members alphabetically.',
-        default: false,
-      },
-      includeMetadata: {
-        type: 'boolean',
-        describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-        default: false,
-      },
-      documentationRootDir: {
-        type: 'string',
-        describe:
-          'Allows you to specify the root documentation directory where the files are being generated. This can be helpful when embedding the generated docs into an existing site so that the links are generated correctly.',
-      },
-    })
-    .parseSync();
-
-  if (config) {
-    argv = { ...config.config, ...argv };
-  }
-
-  Settings.build({
-    sourceDirectory: argv.sourceDir,
-    recursive: argv.recursive,
-    scope: argv.scope,
-    outputDir: argv.targetDir,
-    targetGenerator: argv.targetGenerator as GeneratorChoices,
-    indexOnly: argv.indexOnly,
-    defaultGroupName: argv.defaultGroupName,
-    sanitizeHtml: argv.sanitizeHtml,
-    openApiTitle: argv.openApiTitle,
-    title: argv.title,
-    namespace: argv.namespace,
-    openApiFileName: argv.openApiFileName,
-    sortMembersAlphabetically: argv.sortMembersAlphabetically,
-    includeMetadata: argv.includeMetadata,
-    rootDir: argv.documentationRootDir,
-    onAfterProcess: config?.config?.onAfterProcess,
-    onBeforeFileWrite: config?.config?.onBeforeFileWrite,
-    frontMatterHeader: config?.config?.frontMatterHeader,
-  });
-
-  try {
-    Apexdocs.generate();
-  } catch (error) {
-    console.error(error);
-    process.exit(1);
-  }
-});
+import { extractArgs } from './args';
+
+function main() {
+  extractArgs()
+    .then((config) => Apexdocs.generate(config))
+    .catch((error) => {
+      console.error(error);
+      process.exit(1);
+    });
+}
+
+main();

package/src/core/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/{adapters → core/adapters}/__tests__/interface-adapter.spec.ts

@@ -1,7 +1,7 @@
-import { InterfaceMirrorBuilder } from '../../test-helpers/InterfaceMirrorBuilder';
-import { AnnotationBuilder } from '../../test-helpers/AnnotationBuilder';
-import { MethodMirrorBuilder, ParameterBuilder } from '../../test-helpers/MethodMirrorBuilder';
-import { interfaceTypeToInterfaceSource } from '../apex-types';
+import { typeToRenderable } from '../apex-types';
+import { InterfaceMirrorBuilder } from '../../../test-helpers/InterfaceMirrorBuilder';
+import { AnnotationBuilder } from '../../../test-helpers/AnnotationBuilder';
+import { MethodMirrorBuilder, ParameterBuilder } from '../../../test-helpers/MethodMirrorBuilder';
 
 function linkGenerator(type: string): string {
   return type;
@@ -10,14 +10,14 @@ function linkGenerator(type: string): string {
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {
   it('converts the name', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.name).toBe('SampleInterface');
   });
 
   it('converts the access modifier', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.meta.accessModifier).toBe('public');
   });
@@ -26,7 +26,7 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
     const interfaceMirror = new InterfaceMirrorBuilder()
       .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
       .build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.doc.annotations).toEqual(['MYANNOTATION']);
   });
@@ -44,10 +44,10 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.methods.value).toHaveLength(1);
-    expect(interfaceSource.methods.value[0].signature.value[0]).toBe('public String sampleMethod()');
+    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe('public String sampleMethod()');
   });
 
   it('converts method declarations. Method with parameters', () => {
@@ -72,9 +72,11 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
+    const interfaceSource = typeToRenderable(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.methods.value).toHaveLength(1);
-    expect(interfaceSource.methods.value[0].signature.value[0]).toBe('public String sampleMethod(String param1)');
+    expect(interfaceSource.methods.value[0].signature.value.content[0]).toBe(
+      'public String sampleMethod(String param1)',
+    );
   });
 });

package/src/{adapters → core/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/adapters}/apex-types.ts

@@ -4,38 +4,41 @@ import {
   RenderableClass,
   RenderableEnum,
   RenderableInterface,
-  Renderable,
   RenderableSection,
   GroupedMember,
-} from '../core/renderable/types';
-import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
-import {
   ClassMirrorWithInheritanceChain,
   FieldMirrorWithInheritance,
   PropertyMirrorWithInheritance,
-} from '../model/inheritance';
+  GetRenderableContentByTypeName,
+} from './types';
+import { adaptDescribable, adaptDocumentable } from './documentables';
 import { adaptConstructor, adaptMethod } from './methods-and-constructors';
 import { adaptFieldOrProperty } from './fields-and-properties';
 
-export function typeToRenderableType(
-  type: Type,
+type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
+  ? RenderableInterface
+  : T extends ClassMirror
+    ? RenderableClass
+    : RenderableEnum;
+
+export function typeToRenderable<T extends Type>(
+  type: T,
   linkGenerator: GetRenderableContentByTypeName,
   namespace?: string,
-): Renderable {
-  function getRenderable() {
+): GetReturnRenderable<T> {
+  function getRenderable(): RenderableInterface | RenderableClass | RenderableEnum {
     switch (type.type_name) {
       case 'enum':
-        return enumTypeToEnumSource(type as EnumMirror, linkGenerator);
+        return enumTypeToEnumSource(type as EnumMirror, linkGenerator) as RenderableEnum;
       case 'interface':
-        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator);
+        return interfaceTypeToInterfaceSource(type as InterfaceMirror, linkGenerator) as RenderableInterface;
       case 'class':
-        return classTypeToClassSource(type as ClassMirrorWithInheritanceChain, linkGenerator);
+        return classTypeToClassSource(type as ClassMirrorWithInheritanceChain, linkGenerator) as RenderableClass;
     }
   }
 
   return {
-    ...getRenderable(),
+    ...(getRenderable() as GetReturnRenderable<T>),
     namespace,
   };
 }
@@ -85,7 +88,7 @@ function enumTypeToEnumSource(
   };
 }
 
-export function interfaceTypeToInterfaceSource(
+function interfaceTypeToInterfaceSource(
   interfaceType: InterfaceMirror,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number = 1,

package/src/{adapters → core/adapters}/documentables.ts

@@ -1,6 +1,6 @@
-import { CustomTag, RenderableDocumentation, RenderableContent } from '../core/renderable/types';
-import { Describable, Documentable } from './types';
-import { GetRenderableContentByTypeName, replaceInlineReferences } from './references';
+import { CustomTag, RenderableDocumentation, RenderableContent, CodeBlock } from './types';
+import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
+import { replaceInlineReferences } from './inline';
 import { isEmptyLine } from './type-utils';
 
 export function adaptDescribable(
@@ -14,15 +14,46 @@ export function adaptDescribable(
       return;
     }
 
-    return (
-      describable
-        .map<RenderableContent[]>((line) => [
-          ...replaceInlineReferences(line, linkGenerator),
+    let content: RenderableContent[] = [];
+    for (let i = 0; i < describable.length; i++) {
+      const line = describable[i];
+      // The language might or might not be present after ```
+      const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
+      if (codeBlockMatch) {
+        // Check if the language is present, if not, fallback to "apex"
+        const language = codeBlockMatch[1] || 'apex';
+        const codeBlockLines: string[] = [];
+        i++;
+        while (i < describable.length) {
+          const currentLine = describable[i];
+          if (currentLine.trim() === '```') {
+            break;
+          }
+          codeBlockLines.push(currentLine);
+          i++;
+        }
+        content = [
+          ...content,
           {
-            type: 'empty-line',
+            __type: 'code-block',
+            language,
+            content: codeBlockLines,
           },
-        ])
-        .flatMap((line) => line)
+          { __type: 'empty-line' },
+        ];
+        continue;
+      }
+
+      content = [
+        ...content,
+        ...replaceInlineReferences(line, linkGenerator),
+        {
+          __type: 'empty-line',
+        },
+      ];
+    }
+    return (
+      content
         // If the last element is an empty line, remove it
         .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
     );
@@ -71,6 +102,17 @@ export function adaptDocumentable(
     );
   }
 
+  function bodyLinesToCodeBlock(language: string, bodyLines: string[] | undefined): CodeBlock | undefined {
+    if (!bodyLines) {
+      return;
+    }
+    return {
+      __type: 'code-block',
+      language,
+      content: bodyLines,
+    };
+  }
+
   return {
     ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
@@ -78,12 +120,12 @@ export function adaptDocumentable(
     mermaid: {
       headingLevel: subHeadingLevel,
       heading: 'Diagram',
-      value: extractAnnotationBodyLines(documentable, 'mermaid'),
+      value: bodyLinesToCodeBlock('mermaid', extractAnnotationBodyLines(documentable, 'mermaid')),
     },
     example: {
       headingLevel: subHeadingLevel,
       heading: 'Example',
-      value: documentable.docComment?.exampleAnnotation?.bodyLines,
+      value: bodyLinesToCodeBlock('apex', documentable.docComment?.exampleAnnotation?.bodyLines),
     },
     group: extractAnnotationBody(documentable, 'group'),
     author: extractAnnotationBody(documentable, 'author'),

package/src/{adapters → core/adapters}/fields-and-properties.ts

@@ -1,21 +1,28 @@
-import { FieldMirrorWithInheritance, PropertyMirrorWithInheritance } from '../model/inheritance';
-import { RenderableField } from '../core/renderable/types';
+import {
+  CodeBlock,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  RenderableField,
+  GetRenderableContentByTypeName,
+} from './types';
 import { adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 
 export function adaptFieldOrProperty(
   field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,
   linkGenerator: GetRenderableContentByTypeName,
   baseHeadingLevel: number,
 ): RenderableField {
-  function buildSignature() {
+  function buildSignature(): CodeBlock {
     const { access_modifier, name } = field;
     const memberModifiers = field.memberModifiers.join(' ');
-    return (
-      `${access_modifier} ${memberModifiers} ${name}`
-        // remove double spaces
-        .replace(/ {2}/g, ' ')
-    );
+    const codeContents = `${access_modifier} ${memberModifiers} ${name}`
+      // remove double spaces
+      .replace(/ {2}/g, ' ');
+    return {
+      __type: 'code-block',
+      language: 'apex',
+      content: [codeContents],
+    };
   }
 
   return {
@@ -32,7 +39,7 @@ export function adaptFieldOrProperty(
     signature: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Signature',
-      value: [buildSignature()],
+      value: buildSignature(),
     },
   };
 }