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

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/core/adapters/__tests__/references.spec.ts

@@ -1,4 +1,4 @@
-import { replaceInlineReferences } from '../references';
+import { replaceInlineReferences } from '../inline';
 import { Link } from '../types';
 
 function getFileLink(typeName: string): Link {
@@ -27,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>>.';

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

@@ -9,9 +9,9 @@ import {
   ClassMirrorWithInheritanceChain,
   FieldMirrorWithInheritance,
   PropertyMirrorWithInheritance,
+  GetRenderableContentByTypeName,
 } from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 import { adaptConstructor, adaptMethod } from './methods-and-constructors';
 import { adaptFieldOrProperty } from './fields-and-properties';
 

package/src/core/adapters/documentables.ts

@@ -1,6 +1,6 @@
 import { CustomTag, RenderableDocumentation, RenderableContent, CodeBlock } from './types';
-import { Describable, Documentable } from './types';
-import { GetRenderableContentByTypeName, replaceInlineReferences } from './references';
+import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
+import { replaceInlineReferences } from './inline';
 import { isEmptyLine } from './type-utils';
 
 export function adaptDescribable(
@@ -32,7 +32,6 @@ export function adaptDescribable(
           codeBlockLines.push(currentLine);
           i++;
         }
-        console.log('codeBlockLines', codeBlockLines);
         content = [
           ...content,
           {
@@ -55,68 +54,9 @@ export function adaptDescribable(
     }
     return (
       content
-        .flatMap((line) => line)
         // If the last element is an empty line, remove it
         .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
     );
-
-    // TODO: Now we want to also extract code blocks if we encounter any line that starts with "```"
-
-    // return describable.reduce<RenderableContent[]>(
-    //   (acc, line) => {
-    //     if (line.trim() === '') {
-    //       return [...acc, { __type: 'empty-line' }];
-    //     }
-    //
-    //     // The language might or might not be present after ```
-    //     const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
-    //     if (codeBlockMatch) {
-    //       console.log('codeBlockMatch', codeBlockMatch);
-    //       // Check if the language is present, if not, fallback to "apex"
-    //       const language = codeBlockMatch[1] || 'apex';
-    //       const codeBlockLines: string[] = [];
-    //       let index = acc.length + 1;
-    //       while (index < describable.length) {
-    //         const currentLine = describable[index];
-    //         if (currentLine.trim() === '```') {
-    //           break;
-    //         }
-    //         codeBlockLines.push(currentLine);
-    //         index++;
-    //       }
-    //       return [
-    //         ...acc,
-    //         {
-    //           __type: 'code-block',
-    //           language,
-    //           content: codeBlockLines,
-    //         },
-    //       ];
-    //     }
-    //
-    //     return [
-    //       ...acc,
-    //       ...replaceInlineReferences(line, linkGenerator),
-    //       {
-    //         __type: 'empty-line',
-    //       },
-    //     ];
-    //   },
-    //   <RenderableContent[]>[],
-    // );
-
-    // return (
-    //   describable
-    //     .map<RenderableContent[]>((line) => [
-    //       ...replaceInlineReferences(line, linkGenerator),
-    //       {
-    //         __type: 'empty-line',
-    //       },
-    //     ])
-    //     .flatMap((line) => line)
-    //     // If the last element is an empty line, remove it
-    //     .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
-    // );
   }
 
   return {

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

@@ -1,6 +1,11 @@
-import { CodeBlock, FieldMirrorWithInheritance, PropertyMirrorWithInheritance, RenderableField } from './types';
+import {
+  CodeBlock,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  RenderableField,
+  GetRenderableContentByTypeName,
+} from './types';
 import { adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 
 export function adaptFieldOrProperty(
   field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,

package/src/core/adapters/{references.ts → inline.ts}

@@ -1,6 +1,10 @@
-import { Link, RenderableContent, StringOrLink } from './types';
+import { InlineCode, Link, RenderableContent } from './types';
+import { pipe } from 'fp-ts/function';
+import { apply } from '../../util/fp';
 
-export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+type InlineRenderableContent = InlineCode | Link | string;
+
+type ToInlineRenderableContent = (typeName: string) => InlineRenderableContent;
 
 function defaultGetEmailByReference(email: string): Link {
   return {
@@ -12,22 +16,51 @@ function defaultGetEmailByReference(email: string): Link {
 
 export function replaceInlineReferences(
   text: string,
-  linkReplacer: GetRenderableContentByTypeName,
-  emailReplacer: GetRenderableContentByTypeName = defaultGetEmailByReference,
+  linkReplacer: ToInlineRenderableContent,
+  emailReplacer: ToInlineRenderableContent = defaultGetEmailByReference,
 ): RenderableContent[] {
-  return replaceInlineEmails(replaceInlineLinks([text], linkReplacer), emailReplacer);
+  const inlineLinks = apply(replaceInlineLinks, linkReplacer);
+  const inlineEmails = apply(replaceInlineEmails, emailReplacer);
+
+  return pipe(inlineCode([text]), inlineLinks, inlineEmails);
+}
+
+function inlineCode(renderableContents: RenderableContent[]): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineCodeContent(renderableContent));
+}
+
+// Replace string that is inline code with InlineCode
+// Inline code is any text that backticks surround
+function inlineCodeContent(renderableContent: RenderableContent): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  function inlineCodeLink(text: string): InlineCode {
+    return {
+      __type: 'inline-code',
+      content: text,
+    };
+  }
+
+  const text = renderableContent;
+
+  // Matches any text surrounded by backticks
+  const codeFormatRegEx = '`([^`]*)`';
+  const matches = match(codeFormatRegEx, text);
+  return createRenderableContents(matches, text, inlineCodeLink);
 }
 
 function replaceInlineLinks(
+  getLinkByTypeName: ToInlineRenderableContent,
   renderableContents: RenderableContent[],
-  getLinkByTypeName: GetRenderableContentByTypeName,
 ): RenderableContent[] {
   return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
 }
 
 function inlineLinkContent(
   renderableContent: RenderableContent,
-  getLinkByTypeName: GetRenderableContentByTypeName,
+  getLinkByTypeName: ToInlineRenderableContent,
 ): RenderableContent[] {
   if (typeof renderableContent !== 'string') {
     return [renderableContent];
@@ -42,15 +75,15 @@ function inlineLinkContent(
 }
 
 export function replaceInlineEmails(
+  getLinkByTypeName: ToInlineRenderableContent,
   renderableContents: RenderableContent[],
-  getLinkByTypeName: GetRenderableContentByTypeName,
 ): RenderableContent[] {
   return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
 }
 
 function inlineEmailContent(
   renderableContent: RenderableContent,
-  getLinkByTypeName: GetRenderableContentByTypeName,
+  getLinkByTypeName: ToInlineRenderableContent,
 ): RenderableContent[] {
   if (typeof renderableContent !== 'string') {
     return [renderableContent];
@@ -79,7 +112,7 @@ function match(regex: string, text: string) {
   return matches;
 }
 
-function createRenderableContents(matches: RegExpExecArray[], text: string, linker: GetRenderableContentByTypeName) {
+function createRenderableContents(matches: RegExpExecArray[], text: string, linker: ToInlineRenderableContent) {
   if (matches.length === 0) {
     return [text];
   }

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

@@ -1,7 +1,12 @@
 import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
-import { RenderableConstructor, RenderableMethod, MethodMirrorWithInheritance, CodeBlock } from './types';
+import {
+  RenderableConstructor,
+  RenderableMethod,
+  MethodMirrorWithInheritance,
+  CodeBlock,
+  GetRenderableContentByTypeName,
+} from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName } from './references';
 import { Documentable } from './types';
 
 export function adaptMethod(

package/src/core/adapters/type-utils.ts

@@ -1,4 +1,4 @@
-import { CodeBlock, EmptyLine, RenderableContent } from './types';
+import { CodeBlock, EmptyLine, InlineCode, RenderableContent } from './types';
 
 export function isEmptyLine(content: RenderableContent): content is EmptyLine {
   return Object.keys(content).includes('__type') && (content as { __type: string }).__type === 'empty-line';
@@ -7,3 +7,7 @@ export function isEmptyLine(content: RenderableContent): content is EmptyLine {
 export function isCodeBlock(content: RenderableContent): content is CodeBlock {
   return Object.keys(content).includes('__type') && (content as { __type: string }).__type === 'code-block';
 }
+
+export function isInlineCode(content: RenderableContent): content is InlineCode {
+  return Object.keys(content).includes('__type') && (content as { __type: string }).__type === 'inline-code';
+}

package/src/core/adapters/types.d.ts

@@ -36,7 +36,9 @@ export type EmptyLine = {
 
 export type StringOrLink = string | Link;
 
-export type RenderableContent = StringOrLink | EmptyLine | CodeBlock;
+export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+
+export type RenderableContent = StringOrLink | EmptyLine | CodeBlock | InlineCode;
 
 type EnumValue = {
   value: string;
@@ -59,6 +61,11 @@ type CodeBlock = {
   content: string[];
 };
 
+type InlineCode = {
+  readonly __type: 'inline-code';
+  content: string;
+};
+
 type RenderableDocumentation = {
   annotations?: Annotation[];
   description?: RenderableContent[];

package/src/core/template.ts

@@ -8,7 +8,7 @@ import { classMarkdownTemplate } from '../transpiler/markdown/plain-markdown/cla
 import { enumMarkdownTemplate } from '../transpiler/markdown/plain-markdown/enum-template';
 import { interfaceMarkdownTemplate } from '../transpiler/markdown/plain-markdown/interface-template';
 import { CodeBlock, RenderableContent, StringOrLink } from './adapters/types';
-import { isCodeBlock, isEmptyLine } from './adapters/type-utils';
+import { isCodeBlock, isEmptyLine, isInlineCode } from './adapters/type-utils';
 import { groupedMembersPartialTemplate } from '../transpiler/markdown/plain-markdown/grouped-members-partial-template';
 
 export type CompilationRequest = {
@@ -94,6 +94,9 @@ const resolveRenderableContent = (description?: RenderableContent[]): string =>
     }
     if (isCodeBlock(curr)) {
       return acc + convertCodeBlock(curr) + '\n';
+    }
+    if (isInlineCode(curr)) {
+      return acc + inlineCode(curr.content).toString() + ' ';
     } else {
       return acc + Handlebars.escapeExpression(link(curr)).trim() + ' ';
     }

package/src/service/apex-file-reader.ts

@@ -17,7 +17,7 @@ export class ApexFileReader {
     const directoryContents = fileSystem.readDirectory(rootPath);
     directoryContents.forEach((currentFilePath) => {
       const currentPath = fileSystem.joinPath(rootPath, currentFilePath);
-      if (this.readRecursively && fileSystem.isDirectory(currentPath)) {
+      if (fileSystem.isDirectory(currentPath)) {
         bundles = bundles.concat(this.processFiles(fileSystem, currentPath));
       }
 
@@ -44,8 +44,4 @@ export class ApexFileReader {
   private static get sourceDirectory() {
     return Settings.getInstance().sourceDirectory;
   }
-
-  private static get readRecursively() {
-    return Settings.getInstance().recursive;
-  }
 }

package/src/settings.ts

@@ -24,13 +24,11 @@ export type TargetType = {
 
 export interface SettingsConfig {
   sourceDirectory: string;
-  recursive: boolean;
   scope: string[];
   outputDir: string;
   targetGenerator: GeneratorChoices;
   indexOnly: boolean;
   defaultGroupName: string;
-  sanitizeHtml: boolean;
   openApiTitle?: string;
   title: string;
   namespace?: string;
@@ -64,10 +62,6 @@ export class Settings {
     return this.config.sourceDirectory;
   }
 
-  get recursive(): boolean {
-    return this.config.recursive;
-  }
-
   get scope(): string[] {
     return this.config.scope;
   }
@@ -84,10 +78,6 @@ export class Settings {
     return this.config.indexOnly;
   }
 
-  get sanitizeHtml(): boolean {
-    return this.config.sanitizeHtml;
-  }
-
   public getDefaultGroupName(): string {
     return this.config.defaultGroupName;
   }

package/src/test-helpers/SettingsBuilder.ts

@@ -8,13 +8,11 @@ export class SettingsBuilder {
   build(): SettingsConfig {
     return {
       sourceDirectory: './',
-      recursive: true,
       scope: [],
       outputDir: './',
       targetGenerator: 'openapi',
       indexOnly: false,
       defaultGroupName: 'Misc',
-      sanitizeHtml: true,
       openApiTitle: 'Apex API',
       openApiFileName: 'openapi',
       title: 'Classes',

package/src/transpiler/markdown/plain-markdown/constructors-partial-template.ts

@@ -13,7 +13,7 @@ export const constructorsPartialTemplate = `
 | Name | Type | Description |
 |------|------|-------------|
 {{#each parameters.value}}
-| {{name}} | {{type}} | {{description}} |
+| {{name}} | {{link type}} | {{description}} |
 {{/each}}
 {{/if}}
 

package/src/util/fp.ts

@@ -0,0 +1,3 @@
+export function apply<T extends unknown[], U extends unknown[], R>(fn: (...args: [...T, ...U]) => R, ...front: T) {
+  return (...tailArgs: U) => fn(...front, ...tailArgs);
+}

package/dist/__spec__/core/expect-extensions.d.ts

@@ -1,3 +0,0 @@
-import * as E from 'fp-ts/Either';
-export declare function extendExpect(): void;
-export declare function assertEither<T, U>(result: E.Either<T, U>, assertion: (data: U) => void): void;

package/dist/__spec__/core/expect-extensions.js

@@ -1,55 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertEither = exports.extendExpect = void 0;
-const E = __importStar(require("fp-ts/Either"));
-function extendExpect() {
-    expect.extend({
-        documentationBundleHasLength(received, length) {
-            return {
-                pass: E.isRight(received) && received.right.docs.length === length,
-                message: () => `Expected documentation bundle to have length ${length}`,
-            };
-        },
-        firstDocContains(doc, content) {
-            return {
-                pass: doc.docs[0].docContents.includes(content),
-                message: () => `Expected documentation to contain ${content}. Got ${doc.docs[0].docContents}`,
-            };
-        },
-        firstDocContainsNot(doc, content) {
-            return {
-                pass: !doc.docs[0].docContents.includes(content),
-                message: () => `Expected documentation to not contain ${content}. Got ${doc.docs[0].docContents}`,
-            };
-        },
-    });
-}
-exports.extendExpect = extendExpect;
-function assertEither(result, assertion) {
-    E.match((error) => fail(error), (data) => assertion(data))(result);
-}
-exports.assertEither = assertEither;
-//# sourceMappingURL=expect-extensions.js.map

package/dist/__spec__/core/expect-extensions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"expect-extensions.js","sourceRoot":"","sources":["../../../src/__spec__/core/expect-extensions.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAkC;AAGlC,SAAgB,YAAY;IAC1B,MAAM,CAAC,MAAM,CAAC;QACZ,4BAA4B,CAAC,QAAiD,EAAE,MAAc;YAC5F,OAAO;gBACL,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM;gBAClE,OAAO,EAAE,GAAG,EAAE,CAAC,gDAAgD,MAAM,EAAE;aACxE,CAAC;QACJ,CAAC;QACD,gBAAgB,CAAC,GAAwB,EAAE,OAAe;YACxD,OAAO;gBACL,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAC/C,OAAO,EAAE,GAAG,EAAE,CAAC,qCAAqC,OAAO,SAAS,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;aAC9F,CAAC;QACJ,CAAC;QACD,mBAAmB,CAAC,GAAwB,EAAE,OAAe;YAC3D,OAAO;gBACL,IAAI,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAChD,OAAO,EAAE,GAAG,EAAE,CAAC,yCAAyC,OAAO,SAAS,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE;aAClG,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AArBD,oCAqBC;AAED,SAAgB,YAAY,CAAO,MAAsB,EAAE,SAA4B;IACrF,CAAC,CAAC,KAAK,CACL,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EACtB,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAC1B,CAAC,MAAM,CAAC,CAAC;AACZ,CAAC;AALD,oCAKC"}

package/dist/__spec__/core/generating-class-docs.spec.d.ts

@@ -1 +0,0 @@
-export {};