@cparra/apexdocs 3.24.0-beta.3 → 3.24.0

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var errorCollector = require('../error-collector-D5Q2hGFS.js');
+var errorCollector = require('../error-collector-DagrtuR3.js');
 var cosmiconfig = require('cosmiconfig');
 var yargs = require('yargs');
 var E = require('fp-ts/Either');

package/dist/{error-collector-D5Q2hGFS.js → error-collector-DagrtuR3.js}

@@ -140,6 +140,7 @@ const defaultTranslations = {
       author: "Author",
       date: "Date",
       see: "See",
+      deprecated: "Deprecated",
       possibleValues: "Possible values are",
       parameters: "Parameters",
       throws: "Throws",
@@ -236,7 +237,28 @@ function defaultGetEmailByReference(email) {
 function replaceInlineReferences(text, linkReplacer, emailReplacer = defaultGetEmailByReference) {
   const inlineLinks = apply(replaceInlineLinks, linkReplacer);
   const inlineEmails = apply(replaceInlineEmails, emailReplacer);
-  return _function.pipe(inlineCode$1([text]), inlineLinks, inlineEmails);
+  return _function.pipe(inlineCodeTags([text]), inlineLiteralTags, inlineCode$1, inlineLinks, inlineEmails);
+}
+function inlineCodeTags(renderableContents) {
+  return renderableContents.flatMap((renderableContent) => {
+    if (typeof renderableContent !== "string") {
+      return [renderableContent];
+    }
+    const matches = match("{@code (.*?)}", renderableContent);
+    return createRenderableContents(matches, renderableContent, (content) => ({
+      __type: "inline-code",
+      content: content.trim()
+    }));
+  });
+}
+function inlineLiteralTags(renderableContents) {
+  return renderableContents.flatMap((renderableContent) => {
+    if (typeof renderableContent !== "string") {
+      return [renderableContent];
+    }
+    const matches = match("{@literal (.*?)}", renderableContent);
+    return createRenderableContents(matches, renderableContent, (content) => content.trim());
+  });
 }
 function inlineCode$1(renderableContents) {
   return renderableContents.flatMap((renderableContent) => inlineCodeContent(renderableContent));
@@ -394,7 +416,7 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
   var _a, _b, _c;
   function extractCustomTags(type) {
     var _a2, _b2;
-    const baseTags = ["description", "group", "author", "date", "see", "example", "throws", "exception"];
+    const baseTags = ["description", "group", "author", "date", "see", "example", "throws", "exception", "deprecated"];
     return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase())).map((currentAnnotation) => __spreadProps$p(__spreadValues$r({}, adaptDescribable(currentAnnotation.bodyLines, linkGenerator)), {
       name: currentAnnotation.name
     }))) != null ? _b2 : [];
@@ -405,10 +427,23 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
       (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName
     )) == null ? void 0 : _b2.body;
   }
-  function extractSeeAnnotations(type) {
+  function extractAnnotationBodies(type, annotationName) {
     var _a2, _b2;
-    return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === "see").map((currentAnnotation) => currentAnnotation.body)) != null ? _b2 : [];
+    return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName).map((currentAnnotation) => currentAnnotation.body)) != null ? _b2 : [];
+  }
+  function extractDeprecated(type) {
+    var _a2;
+    const deprecatedAnnotation = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === "deprecated"
+    );
+    if (!deprecatedAnnotation) {
+      return void 0;
+    }
+    return {
+      description: describableToRenderableContent(deprecatedAnnotation.bodyLines, linkGenerator)
+    };
   }
+  const authors = extractAnnotationBodies(documentable, "author");
   return __spreadProps$p(__spreadValues$r({}, adaptDescribable((_a = documentable.docComment) == null ? void 0 : _a.descriptionLines, linkGenerator)), {
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
     customTags: extractCustomTags(documentable),
@@ -418,9 +453,11 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
       value: describableToRenderableContent((_c = (_b = documentable.docComment) == null ? void 0 : _b.exampleAnnotation) == null ? void 0 : _c.bodyLines, linkGenerator)
     },
     group: extractAnnotationBody(documentable, "group"),
-    author: extractAnnotationBody(documentable, "author"),
+    author: authors[0],
+    authors,
     date: extractAnnotationBody(documentable, "date"),
-    sees: extractSeeAnnotations(documentable).map(linkGenerator)
+    sees: extractAnnotationBodies(documentable, "see").map(linkGenerator),
+    deprecated: extractDeprecated(documentable)
   });
 }
 
@@ -789,6 +826,10 @@ function classTypeToClassSource(classType, linkGenerator, baseHeadingLevel = 1,
     }
   });
 }
