@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

package/dist/defaults-DGKfeZq-.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const defaults = {
+  targetGenerator: "markdown",
+  targetDir: "./docs/",
+  scope: ["global"],
+  defaultGroupName: "Miscellaneous",
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+  linkingStrategy: "relative"
+};
+
+exports.defaults = defaults;

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { SetOptional } from 'type-fest';
+
+/**
+ * The configurable hooks that can be used to modify the output of the generator.
+ */
+type ConfigurableHooks = {
+  transformReferenceGuide: TransformReferenceGuide;
+  transformDocs: TransformDocs;
+  transformDocPage: TransformDocPage;
+  transformReference: TransformReference;
+};
+
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
+type UserDefinedMarkdownConfig = {
+  targetGenerator: 'markdown';
+  sourceDir: string;
+  targetDir: string;
+  scope: string[];
+  defaultGroupName: string;
+  namespace?: string;
+  sortMembersAlphabetically: boolean;
+  includeMetadata: boolean;
+  linkingStrategy: LinkingStrategy;
+} & Partial<ConfigurableHooks>;
+
+type SourceFileMetadata = {
+  filePath: string;
+  name: string;
+  type: 'interface' | 'class' | 'enum';
+};
+
+type DocPageReference = {
+  source: SourceFileMetadata;
+  // The name under which the type should be displayed in the documentation.
+  // By default, this will match the source.name, but it can be configured by the user.
+  displayName: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
+};
+
+type Frontmatter = string | Record<string, unknown> | null;
+
+type ReferenceGuidePageData = {
+  frontmatter: Frontmatter;
+  content: string;
+  outputDocPath: string;
+};
+
+type DocPageData = {
+  source: SourceFileMetadata;
+  group: string | null;
+  outputDocPath: string;
+  frontmatter: Frontmatter;
+  content: string;
+};
+
+/**
+ * Represents a file to be skipped.
+ */
+type Skip = {
+  readonly _tag: 'Skip';
+};
+
+// Configurable Hooks
+
+type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
+
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
+
+/**
+ * Allows changing where the files are written to.
+ */
+type TransformReference = (
+  reference: DocPageReference,
+) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;
+
+/**
+ * Allows changing the frontmatter and content of the reference guide, or even if creating a reference
+ * guide will be skipped altogether.
+ */
+type TransformReferenceGuide = (
+  referenceGuide: ReferenceGuidePageData,
+) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;
+
+/**
+ * The main purpose if for allowing for doc pages to be skipped, but it can also be used to change the frontmatter
+ * and content of the doc pages.
+ */
+type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>;
+
+/**
+ * Allows changing the frontmatter and content of the doc pages.
+ */
+type TransformDocPage = (
+  doc: DocPageData,
+) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
+
+type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'>, 'targetGenerator'>;
+declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig;
+declare function skip(): Skip;
+
+export { type ConfigurableHooks, type DocPageData, type DocPageReference, type ReferenceGuidePageData, defineMarkdownConfig, skip };

package/dist/index.js

@@ -0,0 +1,36 @@
+'use strict';
+
+var defaults = require('./defaults-DGKfeZq-.js');
+
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+function defineMarkdownConfig(config) {
+  return __spreadProps(__spreadValues(__spreadValues({}, defaults.defaults), config), {
+    targetGenerator: "markdown"
+  });
+}
+function skip() {
+  return {
+    _tag: "Skip"
+  };
+}
+
+exports.defineMarkdownConfig = defineMarkdownConfig;
+exports.skip = skip;

package/eslint.config.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintConfigPrettier from "eslint-config-prettier";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintConfigPrettier);

package/examples/markdown/.forceignore

@@ -0,0 +1,12 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**

package/examples/markdown/config/project-scratch-def.json

@@ -0,0 +1,5 @@
+{
+  "orgName": "cesarparra company",
+  "edition": "Developer",
+  "features": []
+}

package/examples/markdown/docs/index.md

