From 59c906417530d7b70ef93bbb7b9d687ea5d64b9e Mon Sep 17 00:00:00 2001
From: Xinyi Feng <xfeng@adobe.com>
Date: Fri, 9 Aug 2024 10:34:19 -0700
Subject: [PATCH] add comments

---
 src/index.js | 66 ++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 5 deletions(-)

diff --git a/src/index.js b/src/index.js
index ccf7172..70284b0 100644
--- a/src/index.js
+++ b/src/index.js
@@ -10,6 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
+/**
+ * Sets debug mode based on the URL and plugin options.
+ * @param {Object} url object containing the URL properties
+ * @param {Object} pluginOptions with default options and custom options
+ * @returns {Boolean} whether debug mode is enabled
+ */
 let isDebugEnabled;
 export function setDebugMode(url, pluginOptions) {
   const { host, hostname, origin } = url;
@@ -22,6 +28,9 @@ export function setDebugMode(url, pluginOptions) {
   return isDebugEnabled;
 }
 
+/**
+ * Logs a debug message
+ */
 export function debug(...args) {
   if (isDebugEnabled) {
     // eslint-disable-next-line no-console
@@ -29,6 +38,11 @@ export function debug(...args) {
   }
 }
 
+/**
+ * Default options for the plugin.
+ * could be adjusted by passing new options
+ * e.g. 'abtest' instead of 'experiment', 'sale' instead of 'campaign'
+ */
 export const DEFAULT_OPTIONS = {
 
   // Audiences related properties
@@ -199,10 +213,11 @@ function getAllSectionMeta(block, scope) {
 }
 
 /**
- * Replaces element with content from path
- * @param {String} path
- * @param {HTMLElement} el
- * @return Returns the path that was loaded or null if the loading failed
+ * Replaces the inner content of an element with content from a specified path.
+ * @param {String} path - the path to load the content from
+ * @param {HTMLElement} el - the element to replace the content of
+ * @param {String} selector - taget CSS selector
+ * @return The path that was loaded or null if the loading failed
  */
 async function replaceInner(path, el, selector) {
   try {
@@ -516,6 +531,7 @@ async function applyAllModifications(
       }
     }));
 
+  // Fragment-level modifications
   if (pageMetadata.manifest) {
     let entries = await getManifestEntriesForCurrentPage(pageMetadata.manifest);
     if (entries) {
@@ -537,6 +553,12 @@ async function applyAllModifications(
   return configs;
 }
 
+/**
+ * Aggregates the entries into a single object.
+ * @param {String} type experiment, campaign or audience
+ * @param {String[]} allowedMultiValuesProperties properties that can have multiple values
+ * @returns object with the aggregated entries
+ */
 function aggregateEntries(type, allowedMultiValuesProperties) {
   return (entries) => entries.reduce((aggregator, entry) => {
     Object.entries(entry).forEach(([key, value]) => {
@@ -672,7 +694,9 @@ async function getExperimentConfig(pluginOptions, metadata, overrides) {
 }
 
 /**
- * Parses the campaign manifest.
+ * Parses the experiemnt manifest
+ * @param {Object} entries fragment manifest entries
+ * @returns {Object} parsed fragment manifest that grouped by experiment
  */
 function parseExperimentManifest(entries) {
   return Object.values(Object.groupBy(
@@ -687,6 +711,11 @@ function getUrlFromExperimentConfig(config) {
     : null;
 }
 
+/**
+ * Runs the experiment on the page, applies all modifications.
+ * Sets up necessary data attributes, class names,
+ * and dispatches custom events for further handling if needed.
+ */
 async function runExperiment(document, pluginOptions) {
   return applyAllModifications(
     pluginOptions.experimentsMetaTagPrefix,
@@ -784,12 +813,20 @@ function parseCampaignManifest(entries) {
     });
 }
 
+/**
+ * Gets the URL from the campaign config
+ */
 function getUrlFromCampaignConfig(config) {
   return config.selectedCampaign
     ? config.configuredCampaigns[config.selectedCampaign]
     : null;
 }
 
+/**
+ * Runs the campaign on the page, applies all modifications.
+ * Sets up necessary data attributes, class names,
+ * and dispatches custom events for further handling if needed.
+ */
 async function runCampaign(document, pluginOptions) {
   return applyAllModifications(
     pluginOptions.campaignsMetaTagPrefix,
@@ -866,12 +903,20 @@ function parseAudienceManifest(entries) {
     });
 }
 
+/**
+ * Gets the URL from the audience config
+ */
 function getUrlFromAudienceConfig(config) {
   return config.selectedAudience
     ? config.configuredAudiences[config.selectedAudience]
     : null;
 }
 
+/**
+ * Serves aduience on the page, applies all modifications.
+ * Sets up necessary data attributes, class names,
+ * and dispatches custom events for further handling if needed.
+ */
 async function serveAudience(document, pluginOptions) {
   document.body.dataset.audiences = Object.keys(pluginOptions.audiences).join(',');
   return applyAllModifications(
@@ -901,6 +946,12 @@ async function serveAudience(document, pluginOptions) {
   );
 }
 
+/**
+ *  Loads and initializes plugins and functionalities eagerly,
+ *  Asynchronously loads audiences, experiments, and campaigns.
+ * @param {Document} document  The HTML document to be processed
+ * @param {Object} [options={}] Configuration options pasesd from script.js
+ */
 export async function loadEager(document, options = {}) {
   const pluginOptions = { ...DEFAULT_OPTIONS, ...options };
   setDebugMode(window.location, pluginOptions);
@@ -916,14 +967,19 @@ export async function loadEager(document, options = {}) {
   ns.campaign = ns.campaigns.find((e) => e.type === 'page');
 }
 
+/**
+ * Loads the experimentation pill when debug mode is enabled
+ */
 export async function loadLazy(document, options = {}) {
   const pluginOptions = { ...DEFAULT_OPTIONS, ...options };
   // do not show the experimentation pill on prod domains
   if (!isDebugEnabled) {
     return;
   }
+  // fetch the central-host preview script from github pages
   // eslint-disable-next-line import/no-unresolved
   const preview = await import('https://opensource.adobe.com/aem-experimentation/preview.js');
+  // functions to be passed to the preview script
   const context = {
     getMetadata,
     toClassName,