+function getGroupName(member) {
+  var _a, _b, _c;
+  return (_c = member.group) != null ? _c : (_b = (_a = member.docComment) == null ? void 0 : _a.annotations.find((annotation) => annotation.name.toLowerCase() === "group")) == null ? void 0 : _b.body;
+}
 function adaptMembers(heading, members, adapter, linkFromTypeNameGenerator, headingLevel, translations) {
   return {
     headingLevel,
@@ -798,7 +839,7 @@ function adaptMembers(heading, members, adapter, linkFromTypeNameGenerator, head
   };
 }
 function hasGroup(members) {
-  return members.some((member) => member.group);
+  return members.some((member) => getGroupName(member));
 }
 function toFlat(members, adapter, linkGenerator, baseHeadingLevel, translations) {
   return members.map((member) => adapter(member, linkGenerator, baseHeadingLevel, translations));
@@ -813,7 +854,7 @@ function groupByGroupName(members) {
   return members.reduce(
     (acc, member) => {
       var _a, _b;
-      const groupName = (_a = member.group) != null ? _a : "Other";
+      const groupName = (_a = getGroupName(member)) != null ? _a : "Other";
       acc[groupName] = (_b = acc[groupName]) != null ? _b : [];
       acc[groupName].push(member);
       return acc;
@@ -1002,6 +1043,10 @@ function renderInlineHelpText(inlineHelpText, config) {
 }
 
 const generateLink = (strategy) => {
+  const resolveTypeName = getStrategyFn(strategy);
+  return (references, from, referenceName) => resolveReference(resolveTypeName, references, from, referenceName);
+};
+const getStrategyFn = (strategy) => {
   switch (strategy) {
     case "relative":
       return generateRelativeLink;
@@ -1011,6 +1056,43 @@ const generateLink = (strategy) => {
       return returnReferenceAsIs;
   }
 };
+function resolveReference(resolveTypeName, references, from, referenceName) {
+  const reference = referenceName.trim();
+  const quotedText = reference.match(/^"([\s\S]*)"$/);
+  if (quotedText) {
+    return quotedText[1];
+  }
+  const htmlAnchor = reference.match(/^<a\s+href="([^"]*)"[^>]*>([\s\S]*?)<\/a>$/i);
+  if (htmlAnchor) {
+    return {
+      __type: "link",
+      title: htmlAnchor[2].trim(),
+      url: htmlAnchor[1]
+    };
+  }
+  const memberReference = reference.match(/^([\w.]*)#([\w.]+(?:\([^)]*\))?)$/);
+  if (memberReference) {
+    const [, typeName, member] = memberReference;
+    const anchor = member.toLowerCase().replace(/[^a-z0-9_-]/g, "");
+    if (!typeName) {
+      return {
+        __type: "link",
+        title: member,
+        url: `#${anchor}`
+      };
+    }
+    const resolvedType = resolveTypeName(references, from, typeName);
+    if (typeof resolvedType === "string") {
+      return reference;
+    }
+    return {
+      __type: "link",
+      title: `${resolvedType.title}.${member}`,
+      url: `${resolvedType.url}#${anchor}`
+    };
+  }
+  return resolveTypeName(references, from, reference);
+}
 const generateRelativeLink = (references, from, referenceName) => {
   function getRelativePath(fromPath, toPath) {
     return path.relative(path.parse(path.join("/", fromPath)).dir, path.join("/", toPath));
@@ -1775,10 +1857,21 @@ const typeDocPartial = `
 **{{@root.translations.markdown.details.group}}** {{doc.group}}
 {{/if}}
 
-{{#if doc.author}}
-**{{@root.translations.markdown.details.author}}** {{doc.author}}
+{{> docDetailsPartial}}
+
+{{#if namespace}}
+## {{@root.translations.markdown.sections.namespace}}
+{{namespace}}
 {{/if}}
 
+{{/documentablePartialTemplate}}
+`.trim();
+
+const docDetailsPartial = `
+{{#each doc.authors}}
+**{{@root.translations.markdown.details.author}}** {{this}}
+
+{{/each}}
 {{#if doc.date}}
 **{{@root.translations.markdown.details.date}}** {{doc.date}}
 {{/if}}
@@ -1787,13 +1880,6 @@ const typeDocPartial = `
 **{{@root.translations.markdown.details.see}}** {{link this}}
 
 {{/each}}
-
-{{#if namespace}}
-## {{@root.translations.markdown.sections.namespace}}
-{{namespace}}
-{{/if}}
-
-{{/documentablePartialTemplate}}
 `.trim();
 
 const documentablePartialTemplate = `
@@ -1801,6 +1887,10 @@ const documentablePartialTemplate = `
 \`{{this}}\`
 {{/each}}
 
+{{#if doc.deprecated}}
+> **{{@root.translations.markdown.details.deprecated}}** {{{renderContent doc.deprecated.description}}}
+{{/if}}
+
 {{{renderContent doc.description}}}
 
 {{#each doc.customTags}}
@@ -1850,16 +1940,18 @@ const methodsPartialTemplate = `
 **{{link returnType.value.type}}**
 
 {{#if returnType.value.description}}
-{{returnType.value.description}}
+{{{renderContent returnType.value.description}}}
 {{/if}}
 
 {{#if throws.value}}
 {{ heading throws.headingLevel throws.heading }}
 {{#each throws.value}}
-{{link this.type}}: {{this.description}}
+{{link this.type}}: {{{renderContent this.description}}}
 
 {{/each}}
 {{/if}}
+
+{{> docDetailsPartial}}
 {{/documentablePartialTemplate}}
 
 {{#unless @last}}---{{/unless}}
@@ -1889,17 +1981,19 @@ const constructorsPartialTemplate = `
 | Name | Type | Description |
 |------|------|-------------|
 {{#each parameters.value}}
-| {{name}} | {{link type}} | {{description}} |
+| {{name}} | {{link type}} | {{{renderContent description}}} |
 {{/each}}
 {{/if}}
 
 {{#if throws.value}}
 {{ heading throws.headingLevel throws.heading }}
 {{#each throws.value}}
-{{link this.type}}: {{this.description}}
+{{link this.type}}: {{{renderContent this.description}}}
 
 {{/each}}
 {{/if}}
+
+{{> docDetailsPartial}}
 {{/documentablePartialTemplate}}
 
 {{#unless @last}}---{{/unless}}
@@ -1924,6 +2018,7 @@ const fieldsPartialTemplate = `
 {{ heading type.headingLevel type.heading }}
 {{link type.value}}
 
+{{> docDetailsPartial}}
 {{/documentablePartialTemplate}}
 
 {{#unless @last}}---{{/unless}}
@@ -2136,6 +2231,7 @@ const templateHelpers = {
 class Template {
   constructor() {
     Handlebars.registerPartial("typeDocumentation", typeDocPartial);
+    Handlebars.registerPartial("docDetailsPartial", docDetailsPartial);
     Handlebars.registerPartial("documentablePartialTemplate", documentablePartialTemplate);
     Handlebars.registerPartial("methodsPartialTemplate", methodsPartialTemplate);
     Handlebars.registerPartial("constructorsPartialTemplate", constructorsPartialTemplate);
@@ -2622,11 +2718,9 @@ class Manifest {
     return accessAndDocAware.filter((type) => this.shouldFilterType(type, modifiers));
   }
   static shouldFilterType(accessAndDocAware, modifiers) {
-    var _a;
-    const hasIgnoreDocAnnotation = (_a = accessAndDocAware.docComment) == null ? void 0 : _a.annotations.some(
-      (annotation) => annotation.name.toLowerCase() === "ignore"
-    );
-    if (hasIgnoreDocAnnotation) {
+    const docComment = accessAndDocAware.docComment;
+    const isExcluded = (docComment == null ? void 0 : docComment.hidden) === true || (docComment == null ? void 0 : docComment.annotations.some((annotation) => annotation.name.toLowerCase() === "ignore"));
+    if (isExcluded) {
       return false;
     }
     return modifiers.includes(accessAndDocAware.access_modifier) || accessAndDocAware.annotations.some((annotation) => modifiers.includes(annotation.type.toLowerCase()));

package/dist/index.d.ts

@@ -87,6 +87,7 @@ type Translations = {
             author: string;
             date: string;
             see: string;
+            deprecated: string;
             possibleValues: string;
             parameters: string;
             throws: string;
@@ -198,9 +199,12 @@ type RenderableDocumentation = {
   customTags?: CustomTag[];
   example?: RenderableSection<RenderableContent[] | undefined>;
   group?: string;
+  /** The first author. Kept for backwards compatibility with custom templates; prefer `authors`. */
   author?: string;
+  authors?: string[];
   date?: string;
   sees?: StringOrLink[];
+  deprecated?: { description?: RenderableContent[] };
 };
 
 type RenderableType = {

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var errorCollector = require('./error-collector-D5Q2hGFS.js');
+var errorCollector = require('./error-collector-DagrtuR3.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.24.0-beta.3",
+  "version": "3.24.0",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "engines": {
     "node": ">=22.12.0"
@@ -96,7 +96,7 @@
     ]
   },
   "dependencies": {
-    "@cparra/apex-reflection": "4.0.0-beta.3",
+    "@cparra/apex-reflection": "4.0.0",
     "@salesforce/source-deploy-retrieve": "^12.20.1",
     "@types/js-yaml": "^4.0.9",
     "@types/yargs": "^17.0.32",