@@ -0,0 +1,109 @@
+# Apex Reference Guide
+
+## Miscellaneous
+
+### [BaseClass](miscellaneous/BaseClass.md)
+
+### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass.md)
+
+### [ParentInterface](miscellaneous/ParentInterface.md)
+
+### [ReferencedEnum](miscellaneous/ReferencedEnum.md)
+
+### [SampleException](miscellaneous/SampleException.md)
+
+This is a sample exception.
+
+### [SampleInterface](miscellaneous/SampleInterface.md)
+
+This is a sample interface
+
+### [Url](miscellaneous/Url.md)
+
+Represents a uniform resource locator (URL) and provides access to parts of the URL. 
+Enables access to the base URL used to access your Salesforce org. 
+ 
+## Usage 
+Use the methods of the `System.URL` class to create links to objects in your organization. Such objects can be files, images, 
+logos, or records that you want to include in external emails, in activities, or in Chatter posts. For example, you can create 
+a link to a file uploaded as an attachment to a Chatter post by concatenating the Salesforce base URL with the file ID: 
+ 
+```apex
+// Get a file uploaded through Chatter.
+ContentDocument doc = [SELECT Id FROM ContentDocument
+        WHERE Title = 'myfile'];
+// Create a link to the file.
+String fullFileURL = URL.getOrgDomainURL().toExternalForm() +
+'/' + doc.id;
+system.debug(fullFileURL);
+```
+
+ 
+The following example creates a link to a Salesforce record. The full URL is created by concatenating the Salesforce base 
+URL with the record ID. 
+ 
+```ape
+Account acct = [SELECT Id FROM Account WHERE Name = 'Acme' LIMIT 1];
+String fullRecordURL = URL.getOrgDomainURL().toExternalForm() + '/' + acct.Id;
+```
+
+ 
+## Example 
+In this example, the base URL and the full request URL of the current Salesforce server instance are retrieved. Next, a URL 
+pointing to a specific account object is created. Finally, components of the base and full URL are obtained. This example 
+prints out all the results to the debug log output. 
+ 
+```apex
+// Create a new account called Acme that we will create a link for later.
+Account myAccount = new Account(Name='Acme');
+insert myAccount;
+
+// Get the base URL.
+String sfdcBaseURL = URL.getOrgDomainURL().toExternalForm();
+System.debug('Base URL: ' + sfdcBaseURL );
+
+// Get the URL for the current request.
+String currentRequestURL = URL.getCurrentRequestUrl().toExternalForm();
+System.debug('Current request URL: ' + currentRequestURL);
+
+// Create the account URL from the base URL.
+String accountURL = URL.getOrgDomainURL().toExternalForm() +
+                       '/' + myAccount.Id;
+System.debug('URL of a particular account: ' + accountURL);
+
+// Get some parts of the base URL.
+System.debug('Host: ' + URL.getOrgDomainURL().getHost());
+System.debug('Protocol: ' + URL.getOrgDomainURL().getProtocol());
+
+// Get the query string of the current request.
+System.debug('Query: ' + URL.getCurrentRequestUrl().getQuery());
+```
+
+ 
+## Version Behavior Changes 
+In API version 41.0 and later, Apex URL objects are represented by the java.net.URI type, not the java.net.URL type. 
+The API version in which the URL object was instantiated determines the behavior of subsequent method calls to the 
+specific instance. Salesforce strongly encourages you to use API 41.0 and later versions for fully RFC-compliant URL 
+parsing that includes proper handling of edge cases of complex URL structures. API 41.0 and later versions also enforce 
+that inputs are valid, RFC-compliant URL or URI strings. 
+ 
+* [URL Constructors](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_constructors) 
+* [URL Methods](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_methods) 
+ 
+**See Also** 
+* [URL Class](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_url.htm)
+
+## Sample Enums
+
+### [SampleEnum](sample-enums/SampleEnum.md)
+
+This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum.md) . 
+ 
+This description has several lines
+
+## SampleGroup
+
+### [SampleClass](samplegroup/SampleClass.md)
+
+aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
+deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.

package/examples/markdown/docs/miscellaneous/BaseClass.md

@@ -0,0 +1,16 @@
+# BaseClass Class
+`abstract`
+
+## Namespace
+ns
+
+## Fields
+### `sampleEnumFromBase`
+
+#### Signature
+```apex
+public sampleEnumFromBase
+```
+
+#### Type
+[SampleEnum](../sample-enums/SampleEnum.md)

package/examples/markdown/docs/miscellaneous/MultiInheritanceClass.md

@@ -0,0 +1,72 @@
+# MultiInheritanceClass Class
+
+## Namespace
+ns
+
+**Inheritance**
+
+[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
+
+## Fields
+### `sampleEnumFromBase`
+
+*Inherited*
+
+#### Signature
+```apex
+public sampleEnumFromBase
+```
+
+#### Type
+[SampleEnum](../sample-enums/SampleEnum.md)
+
+## Properties
+### Group Name
+#### `someProperty`
+
+*Inherited*
+
+##### Signature
+```apex
+public someProperty
+```
+
+##### Type
+String
+
+## Methods
+### Available Methods
+#### `doSomething()`
+
+*Inherited*
+
+##### Signature
+```apex
+public void doSomething()
+```
+
+##### Return Type
+**void**
+
+### Deprecated Methods
+#### `sayHello()`
+
+*Inherited*
+
+`DEPRECATED`
+
+This is a sample method.
+
+##### Signature
+```apex
+public virtual String sayHello()
+```
+
+##### Return Type
+**String**
+
+A string value.
+
+##### Example
+SampleClass sample &#x3D; new SampleClass(); 
+sample.doSomething();

package/examples/markdown/docs/miscellaneous/ParentInterface.md

@@ -0,0 +1,15 @@
+# ParentInterface Interface
+
+## Namespace
+ns
+
+## Methods
+### `sampleParentMethod()`
+
+#### Signature
+```apex
+public void sampleParentMethod()
+```
+
+#### Return Type
+**void**

package/examples/markdown/docs/miscellaneous/ReferencedEnum.md

@@ -0,0 +1,8 @@
+# ReferencedEnum Enum
+
+## Namespace
+ns
+
+## Values
+| Value | Description |
+|-------|-------------|

package/examples/markdown/docs/miscellaneous/SampleException.md

@@ -0,0 +1,24 @@
+# SampleException Class
+
+This is a sample exception.
+
+**Usage** 
+
+You can use the exception the following way. 
+You can also take a look at [SampleClass](../samplegroup/SampleClass.md) to see how it is used. 
+This is a dangerous HTML tag: <script>alert('Hello');</script> 
+ 
+```apex
+try {
+   throw new SampleException();
+} catch (SampleException e) {
+  System.debug('Caught exception');
+}
+```
+
+## Namespace
+ns
+
+**Inheritance**
+
+Exception

package/examples/markdown/docs/miscellaneous/SampleInterface.md

@@ -0,0 +1,116 @@
+# SampleInterface Interface
+
+`NAMESPACEACCESSIBLE`
+
+This is a sample interface
+
+**Mermaid** 
+
+```mermaid
+graph TD
+   A[SampleInterface] -->|extends| B[ParentInterface]
+   B -->|extends| C[GrandParentInterface]
+   C -->|extends| D[GreatGrandParentInterface]
+```
+
+**Author** John Doe
+
+**Date** 2020-01-01
+
+**See** [SampleEnum](../sample-enums/SampleEnum.md)
+
+**See** [ReferencedEnum](ReferencedEnum.md)
+
+## Namespace
+ns
+
+## Example
+```apex
+SampleInterface sampleInterface = new SampleInterface();
+sampleInterface.sampleMethod();
+```
+
+**Extends**
+[ParentInterface](ParentInterface.md)
+
+## Methods
+### `sampleMethod()`
+
+`NAMESPACEACCESSIBLE`
+
+This is a sample method
+
+**Custom Tag** 
+
+This is a custom tag
+
+**Another Custom Tag** 
+
+This is another custom tag
+
+**Mermaid** 
+
+graph TD 
+A[SampleInterface] -->|extends| B[ParentInterface] 
+B -->|extends| C[GrandParentInterface] 
+C -->|extends| D[GreatGrandParentInterface]
+
+#### Signature
+```apex
+public String sampleMethod()
+```
+
+#### Return Type
+**String**
+
+Some return value
+
+#### Throws
+[SampleException](SampleException.md): This is a sample exception
+
+AnotherSampleException: This is another sample exception
+
+#### Example
+SampleInterface sampleInterface = new SampleInterface(); 
+sampleInterface.sampleMethod();
+
+---
+
+### `sampleMethodWithParams(param1, param2, theEnum)`
+
+`NAMESPACEACCESSIBLE`
+`DEPRECATED`
+
+This is a sample method with parameters 
+Sometimes it won't be possible to find a NonExistent link.
+
+#### Signature
+```apex
+public SampleEnum sampleMethodWithParams(String param1, Integer param2, SampleEnum theEnum)
+```
+
+#### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| param1 | String | This is the first parameter |
+| param2 | Integer | This is the second parameter |
+| theEnum | [SampleEnum](../sample-enums/SampleEnum.md) | This is an enum parameter |
+
+#### Return Type
+**[SampleEnum](../sample-enums/SampleEnum.md)**
+
+Some return value
+
+---
+
+### `sampleParentMethod()`
+
+*Inherited*
+
+#### Signature
+```apex
+public void sampleParentMethod()
+```
+
+#### Return Type
+**void**